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:

1. Expect index.lock contention -- agents will retry automatically
2. Each agent commits only its own files -- prompt must say this explicitly
3. No agent should run git add . -- only specific files
4. Monitor with git log --oneline -20 periodically
5. 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