Orchestration

Orchestration

Patterns for coordinating multi-agent work in Claude Code using team mode.

Source: code.claude.com/docs/en/agent-teams

Quick Start

Tell the lead what team you want in natural language:

Create an agent team to refactor the auth module. Spawn three teammates:
- One focused on extracting shared utilities
- One migrating tests to the new structure
- One updating documentation
Use Sonnet for each teammate.

The lead creates the team, spawns teammates, distributes work via a shared task list, and synthesizes results.

How It Works

Teammates are persistent — they go idle between turns and can be woken up with messages. They can message each other directly.

Key Behaviours

• Lead spawns teammates based on your prompt — you describe the team, the lead creates it
• Teammates self-claim tasks from the shared list after finishing work
• No nested teams — teammates cannot spawn their own teams or teammates
• File partitioning — never assign the same file to multiple teammates
• 3-5 teammates is the sweet spot for most workflows
• 5-6 tasks per teammate keeps everyone productive

When Teams vs Subagents

References

• patterns.md - 6 orchestration patterns (fan-out, pipeline, map-reduce, speculative, background, task-graph)
• domains.md - 8 domain-specific decomposition guides
• task-management.md - Task dependencies, graph walking, file partitioning

Domain-Specific Decomposition

Task decomposition strategies by domain.

Decomposition strategies inspired by claude-sneakpeek by Mike Kelly.

Software Development

Plan-Parallel-Integrate

For feature implementation:

1. Plan (opus): Analyze requirements, define architecture, identify files 2. Parallel (sonnet x N): Implement components concurrently, one agent per module 3. Integrate (sonnet): Wire components together, resolve interfaces

Diagnose-Hypothesize-Fix

For bug fixing:

1. Diagnose (haiku x N): Gather logs, reproduce steps, collect context from multiple files 2. Hypothesize (opus): Analyze evidence, identify root cause 3. Fix (sonnet): Implement and verify fix

Code Review

Multi-Angle Review (Fan-Out)

Spawn separate reviewers for each concern:

• Security (sonnet): Auth, injection, data exposure
• Performance (sonnet): N+1 queries, memory leaks, unnecessary computation
• Correctness (sonnet): Business logic, edge cases, error handling
• Style (haiku): Naming, formatting, consistency with codebase patterns

Aggregate into single review with prioritized findings.

Testing

Generate-Run-Report (Pipeline)

1. Analyze (haiku): Read source, identify testable paths 2. Generate (sonnet): Write test cases covering happy path, edge cases, errors 3. Run (haiku): Execute tests, capture output 4. Report (haiku): Summarize results, flag failures

Documentation

Extract-Draft-Review

1. Extract (haiku x N): Read source files, gather types, interfaces, usage patterns 2. Draft (sonnet): Write documentation from extracted context 3. Review (haiku): Check accuracy against source, flag discrepancies

Refactoring

Audit-Plan-Execute

1. Audit (haiku x N): Scan codebase for target pattern (e.g., deprecated API usage) 2. Plan (opus): Group changes, identify dependencies, define migration order 3. Execute (sonnet x N): Apply changes per module, one agent per partition 4. Verify (haiku): Run tests, check no regressions

DevOps / Infrastructure

Diagnose-Remediate-Validate

1. Diagnose (haiku x N): Read logs, configs, CI output in parallel 2. Remediate (sonnet): Fix configuration, update pipeline 3. Validate (haiku): Run pipeline, verify fix

Research / Investigation

Breadth-then-Depth

1. Breadth (haiku x N): Fan-out search across multiple sources/files 2. Synthesize (opus): Identify key findings, rank by relevance 3. Depth (sonnet): Deep-dive on top findings

Data Analysis

Partition-Analyze-Merge (Map-Reduce)

1. Partition: Split dataset/files into chunks 2. Analyze (haiku x N): Process each chunk independently 3. Merge (sonnet): Combine results, resolve conflicts, produce summary

Orchestration Patterns

Detailed examples for each coordination pattern.

Fan-Out

Spawn N independent agents for parallel work. No communication between them.

Orchestrator
├── Agent A (security review)
├── Agent B (performance review)
├── Agent C (correctness review)
└── Agent D (style review)

When: Tasks are independent, results aggregated by orchestrator.

Example: PR review from multiple angles.

1. TaskCreate("Security review of auth changes")
2. TaskCreate("Performance review of query changes")
3. TaskCreate("Correctness review of business logic")
4. Spawn haiku agent per task with run_in_background=true
5. Collect results, synthesize into unified review

Model choice: haiku for simple reviews, sonnet for nuanced analysis.

Pipeline

Sequential agents where output feeds the next stage.

Research Agent → Planning Agent → Implementation Agent → Review Agent

When: Each stage depends on the previous stage's output.

Example: Feature implementation.

1. TaskCreate("Research existing auth patterns") → haiku
2. TaskCreate("Plan JWT migration", blockedBy: [1]) → opus
3. TaskCreate("Implement JWT auth", blockedBy: [2]) → sonnet
4. TaskCreate("Review implementation", blockedBy: [3]) → sonnet

Wait for each stage. Pass results via task description or file references.

Map-Reduce

Distribute work across N agents, then aggregate.

Orchestrator splits work
├── Agent A (files 1-5)
├── Agent B (files 6-10)
├── Agent C (files 11-15)
└── Orchestrator merges results

When: Same operation on many items, need unified output.

