Multi-Agent Orchestration
Meta-orchestration patterns mined from 597+ real agent dispatches across production codebases. This skill tells you WHICH strategy to use, HOW to structure prompts, and WHEN to use background vs foreground.
Core principle: Choose the right orchestration strategy for the work, partition agents by independence, inject context to enable parallelism, and adapt review overhead to trust level.
Strategy Selection
digraph strategy_selection {
rankdir=TB;
"What type of work?" [shape=diamond];
"Research / knowledge gathering" [shape=box];
"Independent feature builds" [shape=box];
"Sequential dependent tasks" [shape=box];
"Same transformation across partitions" [shape=box];
"Codebase audit / assessment" [shape=box];
"Greenfield project kickoff" [shape=box];
"Research Swarm" [shape=box style=filled fillcolor=lightyellow];
"Epic Parallel Build" [shape=box style=filled fillcolor=lightyellow];
"Sequential Pipeline" [shape=box style=filled fillcolor=lightyellow];
"Parallel Sweep" [shape=box style=filled fillcolor=lightyellow];
"Multi-Dimensional Audit" [shape=box style=filled fillcolor=lightyellow];
"Full Lifecycle" [shape=box style=filled fillcolor=lightyellow];
"What type of work?" -> "Research / knowledge gathering";
"What type of work?" -> "Independent feature builds";
"What type of work?" -> "Sequential dependent tasks";
"What type of work?" -> "Same transformation across partitions";
"What type of work?" -> "Codebase audit / assessment";
"What type of work?" -> "Greenfield project kickoff";
"Research / knowledge gathering" -> "Research Swarm";
"Independent feature builds" -> "Epic Parallel Build";
"Sequential dependent tasks" -> "Sequential Pipeline";
"Same transformation across partitions" -> "Parallel Sweep";
"Codebase audit / assessment" -> "Multi-Dimensional Audit";
"Greenfield project kickoff" -> "Full Lifecycle";
}
| Strategy |
When |
Agents |
Background |
Key Pattern |
| Research Swarm |
Knowledge gathering, docs, SOTA research |
10-60+ |
Yes (100%) |
Fan-out, each writes own doc |
| Epic Parallel Build |
Plan with independent epics/features |
20-60+ |
Yes (90%+) |
Wave dispatch by subsystem |
| Sequential Pipeline |
Dependent tasks, shared files |
3-15 |
No (0%) |
Implement -> Review -> Fix chain |
| Parallel Sweep |
Same fix/transform across modules |
4-10 |
No (0%) |
Partition by directory, fan-out |
| Multi-Dimensional Audit |
Quality gates, deep assessment |
6-9 |
No (0%) |
Same code, different review lenses |
| Full Lifecycle |
New project from scratch |
All above |
Mixed |
Research -> Plan -> Build -> Review -> Harden |
Strategy 1: Research Swarm
Mass-deploy background agents to build a knowledge corpus. Each agent researches one topic and writes one markdown document. Zero dependencies between agents.
When to Use
- Kicking off a new project (need SOTA for all technologies)
- Building a skill/plugin (need comprehensive domain knowledge)
- Technology evaluation (compare multiple options in parallel)
The Pattern
Phase 1: Deploy research army (ALL BACKGROUND)
Wave 1 (10-20 agents): Core technology research
Wave 2 (10-20 agents): Specialized topics, integrations
Wave 3 (5-10 agents): Gap-filling based on early results
Phase 2: Monitor and supplement
- Check completed docs as they arrive
- Identify gaps, deploy targeted follow-up agents
- Read completed research to inform remaining dispatches
Phase 3: Synthesize
- Read all research docs (foreground)
- Create architecture plans, design docs
- Use Plan agent to synthesize findings
Prompt Template: Research Agent
Research [TECHNOLOGY] for [PROJECT]'s [USE CASE].
Create a comprehensive research doc at [OUTPUT_PATH]/[filename].md covering:
1. Latest [TECH] version and features (search "[TECH] 2026" or "[TECH] latest")
2. [Specific feature relevant to project]
3. [Another relevant feature]
4. [Integration patterns with other stack components]
5. [Performance characteristics]
6. [Known gotchas and limitations]
7. [Best practices for production use]
8. [Code examples for key patterns]
Include code examples where possible. Use WebSearch and WebFetch to get current docs.
Key rules:
- Every agent gets an explicit output file path (no ambiguity)
- Include search hints: "search [TECH] 2026" (agents need recency guidance)
- Numbered coverage list (8-12 items) scopes the research precisely
- ALL agents run in background -- no dependencies between research topics
Dispatch Cadence
- 3-4 seconds between agent dispatches
- Group into thematic waves of 10-20 agents
- 15-25 minute gaps between waves for gap analysis
Strategy 2: Epic Parallel Build
Deploy background agents to implement independent features/epics simultaneously. Each agent builds one feature in its own directory/module. No two agents touch the same files.
When to Use
- Implementation plan with 10+ independent tasks
- Monorepo with isolated packages/modules
- Sprint backlog with non-overlapping features
The Pattern
Phase 1: Scout (FOREGROUND)
- Deploy one Explore agent to map the codebase
- Identify dependency chains and independent workstreams
- Group tasks by subsystem to prevent file conflicts
Phase 2: Deploy build army (ALL BACKGROUND)
Wave 1: Infrastructure/foundation (Redis, DB, auth)
Wave 2: Backend APIs (each in own module directory)
Wave 3: Frontend pages (each in own route directory)
Wave 4: Integrations (MCP servers, external services)
Wave 5: DevOps (CI, Docker, deployment)
Wave 6: Bug fixes from review findings
Phase 3: Monitor and coordinate
- Check git status for completed commits
- Handle git index.lock contention (expected with 30+ agents)
- Deploy remaining tasks as agents complete
- Track via Sibyl tasks or TodoWrite
Phase 4: Review and harden (FOREGROUND)
- Run Codex/code-reviewer on completed work
- Dispatch fix agents for critical findings
- Integration testing
Prompt Template: Feature Build Agent
**Task: [DESCRIPTIVE TITLE]** (task\_[ID])
Work in /path/to/project/[SPECIFIC_DIRECTORY]
## Context
[What already exists. Reference specific files, patterns, infrastructure.]
[e.g., "Redis is available at `app.state.redis`", "Follow pattern from `src/auth/`"]
## Your Job
1. Create `src/path/to/module/` with:
- `file.py` -- [Description]
- `routes.py` -- [Description]
- `models.py` -- [Schema definitions]
2. Implementation requirements:
[Detailed spec with code snippets, Pydantic models, API contracts]
3. Tests:
- Create `tests/test_module.py`
- Cover: [specific test scenarios]
4. Integration:
- Wire into [main app entry point]
- Register routes at [path]
## Git
Commit with message: "feat([module]): [description]"
Only stage files YOU created. Check `git status` before committing.
Do NOT stage files from other agents.
Key rules:
- Every agent gets its own directory scope -- NO OVERLAP
- Provide existing patterns to follow ("Follow pattern from X")
- Include infrastructure context ("Redis available at X")
- Explicit git hygiene instructions (critical with 30+ parallel agents)
- Task IDs for traceability
Git Coordination for Parallel Agents
When running 10+ agents concurrently:
- Expect index.lock contention -- agents will retry automatically
- Each agent commits only its own files -- prompt must say this explicitly
- No agent should run
git add . -- only specific files
- Monitor with
git log --oneline -20 periodically
- No agent should push -- orchestrator handles push after integration
Strategy 3: Sequential Pipeline
Execute dependent tasks one at a time with review gates. Each task builds on the previous task's output. Use superpowers:subagent-driven-development for the full pipeline.
When to Use
- Tasks that modify shared files
- Integration boundary work (JNI bridges, auth chains)
- Review-then-fix cycles where each fix depends on review findings
- Complex features where implementation order matters
The Pattern
For each task:
1. Dispatch implementer (FOREGROUND)
2. Dispatch spec reviewer (FOREGROUND)
3. Dispatch code quality reviewer (FOREGROUND)
4. Fix any issues found
5. Move to next task
Trust Gradient (adapt over time):
Early tasks: Implement -> Spec Review -> Code Review (full ceremony)
Middle tasks: Implement -> Spec Review (lighter)
Late tasks: Implement only (pattern proven, high confidence)
Trust Gradient
As the session progresses and patterns prove reliable, progressively lighten review overhead:
| Phase |
Review Overhead |
When |
| Full ceremony |
Implement + Spec Review + Code Review |
First 3-4 tasks |
| Standard |
Implement + Spec Review |
Tasks 5-8, or after patterns stabilize |
| Light |
Implement + quick spot-check |
Late tasks with established patterns |
| Cost-optimized |
Use model: "haiku" for reviews |
Formulaic review passes |
This is NOT cutting corners -- it's earned confidence. If a late task deviates from the pattern, escalate back to full ceremony.
Strategy 4: Parallel Sweep
Apply the same transformation across partitioned areas of the codebase. Every agent does the same TYPE of work but on different FILES.
When to Use
- Lint/format fixes across modules
- Type annotation additions across packages
- Test writing for multiple modules
- Documentation updates across components
- UI polish across pages
The Pattern
Phase 1: Analyze the scope
- Run the tool (ruff, ty, etc.) to get full issue list
- Auto-fix what you can
