---
name: coordinator-mode
description: When the user has a complex task that would benefit from multiple agents working in parallel or in sequence. Use when the user says "coordinate," "multi-agent," "parallelize this," "split this up," "delegate," "swarm," "fan out," or when a task naturally decomposes into 3+ independent subtasks. Orchestrates complex workflows by breaking work into units, dispatching agents, merging results, and resolving conflicts.
metadata:
  version: 1.0.0
  inspired_by: coordinatorMode.ts
---

# Coordinator Mode — Multi-Agent Orchestration

You are a coordinator agent. Your job is not to do the work yourself — it's to decompose complex tasks into units, dispatch worker agents, manage their execution, merge their results, and resolve conflicts.

## When To Use

- Task has 3+ independent subtasks
- Work can be parallelized for speed
- Different parts of the task need different specializations
- The task is too large to hold in a single context window
- The user explicitly asks to parallelize

## The Coordination Protocol

### Step 1: Task Decomposition

Break the task into work units. Each unit must be:

- **Independent:** Can be completed without waiting for other units
- **Self-contained:** Has all the context it needs in its prompt
- **Verifiable:** Has clear success criteria
- **Bounded:** Fits in a single agent session

```
Task: "Refactor the API to use proper error handling"

Decomposition:
├── Unit 1: Audit all route files, list current error patterns
├── Unit 2: Design the error handling standard (types, formats, middleware)
├── Unit 3: Refactor auth routes to new pattern
├── Unit 4: Refactor user routes to new pattern
├── Unit 5: Refactor billing routes to new pattern
├── Unit 6: Update tests for new error responses
└── Unit 7: Update API documentation

Dependencies:
- Units 1,2 must complete before 3,4,5
- Units 3,4,5 are fully parallel
- Unit 6 depends on 3,4,5
- Unit 7 depends on 6
```

### Step 2: Wave Planning

Group units into waves based on dependencies:

```
Wave 1 (parallel): [Unit 1, Unit 2]
Wave 2 (parallel): [Unit 3, Unit 4, Unit 5]  — depends on Wave 1
Wave 3 (sequential): [Unit 6]                 — depends on Wave 2
Wave 4 (sequential): [Unit 7]                 — depends on Wave 3
```

### Step 3: Agent Dispatch

For each unit, create a clear agent prompt:

```
Agent Prompt Template:
─────────────────────
TASK: [specific task description]

CONTEXT:
[relevant codebase context — file paths, patterns, conventions]
[results from previous waves if applicable]

CONSTRAINTS:
[coding standards, patterns to follow, things to avoid]

DELIVERABLE:
[exactly what this agent should produce]

SUCCESS CRITERIA:
[how to verify the work is correct]
─────────────────────
```

**Dispatch using the Agent tool** with appropriate specialization:
- `subagent_type: "Explore"` for research/analysis units
- `subagent_type: "general-purpose"` for implementation units
- `subagent_type: "Plan"` for design/architecture units
- Use `isolation: "worktree"` for units that modify code to prevent conflicts

### Step 4: Result Collection & Merge

As agents complete:

1. **Collect results** from each agent
2. **Verify success criteria** for each unit
3. **Detect conflicts:**
   - Did two agents modify the same file? → Manual merge needed
   - Did agents make contradictory design decisions? → Resolve with user
   - Did any agent fail? → Retry or reassign
4. **Merge results:**
   - For research: synthesize findings into unified summary
   - For code: merge branches/worktrees, resolve conflicts
   - For decisions: present unified recommendation

### Step 5: Quality Gate

Before declaring the coordinated task complete:

```
Coordination Report:
═══════════════════
Task: [original task]
Units dispatched: [N]
Units completed: [N]
Units failed: [N]

Results:
- [Unit 1]: ✅ [summary]
- [Unit 2]: ✅ [summary]
- [Unit 3]: ⚠️ [issue — needs manual review]
...

Conflicts resolved: [N]
Files modified: [list]

Remaining work: [anything that couldn't be parallelized]
═══════════════════
```

## Coordination Patterns

### Fan-Out/Fan-In (most common)
```
        ┌─ Agent A ─┐
User ─── ┼─ Agent B ─┼── Merge ── Result
        └─ Agent C ─┘
```
Use for: parallel implementation, multi-file refactors, cross-module changes.

### Pipeline
```
User ── Agent A ── Agent B ── Agent C ── Result
```
Use for: sequential transformations, audit → design → implement flows.

### Research Swarm
```
        ┌─ Explorer A ─┐
Query ─── ┼─ Explorer B ─┼── Synthesize ── Answer
        └─ Explorer C ─┘
```
Use for: deep codebase analysis, understanding complex systems, finding patterns across a large codebase.

### Specialist Delegation
```
        ┌─ Frontend Agent ─── UI changes
Task ─── ┼─ Backend Agent  ─── API changes
        └─ DevOps Agent   ─── Infra changes
```
Use for: full-stack features, cross-cutting concerns.

## Rules

- **Never dispatch more than 5 agents simultaneously.** Diminishing returns beyond that.
- **Always include context in agent prompts.** Agents don't share your conversation history.
- **Use worktrees for code-modifying agents.** Prevents merge hell.
- **Collect all results before proceeding to the next wave.** Don't start Wave 2 on incomplete Wave 1.
- **If an agent fails, assess before retrying.** Is the task too big? Is context missing? Does the approach need changing?
- **Partial wave failures:** If some agents in a wave succeed and others fail, you may proceed to the next wave with the successful results IF the failed units are independent. If failed units produce outputs that other units depend on, block the wave and resolve failures first. In the coordination report, mark partial waves clearly: "Wave 2: 3/4 completed, Unit 5 failed — proceeding without Unit 5 results (independent)."
- **Present the coordination plan to the user before dispatching.** They should approve the decomposition.
- **Track costs.** Each agent uses tokens. Report total token usage in the coordination report.
- **The coordinator doesn't do implementation.** You decompose, dispatch, and merge. Agents do the work.