Different agents should not share the same tree

A hard problem with parallel agents

s09-s11 let you run multiple teammates simultaneously, but there's a hidden trap: they all share the same working directory. alice edits auth.py at the same time bob is editing auth.py - git conflicts, corrupted files, tests poisoning each other.

s12's solution is git worktree: the same repository, but with git worktree add you can checkout different branches into different directories. Each agent gets its own worktree, works in its own directory, and stays invisible to the others.

my-repo/                           # main workspace (lead uses this)
.worktrees/
  alice-auth/                      # alice's isolated directory
    (branch: wt/alice-auth)
  bob-api/                         # bob's isolated directory
    (branch: wt/bob-api)
  index.json                       # worktree registry
  events.jsonl                     # lifecycle event log

Two-plane separation of concerns

s12 explicitly splits the system into two planes:

• Control plane: the JSON files in .tasks/. A task is an abstract unit of "what to do", with dependencies, owner, and status.
• Execution plane: the directories in .worktrees/. A worktree is the physical container of "where to do it" - a directory plus a branch.

The two planes are bidirectionally linked via task.worktree and worktree.task_id.

This decoupling means you can: reuse the task management mechanism with a different execution environment (e.g. Docker containers instead of git worktrees). Or swap the task mechanism while reusing worktrees (e.g. a database instead of JSON files).

Lifecycle demo

Walk through the complete lifecycle: create task -> create worktree -> run commands -> keep or remove. Each step has an event log entry (events.jsonl), which is how production systems achieve observability.

keep vs remove

When a worktree has served its purpose, there are two endings:

• remove: git worktree remove --force - directory deleted, branch typically cleaned up. Equivalent to "this experiment didn't work out."
• keep: mark status: kept in .worktrees/index.json, physical directory preserved. Equivalent to "this result is worth keeping, pending merge."

Common pattern: subagent runs an experimental refactor -> good results -> keep -> human reviews -> merges to main -> manually removes. Bad results? Directly remove.