Agent Teams

Parallel multi-agent playbook (lead-side)

This skill is the lead/orchestrator's reference for fanning out parallel work. Only the lead orchestrates and spawns — workers implement and report back.

1. Fan out only when work is genuinely parallel

Parallel agents cost significantly more tokens than one session (each is a full Claude instance). Reach for fan-out only when parts are independent and run at the same time:

• N independent modules/files with no shared edits
• multi-lens review (security / performance / tests) at once
• debugging with competing hypotheses
• backend + frontend that must agree on a contract

For sequential work (plan → build → ship), a dependency chain, or same-file edits, do NOT fan out — run it through the feature-workflow skill, whose delegated execute spawns one step-executor per step on the session's own branch. The value here is the parallel execution phase only.

2. Pick the mechanism (this is the important decision)

| Mechanism | Use when | Coordination | Cost / overhead | |-----------|----------|--------------|-----------------| | Background subagents (DEFAULT) | independent units; contracts known up front | none — contract pre-specified in each prompt | low; in-process, no setup | | Workflows | large fan-out (10s+), deterministic/repeatable orchestration, cross-checking/voting, resumable runs | script variables | medium; you write/run a script | | Named teammates (experimental, almost never needed) | you must dialogue live with a delegated agent running in parallel, off the master tab, AND a shared tree is acceptable | live SendMessage cross-talk | high; iTerm2 panes, separate processes, manual teardown |

Default to background subagents (Agent tool, no name). team-executor sets background: true in its frontmatter — the documented way to make a subagent always run in the background; for ad-hoc spawns say "in the background" (run_in_background: true on the Agent call also works on current builds). They run in-process under the lead (no separate OS process, no iTerm2 pane), need no shutdown handshake, and deliver a clean completion notification. Pre-specify any cross-unit contract in each spawn prompt so they never need to talk to each other.

