# Agent Teams

> Orchestration playbook for parallel multi-agent work in Claude Code. Use when fanning out genuinely parallel, independent work — N independent modules, multi-lens review, competing-hypothesis debugging, backend+frontend that must agree on a contract. Defaults to background subagents (with worktree isolation only when they write files in parallel and merge later); covers when to reach for Workflow…

- **Type:** Skill
- **Install:** `agentstack add skill-turbokach-claude-code-setup-agent-teams`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TurboKach](https://agentstack.voostack.com/s/turbokach)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TurboKach](https://github.com/TurboKach)
- **Source:** https://github.com/TurboKach/claude-code-setup/tree/master/skills/agent-teams

## Install

```sh
agentstack add skill-turbokach-claude-code-setup-agent-teams
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://code.claude.com/docs/en/agents):
> "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](https://code.claude.com/docs/en/worktrees#choose-the-base-branch)).
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](https://code.claude.com/docs/en/agents) 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](https://code.claude.com/docs/en/worktrees#clean-up-subagent-and-background-session-worktrees)).
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](https://github.com/TurboKach)
- **Source:** [TurboKach/claude-code-setup](https://github.com/TurboKach/claude-code-setup)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-turbokach-claude-code-setup-agent-teams
- Seller: https://agentstack.voostack.com/s/turbokach
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.