Agent Teams
Multi-agent orchestration with explicit topologies, tool restrictions, worktree isolation, and lifecycle management.
When to use a team vs solo
| Signal |
Go team |
| Task has 3+ independent subtasks |
yes |
| Quality-critical (security, compliance) |
yes (adds reviewer) |
| Cross-cutting refactor touching many files |
yes |
| Debug with multiple plausible hypotheses |
yes (competing-hypotheses) |
| Straightforward feature in one module |
no (solo is cheaper) |
| Time-sensitive (parallel beats serial) |
yes |
Rough guideline: team cost = 1.5–6× solo, so reserve teams for tasks where the parallel-or-specialist value justifies it.
Five ready-made topologies (fetch via MCP)
| Topology |
Size |
When |
architect-implementer-reviewer |
3 (2 Opus + 1 Sonnet) |
Medium-to-large features with non-trivial design |
frontend-backend-test-squad |
4 (3 Sonnet + 1 Opus) |
Full-stack features with clear UI/API/test split |
competing-hypotheses-debug |
4 (3 Sonnet parallel + 1 Opus synth) |
Bugs with multiple plausible causes |
security-performance-test-review-board |
4 parallel Sonnet |
PR reviews where discipline specialists are cheaper than generalist |
docs-migration-sprint |
4 (3 Sonnet writers + 1 Opus editor) |
Large doc migrations (framework version bumps, brand renames) |
Fetch full kit via cc_kb_topology_kit(name) — includes composition, file ownership, coordination protocol, cost estimate, anti-patterns.
Shortlist for a specific task: cc_docs_team_topology_recommend(task, complexity, team_size).
Role-based subagents (general-purpose)
These agents are topology-agnostic — plug them into any topology:
| Agent |
Model |
Tools |
cc-implementer |
Sonnet |
Read, Edit, Write, Bash, Grep, Glob |
cc-debugger |
Opus |
Read, Grep, Glob, Bash (hypothesis protocol) |
cc-migration-lead |
Opus |
Read + writes migration plan before any code |
cc-dependency-auditor |
Haiku |
Bash (pnpm/pip/cargo audit only) |
cc-release-coordinator |
Sonnet |
Read, Write, Bash (semver + changelog + tag) |
cc-audit-reviewer |
Opus |
Read, Grep, Glob (second-round review) |
cc-security-compliance-advisor |
Opus |
Read, Grep, Glob, Bash (compliance scan) |
cc-principal-engineer-strategist |
Opus |
Read, Grep, Glob (deep analysis) |
cc-council-coordinator |
Opus |
Agent, Read (fan-out/fan-in) |
cc-team-orchestrator |
Opus |
Agent, Read, Write (delegation + lifecycle) |
Coordination protocols
| Protocol |
Use |
| Serial (chain) |
Phase N+1 needs phase N's output verbatim (architect → implementer → reviewer) |
| Parallel (fan-out) |
Subtasks are independent; merge at end (review board, competing hypotheses) |
| Blackboard |
Agents read each other's evolving notes; coordinator synthesizes (council review) |
| Orchestrator-workers |
Lead agent decomposes and spawns workers dynamically |
Worktree isolation
Parallel agents often need isolated working copies to prevent interference. Use isolation: "worktree" on the Agent tool call, or manually git worktree add before launching.
When to isolate:
- Parallel agents all edit the same file → yes, isolate
- Parallel agents investigate (read-only) → no, shared repo is fine
- Agents share state via a coordinator file (blackboard) → no isolation, but strict write-discipline
Coordination mechanics (current Agent-tool surface)
| Need |
How |
| Spawn a teammate |
Agent tool with subagent_type, model, and a focused prompt. A built-in general-purpose agent is always available. |
| Address it later with context intact |
give it a name/team_name, then SendMessage to that name/ID — a fresh Agent call instead starts a new context. |
| Run non-blocking |
run_in_background: true (tool) / background: true (frontmatter); you're notified on completion. Launch independent agents in one message to run them concurrently. |
| Isolate the working copy |
isolation: "worktree" (see below). |
| Require a plan before it acts |
mode: "plan" on the spawn. |
| Cap runaway loops |
maxTurns in the agent definition. |
The agent's final message is the only thing returned to the parent — relay what matters; the
user doesn't see a teammate's transcript. Keep spawn prompts under ~400 words and prefer named
specialists over generics (see cc-prompt-budget-preflight).
Fable 5 for long-horizon coordinators. When a team runs for hours (overnight builds, multi-wave
migrations), put the coordinator on model: fable — Fable 5 reliably sustains ongoing messaging
with long-running async subagents and doesn't drift across waves the way smaller orchestrators can.
Workers stay on Sonnet; the tier premium (~2× Opus per token) only pays off on the coordinator
role. Old "don't over-delegate" guardrails written for prior models should be relaxed on Fable —
delegation is dependable there.
Lifecycle management
Long-running or idle agents waste tokens. cc-team-orchestrator agent handles this:
- Health check active agents periodically.
- Mark agents idle after N minutes of no activity.
- Clean up completed worktrees if the agent made no changes.
- Retain results (the agent's final message) for the coordinator even after cleanup.
MCP delegation
| Need |
Tool |
| Fetch a topology kit |
cc_kb_topology_kit(name) |
| Recommend a topology |
cc_docs_team_topology_recommend(task, complexity, team_size) |
| Model for each role |
cc_docs_model_recommend(task, budget) |
| Pattern for orchestration |
cc_kb_pattern_template(name) |
Anti-patterns
- Launching a team for a task a solo agent could finish in under 5 tool calls → overhead dominates.
- Parallel agents with identical system prompts → not actually parallel; just N×cost.
- No coordinator → each agent reports separately; user has to synthesize.
- Unbounded agent TTL → agents hang around consuming session tokens.
- Team cost estimate skipped → teams regularly exceed budget; always estimate first via
cc_docs_model_recommend.
1---2name: cc-agent-teams3description: Agent Teams4---56# Agent Teams78Multi-agent orchestration with explicit topologies, tool restrictions, worktree isolation, and lifecycle management.910## When to use a team vs solo1112| Signal | Go team |13|---|---|14| Task has 3+ independent subtasks | yes |15| Quality-critical (security, compliance) | yes (adds reviewer) |16| Cross-cutting refactor touching many files | yes |17| Debug with multiple plausible hypotheses | yes (competing-hypotheses) |18| Straightforward feature in one module | no (solo is cheaper) |19| Time-sensitive (parallel beats serial) | yes |2021Rough guideline: team cost = 1.5–6× solo, so reserve teams for tasks where the parallel-or-specialist value justifies it.2223## Five ready-made topologies (fetch via MCP)2425| Topology | Size | When |26|---|---|---|27| `architect-implementer-reviewer` | 3 (2 Opus + 1 Sonnet) | Medium-to-large features with non-trivial design |28| `frontend-backend-test-squad` | 4 (3 Sonnet + 1 Opus) | Full-stack features with clear UI/API/test split |29| `competing-hypotheses-debug` | 4 (3 Sonnet parallel + 1 Opus synth) | Bugs with multiple plausible causes |30| `security-performance-test-review-board` | 4 parallel Sonnet | PR reviews where discipline specialists are cheaper than generalist |31| `docs-migration-sprint` | 4 (3 Sonnet writers + 1 Opus editor) | Large doc migrations (framework version bumps, brand renames) |3233Fetch full kit via `cc_kb_topology_kit(name)` — includes composition, file ownership, coordination protocol, cost estimate, anti-patterns.3435Shortlist for a specific task: `cc_docs_team_topology_recommend(task, complexity, team_size)`.3637## Role-based subagents (general-purpose)3839These agents are topology-agnostic — plug them into any topology:4041| Agent | Model | Tools |42|---|---|---|43| `cc-implementer` | Sonnet | Read, Edit, Write, Bash, Grep, Glob |44| `cc-debugger` | Opus | Read, Grep, Glob, Bash (hypothesis protocol) |45| `cc-migration-lead` | Opus | Read + writes migration plan before any code |46| `cc-dependency-auditor` | Haiku | Bash (pnpm/pip/cargo audit only) |47| `cc-release-coordinator` | Sonnet | Read, Write, Bash (semver + changelog + tag) |48| `cc-audit-reviewer` | Opus | Read, Grep, Glob (second-round review) |49| `cc-security-compliance-advisor` | Opus | Read, Grep, Glob, Bash (compliance scan) |50| `cc-principal-engineer-strategist` | Opus | Read, Grep, Glob (deep analysis) |51| `cc-council-coordinator` | Opus | Agent, Read (fan-out/fan-in) |52| `cc-team-orchestrator` | Opus | Agent, Read, Write (delegation + lifecycle) |5354## Coordination protocols5556| Protocol | Use |57|---|---|58| **Serial (chain)** | Phase N+1 needs phase N's output verbatim (architect → implementer → reviewer) |59| **Parallel (fan-out)** | Subtasks are independent; merge at end (review board, competing hypotheses) |60| **Blackboard** | Agents read each other's evolving notes; coordinator synthesizes (council review) |61| **Orchestrator-workers** | Lead agent decomposes and spawns workers dynamically |6263## Worktree isolation6465Parallel agents often need isolated working copies to prevent interference. Use `isolation: "worktree"` on the Agent tool call, or manually `git worktree add` before launching.6667When to isolate:68- Parallel agents all edit the same file → yes, isolate69- Parallel agents investigate (read-only) → no, shared repo is fine70- Agents share state via a coordinator file (blackboard) → no isolation, but strict write-discipline7172## Coordination mechanics (current Agent-tool surface)7374| Need | How |75|---|---|76| Spawn a teammate | `Agent` tool with `subagent_type`, `model`, and a focused prompt. A built-in `general-purpose` agent is always available. |77| Address it later with context intact | give it a `name`/`team_name`, then **`SendMessage`** to that name/ID — a fresh `Agent` call instead starts a new context. |78| Run non-blocking | `run_in_background: true` (tool) / `background: true` (frontmatter); you're notified on completion. Launch independent agents in one message to run them concurrently. |79| Isolate the working copy | `isolation: "worktree"` (see below). |80| Require a plan before it acts | `mode: "plan"` on the spawn. |81| Cap runaway loops | `maxTurns` in the agent definition. |8283The agent's **final message is the only thing returned to the parent** — relay what matters; the84user doesn't see a teammate's transcript. Keep spawn prompts under ~400 words and prefer named85specialists over generics (see `cc-prompt-budget-preflight`).8687**Fable 5 for long-horizon coordinators.** When a team runs for hours (overnight builds, multi-wave88migrations), put the coordinator on `model: fable` — Fable 5 reliably sustains ongoing messaging89with long-running async subagents and doesn't drift across waves the way smaller orchestrators can.90Workers stay on Sonnet; the tier premium (~2× Opus per token) only pays off on the coordinator91role. Old "don't over-delegate" guardrails written for prior models should be relaxed on Fable —92delegation is dependable there.9394## Lifecycle management9596Long-running or idle agents waste tokens. `cc-team-orchestrator` agent handles this:97- Health check active agents periodically.98- Mark agents idle after N minutes of no activity.99- Clean up completed worktrees if the agent made no changes.100- Retain results (the agent's final message) for the coordinator even after cleanup.101102## MCP delegation103104| Need | Tool |105|---|---|106| Fetch a topology kit | `cc_kb_topology_kit(name)` |107| Recommend a topology | `cc_docs_team_topology_recommend(task, complexity, team_size)` |108| Model for each role | `cc_docs_model_recommend(task, budget)` |109| Pattern for orchestration | `cc_kb_pattern_template(name)` |110111## Anti-patterns112113- Launching a team for a task a solo agent could finish in under 5 tool calls → overhead dominates.114- Parallel agents with identical system prompts → not actually parallel; just N×cost.115- No coordinator → each agent reports separately; user has to synthesize.116- Unbounded agent TTL → agents hang around consuming session tokens.117- Team cost estimate skipped → teams regularly exceed budget; always estimate first via `cc_docs_model_recommend`.
markus41