By name: oa-orchestration-patterns description: "4 reusable agent orchestration patterns: Research Swarm, Build Pipeline, Review Chain, Batch Processor. Use when choosing how to structure multi-agent work. Activates for: orchestration pattern, research swarm, build pipeline, review chain, batch processor." user-invocable: false
Critical Rules
- Keep batch sizes 3-5 agents — because larger batches saturate context and produce inconsistent quality.
- NEVER mix patterns in one workflow without explicit handoff points — because agents cannot coordinate across pattern boundaries without messaging.
Decision Tree
What is the task shape?
├── Multiple independent information sources → Research Swarm
├── Sequential build with unknown steps → Build Pipeline (oa pipeline)
├── Output that needs QA validation → Review Chain
└── Same template on N inputs → Batch Processor
Patterns
Pattern 1: Research Swarm
3 parallel researchers + 1 combiner. Use for multi-topic investigation.
oa run "Research topic A: write findings to /tmp/proj/research-a.md" --name researcher-a --model claude/sonnet --direct
oa run "Research topic B: write findings to /tmp/proj/research-b.md" --name researcher-b --model claude/sonnet --direct
oa run "Research topic C: write findings to /tmp/proj/research-c.md" --name researcher-c --model claude/sonnet --direct
# After all done:
oa run "Read /tmp/proj/research-*.md and synthesize into /tmp/proj/final.md" --name combiner --model claude/sonnet --direct
Models: sonnet for researchers, sonnet for combiner.
Pattern 2: Build Pipeline
Planner → N builders → validator. Use for feature implementation or doc generation.
oa pipeline "Implement feature X with tests and documentation"
# Or manually:
oa run "Plan the implementation: write plan.md with steps" --name planner --model claude/opus --direct
# After planner done, spawn builders per plan step
oa run "Implement step 1 per /tmp/proj/plan.md" --name builder-1 --model claude/sonnet --direct
oa run "Validate all outputs against spec" --name validator --model claude/sonnet --direct
Models: opus for planner, sonnet for builders, sonnet for validator.
Pattern 3: Review Chain
1 writer → 1 reviewer → 1 fixer (if needed). Use for QA-critical output.
oa run "Write the API documentation to /tmp/proj/api-docs.md" --name writer --model claude/sonnet --direct
# After writer done:
oa run "Review /tmp/proj/api-docs.md against spec. Write issues to /tmp/proj/review.md" --name reviewer --model claude/sonnet --direct
# After reviewer done, conditionally:
oa run "Fix issues in /tmp/proj/api-docs.md listed in /tmp/proj/review.md" --name fixer --model claude/sonnet --direct
Models: sonnet throughout. Use opus for writer only when content is architecturally complex.
Pattern 4: Batch Processor
N workers on the same template. Use for file migration, format conversion, bulk generation.
# For each file in batch (max 5 at a time):
oa run "Convert /tmp/proj/file1.md to JSON. Write to /tmp/proj/file1.json" --name converter-1 --model claude/haiku --direct
oa run "Convert /tmp/proj/file2.md to JSON. Write to /tmp/proj/file2.json" --name converter-2 --model claude/haiku --direct
oa run "Convert /tmp/proj/file3.md to JSON. Write to /tmp/proj/file3.json" --name converter-3 --model claude/haiku --direct
Models: haiku for repetitive/structured work. Batch size: 3-5 max.
Quality Gate After Any Pattern
After every agent batch, verify before proceeding:
- Count — expected N outputs? got N?
- Content — complete, not truncated?
- Format — matches reference structure?
- Cross-reference — outputs consistent with each other?
Anti-Patterns
- Bad: 10 parallel agents on the same task — overwhelms context, produces inconsistent quality
- Good: 3-5 parallel agents max, then a combiner
- Bad: Skipping the validator in a Build Pipeline — unvalidated output propagates errors
- Good: Always include a validator/reviewer as the final step
References
- Related: oa-orchestration-spawn, oa-orchestration-pipeline, oa-orchestration-communication