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.