Reference
Swarm mode.
Swarm mode parallelizes TDD across isolated worktrees. Decisions live in main context; the single subagent executes pre-decided recipes.
§ I
The principle
Decisions live in main context. Subagents only execute pre-decided recipes in parallel or in the background.
The main context owns architecture, scenario selection, and recipe design, work that depends on conversational visibility (screenshots, prior rounds, off-hand corrections). Subagents get a task brief and execute it. They do not design around it.
§ II
The single subagent
The baseline ships exactly one subagent: swarm-worker. Its job is narrow: run Skill(scenario) to write failing tests, then run Skill(implement) to make them pass, inside an isolated worktree.
It receives a fully-specified recipe from the main context and executes it verbatim. It does not pick abstractions, expand scope, or make architectural choices.
swarm-worker is sanctioned for use only inside /swarm-dispatch. Invoking it outside that path is a constitutional violation (Article II).
§ III
The pipeline
Three commands form the swarm path. The first two are decisions in main context; the third is the only place swarm-worker may run.
/swarm-plan
Decomposes an approved spec into a dependency-ordered set of tasks. Each task has a name, a write set (the exact source paths it may touch), a behavior contract, and a wave assignment. Tasks in the same wave have disjoint write sets and can run in parallel. Tasks in later waves depend on earlier-wave output.
/approve-swarm <slug>
Consent gate B, the second of three workflow-phase gates. The user types this command; Claude cannot invoke it. consent_gate_grant detects the command in the user's submission and writes a short-lived marker. swarm_approval_guard validates the marker before allowing the swarm-approval token to be written. Without a valid marker, the write is blocked.
/swarm-dispatch
Executes the approved swarm plan wave by wave. For each wave, the main context decides each task's recipe and spawns swarm-worker instances in parallel, each running inside an isolated git worktree (or under swarm_boundary_guard enforcement in shared mode). After each wave, a merge audit verifies write-set discipline before changes land. Waves proceed in dependency order; a failed wave stops further dispatch.
§ IV
When to swarm vs solo
The threshold is three or more independent components in the spec, where the dependency graph has at least two nodes with no cross-edge. Below that threshold, run /tdd solo.
The coordination overhead of /swarm-plan → /approve-swarm → /swarm-dispatch exceeds the parallelism benefit for small changes.
The threshold is configurable per project via project.json → swarm.min_tasks_worth_swarming. Default is 3.
§ V
Worktree isolation vs shared mode
When git is available, /swarm-dispatch creates a separate git worktree per task. Each worker writes only to its assigned worktree; the merge audit checks write-set membership before merging changes back.
Physical isolation means workers cannot accidentally touch each other's files.
When git is not available (a fresh directory with no repository), the harness falls back to shared mode. swarm_boundary_guard enforces write-set discipline at the Write boundary: any attempted write outside the declared write set is blocked before it lands. Shared mode is weaker than worktree isolation (no merge audit, no branch history) but functional for environments without git.
§ VI
Failure recovery
A failed wave stops further dispatch immediately. No subsequent waves run. The failed worktrees are preserved on disk for inspection.
The orchestrator does not auto-retry or auto-clean. The swarm-worker reports status: "failed" with a note; the main context decides whether to re-plan, fix the recipe, or escalate.
Even when a worker reports success, the merge audit runs against the worktree to verify the changes match the declared write set. A worker that wrote outside its set fails the audit, and its wave fails.