orchestration

Orchestration

Scope: covers multi-agent workflow design. For individual agent authoring, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. Four Orchestration Patterns

Pattern A: Parallel Dispatch

Multiple agents run simultaneously on independent work. A command dispatches them via the Task tool and synthesizes results.

Command dispatches via Task:
  |-- agent-1 (analyzes security)
  |-- agent-2 (analyzes performance)
  |-- agent-3 (analyzes architecture)
  --> Command synthesizes all results into final report

Use when: agents don't depend on each other's output.

Real examples:

• grill plugin: 6 review agents analyze code from different angles in parallel
• docs-guardian: 4 agents (staleness, accuracy, coverage, quality) run simultaneously

Implementation pattern in command body:

## Execution
1. Dispatch the following agents in parallel using Task:
   - security-agent: analyze for vulnerabilities
   - performance-agent: analyze for bottlenecks
   - architecture-agent: analyze for structural issues
2. Collect all agent outputs
3. Synthesize into a unified report with cross-references

Key decisions:

Decision	Recommendation
Max parallel agents	6 (diminishing returns above this)
Timeout per agent	120 seconds for sonnet, 300 for opus
Failure handling	Continue with other agents if one fails
Result merging	Deduplicate findings that appear in multiple agents

Pattern B: Sequential Pipeline

Each stage feeds into the next. Output of stage N is input to stage N+1.

parse --> chunk --> summarize --> QC --> output

Use when: each stage depends on the previous stage's output.

Real examples:

• reading-assistant: parse PDF -> chunk content -> summarize chunks -> QC summaries -> output
• tdd-guardian: discover tests -> run tests -> check coverage -> analyze failures -> report -> enforce

Implementation pattern:

## Execution
### Phase 1: Parse (haiku)
1. Scan input files
2. Extract structured content
3. Output: parsed data as JSON

### Phase 2: Process (sonnet)
4. Receive parsed data from Phase 1
5. Analyze and transform
6. Output: processed results

### Phase 3: QC (sonnet)
7. Verify Phase 2 output meets quality bar
8. Output: pass/warn/fail verdict

### Phase 4: Output
9. If QC passed: format and deliver final report
10. If QC failed: report failures and stop