Example: Codebase-wide type audit.

1. List all files needing audit
2. Partition into chunks (5-10 files per agent)
3. Spawn sonnet agents per chunk: "Audit these files for type safety issues"
4. Collect per-chunk reports
5. Merge into single prioritized report

Key: Partition files cleanly. Never assign same file to multiple agents.

Speculative

Run competing approaches in parallel, pick the best.

Orchestrator
├── Agent A (approach: functional)
├── Agent B (approach: OOP)
└── Agent C (approach: procedural)
→ Compare outputs, select winner

When: Uncertain which approach is best. Budget allows parallel exploration.

Example: Algorithm optimization.

1. Spawn 3 sonnet agents with different strategies
2. Each writes solution to separate branch/file
3. Run benchmarks on each
4. Select best performer, discard others

Cost warning: Expensive pattern. Use only when approach uncertainty is high.

Background

Fire-and-forget for long tasks while continuing foreground work.

Orchestrator continues working
└── Background Agent (long-running task)
    → Notifies when done

When: Task is independent and non-blocking.

Example: Generate test suite while implementing feature.

1. Spawn sonnet agent: "Generate tests for the auth module" with run_in_background=true
2. Continue implementing feature in foreground
3. Check background task output when ready to integrate

Task Graph (DAG)

Most flexible pattern. Define tasks with dependency edges.

     ┌── B ──┐
A ───┤       ├── D ── E
     └── C ──┘

When: Complex projects with partial ordering.

Example: Full feature implementation.

TaskCreate("Research API requirements")           # Task 1
TaskCreate("Design database schema")              # Task 2
TaskCreate("Implement API endpoints", blockedBy: [1, 2])  # Task 3
TaskCreate("Write integration tests", blockedBy: [3])     # Task 4
TaskCreate("Update documentation", blockedBy: [3])        # Task 5 (parallel with 4)

Walk the graph:

1. Spawn agents for all unblocked tasks 2. When a task completes, check for newly unblocked tasks 3. Spawn agents for those 4. Repeat until all tasks resolved

This is the foundation pattern. All other patterns are special cases of a task graph.

Task Management Patterns

Effective use of TaskCreate/TaskUpdate/TaskList for orchestration.

Task management patterns inspired by claude-sneakpeek by Mike Kelly.

Task Lifecycle

pending → in_progress → completed
                      → deleted (if no longer needed)

• Set in_progress BEFORE spawning an agent for the task
• Set completed only when agent reports success
• Use deleted for tasks superseded by changed requirements

Dependency Patterns

Linear Chain

Task 1 → Task 2 → Task 3

TaskCreate("Step 1")  # id: 1
TaskCreate("Step 2")  # id: 2
TaskUpdate(id: 2, addBlockedBy: [1])
TaskCreate("Step 3")  # id: 3
TaskUpdate(id: 3, addBlockedBy: [2])

Diamond

    ┌── B ──┐
A ──┤       ├── D
    └── C ──┘

TaskCreate("A: Research")      # id: 1
TaskCreate("B: Frontend")      # id: 2, blockedBy: [1]
TaskCreate("C: Backend")       # id: 3, blockedBy: [1]
TaskCreate("D: Integration")   # id: 4, blockedBy: [2, 3]

Fan-Out (no merge)

A ──┬── B
    ├── C
    └── D

All of B, C, D depend on A but not on each other. No final merge step.

Task Descriptions

Write task descriptions as self-contained agent prompts:

Good:

Implement JWT token validation middleware in src/middleware/auth.ts.
Read the existing session-based auth in src/auth/session.ts for context.
Use jsonwebtoken package (already in package.json).
Export validateToken middleware function.
Write tests in src/middleware/__tests__/auth.test.ts.

Bad:

Do the JWT stuff we discussed.

Include:

• What to do (specific action)
• Where (file paths)
• Context (what to read first)
• Constraints (packages, patterns to follow)
• Deliverables (what files to create/modify)

Walking the Graph

Orchestrator loop:

1. TaskList → find tasks with status=pending, no blockedBy
2. For each unblocked task:
   a. TaskUpdate(status: in_progress, owner: agent-name)
   b. Spawn agent with task description
3. When agent completes → TaskUpdate(status: completed)
4. TaskList → check for newly unblocked tasks
5. Repeat until all tasks completed

Partitioning Files

When multiple agents work in parallel, partition files to avoid conflicts:

• By module: Agent A owns src/auth/, Agent B owns src/api/
• By layer: Agent A owns models, Agent B owns routes
• By feature: Agent A owns user flow, Agent B owns admin flow

State the partition explicitly in each agent's prompt:

You own these files exclusively: src/auth/jwt.ts, src/auth/middleware.ts
Do NOT modify any files outside this list.

Comments and Progress

Use task descriptions for context. When updating tasks:

• Update description to append progress notes if needed
• Create new follow-up tasks rather than overloading one task
• Keep task subjects short and scannable for TaskList output

Team Cleanup

When using teams with ccrecall for analytics:

• Sync before delete: Run bunx ccrecall sync BEFORE TeamDelete. Team config files at ~/.claude/teams/{name}/config.json are ephemeral — TeamDelete removes them, and ccrecall reads from those files to capture team members and their models.
• Order: Shutdown teammates → sync ccrecall → delete team
• If you skip sync: Team members, model assignments, and task data won't be recorded in ccrecall.db

Team vs Subagent Decision