Reach for Workflows when the fan-out is large or you want deterministic, repeatable, resumable orchestration with built-in cross-checking. (In this kit only the lead runs Workflows — the worker roles' tools lists deliberately omit the Workflow and Agent tools, so they can't fan out on their own. That's a kit choice, not a platform rule: since v2.1.172 a subagent whose tools includes Agent can spawn nested subagents, up to 5 levels deep.)

Reach for named teammates almost never. The only case they earn their keep: you want to dialogue live with a delegated agent running in parallel, off the master tab — and you accept that teammates are not isolated in worktrees (Claude Code does not honor isolation: worktree for teammates; they share the lead's checkout, so you must partition files by hand). Note what does NOT qualify: a planning gate. /autoplan runs in the lead (interactive there), and any input a delegated subagent needs is bubbled up to the lead — so the master already funnels approvals to you. Agent-to-agent contract negotiation doesn't qualify either: pre-specify the contract in each spawn prompt instead. This is the heaviest path; see §"Named-teammate path".

> Documented: teammates are not worktree-isolated. isolation: worktree is > a subagent feature; a definition spawned as a teammate keeps only its > tools and model, and the isolation is silently dropped (docs: > "Agent teams don't isolate teammates in worktrees, so partition the work so > each teammate owns a different set of files"). Spawning the executors as > named teammates once put all four in the same checkout committing to main, > clobbering each other. Background subagents are the safe default precisely > because they CAN get real worktrees when they need them.

3. Worktree isolation: every concurrent writer gets one

You're in this skill because the fan-out decision already came back "parallel" — that call is made before agent-teams loads, per the global CLAUDE.md rule ("Inside a pipeline, delegation is the default … If one subagent can do it, use one") and feature-workflow's "When to offer (lead only)" bullet. So within a fan-out the rule is simple: writers that run concurrently get isolation: worktree each — even if the plan says their files are disjoint. Read-only fan-out (review, research, multi-lens analysis) never gets a worktree, regardless of count — nothing is written, so isolation is pure overhead.

You don't decide this per spawn. team-executor carries isolation: worktree in its own frontmatter, so every executor gets a worktree whether or not the spawning prompt remembers to ask. That's deliberate: the decision was already made when you picked the parallel path, and a rule that has to be re-derived at each spawn is a rule that gets skipped.

If you get here with only one writer, that's not an agent-teams run. It means the fan-out decision was wrong or skipped — stop, and hand the work to feature-workflow's sequential delegated execute, which spawns step-executor on the session's own branch with no worktree and nothing to merge.

Set worktree.baseRef to "head" before the first fan-out. Subagent worktrees branch from the repository's remote default branch unless you change this — so with the default ("fresh"), every executor starts from a clean origin/main that has neither docs/prompts/-plan.md nor any of the session's in-progress commits, and the merger then drags main↔branch divergence into each unit. settings.example.json ships {"worktree": {"baseRef": "head"}}; the docs name this exact case ("use this when isolating subagents that need to operate on in-progress work" — docs). A worktree is also a fresh checkout, so gitignored files don't come along — add a .worktreeinclude if executors need .env or similar to run tests.

Why "disjoint files" isn't a safe reason to skip worktrees with 2+ writers. Disjointness isn't knowable at spawn time. (Observed, 20 sessions reviewed): of 3 genuinely-parallel execute batches, 2 collided — in claude-watch, units U0+U3 and separately U2+U5 all edited the CLI entrypoint despite being planned as independent. A new unit usually has to register itself in some hub file (a dispatcher, router, barrel export, package.json) that the plan assigned to nobody. Only one batch (wizards U1/U2) was genuinely clean. Plan around this: if units keep colliding on a hub file, give that file to one unit instead of isolating three agents that all want to edit it — prefer fewer, larger units over more, smaller colliding ones.

Why review needs a separable diff. team-reviewer reviews "its worktree diff" and team-merger merges each unit in turn after approval; the global /codex merge gate forbids merging a step until that step's diff has been reviewed. With 2+ concurrent writers sharing one checkout there is no per-unit diff to review or merge independently, and a unit that fails review can't be dropped without untangling it from the others it shares a tree with.

> Deliberate deviation (from the platform docs' file-overlap test): the > docs key worktree isolation to > whether tasks touch the same files. This kit keys it to concurrent-writer > count instead — a stricter test (a superset of the docs' cases): even units > with disjoint files get worktrees the moment 2+ of them write at the same > time, because disjointness can't be verified at spawn time and review needs a > separable diff either way.

Clean up after merge — nothing else will. Once a unit lands, the merger removes its worktree (git worktree remove) and deletes the merged branch (git branch -d) immediately after each successful merge. That is not a tidiness step: neither platform cleanup path ever reclaims an executor worktree. Claude Code auto-removes a subagent worktree only if the subagent made no changes, and the periodic cleanupPeriodDays sweep skips any worktree still holding work — changed files, untracked files, or unpushed commits — which describes every executor worktree by construction, since executors commit locally and never push (docs). If the merger doesn't remove it, it stays until someone runs git worktree remove --force by hand. For a run that dies before the merger gets there, the backstop is the /goal completion condition below ("no feature worktrees/branches remain"). The net result: nothing lingers on disk once work is merged, and there is no pane or process to tear down.

The pipeline

1. PLAN      (subagent drafts → LEAD runs /autoplan, interactive)
   → team-planner subagent (opus) writes the ROUGH plan to
     docs/prompts/-plan.md and returns it — it does NOT run /autoplan
   → the LEAD runs /autoplan **itself** (interactive): the user answers its
     option-picks in the master tab; /autoplan spawns its own review subagents,
     so the heavy reads stay off the lead. Then surface the refined plan and
     wait for the user's approval.   ← only gate
2. PROMPTS   (subagent: team-prompt-smith, sonnet)
   → turns the approved plan into one self-contained spawn prompt per unit
3. EXECUTE   (background subagents: team-executor)   ← parallel
   → lead spawns one background subagent per independent unit; each gets a
     worktree from team-executor's own `isolation: worktree` frontmatter, not
     from the spawn call; contracts are pre-specified in each prompt
4. REVIEW    (subagent: team-reviewer, opus — read-only, NO worktree)
   → adversarially verifies each unit's diff before it lands
5. MERGE     (subagent: team-merger, sonnet)
   → merges each approved worktree into the base branch; after each successful
     merge removes that worktree + deletes its branch; reports completion

Every step delegates to a subagent except the lead's own /autoplan pass in step 1; step 3 is the only fan-out (one background subagent per unit). Keep the lead thin: it coordinates, runs /autoplan, and ingests summaries — it does not read large diffs or implement. If the lead starts implementing, stop and delegate.

Subagents are headless — they never prompt the user. A subagent runs to completion and hands its result back; it has no channel to ask you anything mid-run. So never delegate an interactive gate to one — /autoplan surfaces option-picks, but run in a spawned/headless session it detects that and auto-picks the recommended option silently, so the user never sees the questions. Interactive skills run in the lead (the session you're attached to); only headless work goes to subagents. (This is why step 1 splits: the subagent drafts headlessly, the lead runs /autoplan interactively.)

(For the rare named-teammate path, step 3's agents are teammates instead and a TEARDOWN step is required — see §"Named-teammate path".)

Approval gate: PLAN ONLY

The lead must get the user's approval on the plan (step 1) before any fan-out. The lead runs /autoplan itself (interactive) — never a subagent, which would run headless and silently auto-pick instead of surfacing the option-picks. Surface the refined plan, name the open taste-decisions, wait. After the plan is approved, executors run, review runs, and the merger lands work and reports completion — no further user gates.

Driving the tail with /goal

The approved tail (EXECUTE → REVIEW → MERGE) has a verifiable end state, which is exactly what /goal is for. Instead of the lead deciding turn-by-turn when the fan-out is "done" (the same model that did the work judging its own completion), set a completion condition and let a fresh evaluator confirm it after every turn. This makes the tail both more autonomous (no per-turn return to the user) and higher quality (an independent model catches a lead that quit early or merged on a red suite).

/goal is user-typed input — the lead cannot invoke it. Right after the user approves the plan, the lead prints this command ready to paste (filled in with the real plan path, base branch, and bound) and asks the user to fire it in the lead:

/goal All units in docs/prompts/-plan.md are merged to ;
team-reviewer approved each diff and `/codex review` reports zero
real-or-regression findings on each unit's diff; the project's test suite (whatever the repo
uses — pytest, npm test, go test, cargo test, …) exits 0 with its output shown;
git status is clean and no feature worktrees/branches remain; or stop after 25 turns.

For the review fix-loop specifically:

/goal team-reviewer and `/codex review` both report zero real-or-regression findings
on every unit's diff, with the verdicts pasted in full each round; or stop after
3 rounds, reporting anything unresolved.

Rules for goals here:

• Only the verifiable tail. Never put a goal on PLAN — that gate is interactive

and taste-based (see "Approval gate: PLAN ONLY"). A goal can't judge taste and the evaluator can't surface option-picks.

• The evaluator sees only the transcript and runs no tools. So the merger and

reviewer must return machine-checkable proof — test exit code + output tail, git worktree list / git status, a structured per-unit verdict — not a prose "done". The role definitions require this; honor it or the goal can't be judged.

• Always bound it (or stop after N turns): a fan-out loop burns tokens fast.
• Pair with auto mode so each goal turn runs without per-tool prompts.
• Headless: claude -p "/goal …" runs the whole tail to completion in one

unattended invocation — an "approve the plan, walk away" mode for this kit.

Models + effort per role

Per-role model: and effort: come from the agent definition files and are honored when the role runs as a subagent. Effort deviates from the model default: judgment roles go up, high-volume roles go down to save tokens.

| Role | Spawned as | Model | Effort | Rationale | |------|-----------|-------|--------|-----------| | Orchestrator (lead) | main session | Opus | session default | coordination, synthesis, user gate | | team-planner | subagent | Opus | high | one pass, highest leverage (Opus 5: prior-model effort defaults don't transfer; high is the sweet spot) | | team-prompt-smith | subagent | Sonnet | medium | structured prompt writing | | team-executor | background subagent | Sonnet (Opus for hard units) | medium | token-heavy fan-out | | team-reviewer | subagent | Opus | high | adversarial bug-hunting (Opus 5 review stays accurate at lower effort) | | team-merger | subagent | Sonnet | medium | mechanical merge/verify | | researcher | subagent | (use built-in Explore) | — | broad reads, no custom file |

Override per spawn when a unit is unusually hard: "spawn this executor on Opus at high effort". As background subagents these roles honor their effort: frontmatter; the named-teammate path may ignore per-teammate effort and fall back to the session default — harmless.

Spawn recipes

Plan (subagent drafts, lead refines), then gate: > Use the team-planner agent to write a ROUGH implementation plan for > to docs/prompts/-plan.md and return it — it must NOT run /autoplan. > Then I (the lead) run /autoplan myself, interactively, so the user answers its > option-picks; I'll get the user's approval before any execution.

Fan out execution (background subagents that write + merge → worktree), after approval: > Spawn one team-executor as a background subagent per unit in

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TurboKach
• Source: TurboKach/claude-code-setup
• License: MIT

Install and usage instructions live in the source repository linked above.