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.