CC-302: Orchestration Mastery

Learning Guide

Orchestration is the art of coordinating multiple agents to accomplish work that no single agent could do alone -- or could only do slowly and poorly. Where CC-301 covered individual agent types and capabilities, this module focuses on the conductor: the patterns and strategies for decomposing tasks, managing dependencies, aggregating results, and recovering from failures across a fleet of specialized agents.

Task Decomposition Strategies

Every orchestration begins with decomposition: breaking a large objective into subtasks that agents can execute. The quality of your decomposition directly determines the quality of your multi-agent outcome.

Functional Decomposition

Split by responsibility boundaries. A full-stack feature naturally decomposes into database, API, business logic, UI, and testing subtasks. Each maps to an agent with the right expertise and tool set. This is the most common and most intuitive decomposition strategy.

Data-Parallel Decomposition

When the same operation must be applied across many items -- auditing 50 API routes, migrating 200 components to a new pattern, reviewing changes across 12 packages -- you decompose by partitioning the data rather than the function. Each agent receives the same instructions but a different slice of the input.

Phase-Based Decomposition

Some tasks have natural sequential phases: explore, plan, implement, validate. Each phase can internally parallelize, but the phases themselves must execute in order because later phases depend on earlier outputs.

// Phase-based decomposition example
Phase 1: [Scout Agent] -> produces context map
Phase 2: [Plan Agent] -> receives context, produces task specs
Phase 3: [Impl Agent A, Impl Agent B, Impl Agent C] -> parallel execution
Phase 4: [Test Agent, Review Agent] -> parallel validation
Phase 5: [Merge Agent] -> integrates results

Dependency Graphs Between Agents

Not all subtasks are independent. Agent B may need Agent A's output. Agent C may need both A and B. Modeling these dependencies as a directed acyclic graph (DAG) lets you maximize parallelism while respecting ordering constraints.

The orchestrator's job is to walk the DAG: dispatch all agents whose dependencies are satisfied, wait for completions, and then dispatch the next wave. This is identical to how build systems (Make, Bazel) schedule compilation tasks.

• Level 0: No dependencies. Dispatch immediately in parallel.
• Level 1: Depends on Level 0 outputs. Dispatch after Level 0 completes.
• Level N: Depends on Level N-1. Continue until the DAG is fully executed.

Result Aggregation Patterns

When parallel agents complete, the orchestrator must combine their outputs into a coherent result. Several patterns apply:

• Concatenation: Simple assembly. Each agent's output is a section of the final result. Example: each agent writes a different file -- no aggregation needed beyond collecting the files.
• Merge: Outputs overlap and must be reconciled. Example: two agents modify the same configuration file from different worktrees. The orchestrator must resolve conflicts.
• Reduction: Outputs are summarized into a single value. Example: five agents each audit a set of routes and produce finding counts. The orchestrator sums them into a total.
• Validation-Gated: Implementation outputs are combined only if validation agents approve them. Failed validations trigger re-implementation rather than aggregation.

Error Handling and Recovery

Agents fail. They hit context limits, misinterpret prompts, produce incorrect code, or encounter unexpected states. Robust orchestration handles these failures gracefully.

Retry with Refined Context

The simplest recovery: re-dispatch the failed agent with a better prompt that includes the error information. If an agent's tests fail, give it the test output and ask it to fix the issue. Limit retries to prevent infinite loops -- two or three attempts is a reasonable ceiling.

Fallback to Alternative Agent

If a specialized agent fails, fall back to a general-purpose agent with broader capabilities. This trades efficiency for reliability.

Partial Completion

When one agent in a parallel batch fails but others succeed, the orchestrator can accept the partial result and either retry the failed subtask or flag it for human attention. Don't discard successful work because one agent stumbled.

// Error recovery pseudocode
result = dispatch(agent, task)
if result.failed:
    // Attempt 1: retry with error context
    result = dispatch(agent, task + error_context)
    if result.failed:
        // Attempt 2: escalate to general-purpose agent
        result = dispatch(general_agent, task + all_context)
        if result.failed:
            // Flag for human intervention
            report_failure(task, all_attempts)

The Conduct/Orchestration Skill Pattern

A powerful organizational pattern is to create a "conductor" skill -- a top-level prompt template that defines the entire multi-agent workflow. The conductor knows which agents to dispatch, in what order, with what prompts, and how to aggregate results. It acts as a reusable playbook for a specific class of tasks.

For example, a "feature-implementation" conductor might always follow: Scout, Plan, Implement (parallel), Test, Review, Merge. A "security-audit" conductor might follow: Enumerate, Scan (parallel), Analyze, Report. Encoding these patterns as conductor skills means you don't re-invent the orchestration logic every time.

Parallel vs. Sequential Execution Decisions

The decision framework is straightforward:

1. Are the tasks independent? If yes, parallelize. If no, sequence.
2. Do they modify overlapping files? If yes, use worktree isolation or sequence them.
3. Is ordering semantically important? Tests must run after implementation. Reviews should run after tests. Plan before implement.
4. What is the cost/benefit? Parallelizing two 5-second tasks saves 5 seconds. Parallelizing two 5-minute tasks saves 5 minutes. Prioritize parallelizing expensive operations.

Context Window Management Across Agents

Each agent has a finite context window. A poorly designed orchestration exhausts context with irrelevant information, leaving no room for the actual work. Several strategies manage this:

• Context Scoping: Give each agent only the context it needs. The database agent doesn't need UI component code. The test agent doesn't need the project README.
• Progressive Summarization: When passing results between phases, summarize rather than forwarding raw output. The Plan agent doesn't need every line the Scout read -- it needs the Scout's conclusions.
• Reference by Path: Instead of copying file contents into prompts, tell agents which files to read. Let them load only what they need.
• Checkpoint and Continue: For very large tasks, break a single agent's work into checkpoints. Agent A processes files 1-50, Agent B processes files 51-100, each with a fresh context window.

Real-World Orchestration Examples

Example 1: Full-Stack Feature Build

Objective: Add a user notifications feature with database table, API endpoints, real-time SSE stream, and UI components.

1. Scout Agent: Explores existing notification-adjacent code, finds patterns for SSE, identifies the database migration approach, maps the API route conventions. Returns a structured context document.
2. Plan Agent: Receives the context, produces a 12-step implementation plan with file paths and acceptance criteria for each step.
3. DB Agent (worktree-db): Creates migration, schema definitions, and seed data.
4. API Agent (worktree-api): Implements CRUD routes and SSE stream endpoint following established conventions.
5. UI Agent (worktree-ui): Builds the notification bell component, dropdown, and mark-as-read interactions.
6. Test Agent: Writes unit tests for the API routes, integration tests for the SSE stream, and component tests for the UI.
7. Review Agent: Reviews all changes against project conventions, security requirements, and test coverage.
8. Merge Agent: Merges all worktrees, resolves any conflicts, runs the full test suite.

Example 2: Codebase-Wide Refactor

Objective: Migrate 200 React components from class-based to functional components with hooks.

1. Inventory Agent: Finds all class components, categorizes by complexity (simple, medium, complex).
2. Template Agent: Converts 3 representative components (one of each complexity) to establish the migration pattern.
3. Batch Agents (10 parallel): Each receives 20 components and the template patterns. Each works in its own worktree.
4. Validation Agents (10 parallel): Each runs the test suite for its batch's components.
5. Merge Agent: Sequential merge of all worktrees with conflict resolution.

This orchestration pattern converts a multi-day manual effort into a parallel operation that completes in a fraction of the time.

For complete technical reference on subagent orchestration, see the Claude Code Sub-Agents documentation.