parallel-agent-orchestration

Parallel agent orchestration

The rest of sutra's guidance assumes one agent, one session, one working tree -- a single writer. Fan out concurrent agents against shared state and that assumption breaks silently: two agents open the same file, both edit, the second write clobbers the first, and you lose work or produce an un-mergeable tree with no error raised. Concurrency bugs do not announce themselves; you discover them at merge time or in production.

Pick an isolation regime BEFORE you fan out. Retrofitting coordination onto agents that are already running is how state gets corrupted.

The one hard rule

Never let two agents mutate the same file at the same time without either a mutex or separate worktrees. Every recipe below exists to enforce this single invariant. If you cannot name the mechanism that prevents a concurrent double-write, do not fan out yet -- run the work serially instead.

Choose the regime

One question decides everything: do the concurrent agents share a working tree?

• Yes -- they edit files in the same checkout -> Shared-state regime.
• No -- each owns an independent track with its own tree -> Disjoint regime.

When unsure, assume shared-state. It is the stricter of the two, and its machinery is a superset of what the disjoint regime needs.

Shared-state regime

Agents touch the same repository, so coordination is mandatory. Layer the five controls below; each closes a different collision path.

1. Give each agent its own git worktree

A worktree is the executable form of the hard rule. git worktree gives every agent an isolated checkout -- its own index and working files -- backed by one shared object store and history. Two agents editing "the same file" now edit two distinct paths; there is no in-place double-write to lose.

git worktree add ../wt-agent-a agent/track-a   # agent A's tree + branch
git worktree add ../wt-agent-b agent/track-b   # agent B's tree + branch

Each agent runs entirely inside its own worktree directory and commits to its own branch. An integrator merges the branches afterward, where real conflicts surface as ordinary, visible merge conflicts instead of silent clobbers. This is the default; reach for the finer-grained controls below only when agents must share one tree.