references/coordination-strategies.md
Multi-Agent Coordination Strategies
Patterns
Fan-Out / Fan-In
The simplest and most common pattern. One coordinator dispatches the same task to N agents, waits for all to complete, then evaluates.
┌─ Agent 1 ─┐
Task ──> ├─ Agent 2 ─┤ ──> Evaluate ──> Merge Winner
└─ Agent 3 ─┘
When to use: Optimization tasks, competitive solutions, exploring diverse approaches, competing content drafts, vendor evaluation.
Agent count: 2-5 (diminishing returns beyond 5 for most tasks).
Eval: Metric-based preferred. LLM judge for subjective quality.
Tournament
Multiple rounds of fan-out/fan-in. Losers are eliminated, winners advance. Each round can refine the task or increase difficulty.
Round 1: A1, A2, A3, A4 → Eval → A2, A4 advance
Round 2: A2, A4 → Eval → A2 wins
When to use: Complex optimization where iterative refinement helps. Each round builds on the previous winner.
Implementation:
- Run
/hub-init+/agenthub:spawnfor round 1 - Eval, merge winner into a new base branch
- Run
/hub-initagain with the merged branch as base - Repeat until convergence or budget exhausted
Ensemble
All agents' work is combined rather than selecting a winner. Useful when agents solve different parts of a problem.
Agent 1: solves auth module
Agent 2: solves API routes ──> Cherry-pick all ──> Combined result
Agent 3: solves database layer
When to use: Large tasks that decompose into independent subtasks. Each agent gets a different piece.
Implementation:
- In
/hub-init, give each agent a DIFFERENT task (subtask of the whole) - Spawn with unique dispatch posts per agent
- Instead of
/agenthub:evalranking, manually cherry-pick from each - Or merge sequentially: merge agent-1, then merge agent-2 on top
Pipeline
Agents work sequentially — each builds on the previous agent's output. Like a relay race.
Agent 1 (design) → Agent 2 (implement) → Agent 3 (test) → Agent 4 (optimize)
When to use: Tasks with natural phases (design → implement → test). Each phase needs different expertise.
Implementation:
- Spawn agent-1 alone, wait for completion
- Merge agent-1's work, spawn agent-2 from that base
- Repeat for each pipeline stage
- Each agent reads the previous agent's result post for context
Agent Configuration
Task Decomposition
For fan-out, all agents get the same task. But you can add variation:
| Strategy | Dispatch Difference | Use Case | |----------|-------------------|----------| | Identical | Same prompt to all | Pure competition | | Constrained | Same goal, different constraints | "Use caching" vs "Use indexing" | | Seeded | Same goal, different starting hints | Explore different parts of solution space | | Role-varied | Same goal, different personas | "As a performance engineer" vs "As a DBA" |
Agent Count Guidelines
| Task Complexity | Agents | Rationale | |----------------|--------|-----------| | Simple optimization | 2 | Two approaches is usually enough | | Medium complexity | 3 | Three diverse approaches, manageable eval | | Complex / creative | 4-5 | More exploration, but eval cost increases | | Subtask decomposition | N = subtasks | One agent per subtask (ensemble pattern) |
Evaluation Strategies
Metric-Based (Objective)
Best when a clear numeric metric exists:
| Metric Type | Example | Direction | |-------------|---------|-----------| | Latency | p50_ms, p99_ms | lower | | Throughput | rps, qps | higher | | Size | bundle_kb, image_bytes | lower | | Score | test_pass_rate, accuracy | higher | | Count | error_count, warnings | lower | | Word count | word_count | higher | | Readability | flesch_score | higher | | Conversion | cta_click_rate | higher |
LLM Judge (Subjective)
Best when quality is subjective or multi-dimensional:
Judging criteria (in order of importance):
- Correctness — Does it solve the stated task?
- Completeness — Does it handle edge cases?
- Simplicity — Fewer lines changed = less risk
- Quality — Clean execution, good structure, no anti-patterns
- Performance — Efficient algorithms and data structures
Hybrid
- Run metric eval to get objective ranking
- If top-2 agents are within 10% of each other, use LLM judge
- Weight: 70% metric, 30% qualitative
Failure Handling
All Agents Fail
Signal: All agents return errors or no improvement
Action:
1. Post failure summary to board
2. Archive session (state → archived)
3. Suggest: "Try with different constraints, more agents, or simplified task"
4. Do NOT auto-retry without user approval
Partial Failure
Signal: Some agents fail, others succeed
Action:
1. Evaluate only successful agents
2. Note failures in eval summary
3. Proceed with merge if any agent succeeded
No Improvement
Signal: All agents complete but none improve on baseline
Action:
1. Show results with negative deltas
2. Suggest: "Current implementation may already be near-optimal"
3. Archive session
Communication Protocol
Board Usage by Phase
| Phase | Channel | Content |
|-------|---------|---------|
| Dispatch | dispatch/ | Task assignment per agent |
| Working | progress/ | Agent status updates (optional) |
| Complete | results/ | Final result summary per agent |
| Merge | results/ | Merge summary from coordinator |
Result Post Template
Agents should write results in this format:
## Result Summary
- **Approach**: {one-line description of strategy}
- **Files changed**: {count}
- **Key changes**: {bullet list of main modifications}
- **Metric**: {value} (baseline: {baseline}, delta: {delta})
- **Tests**: {pass/fail status}
- **Confidence**: {High/Medium/Low} — {reason}
- **Limitations**: {known issues or edge cases}