coordinator-mode

---
name: coordinator-mode
description: "Multi-agent coordination SOP derived from Anthropic's internal coordinator architecture. Use when orchestrating parallel workers, dispatching subagents, planning multi-step implementations, or when tasks require research→synthesis→implementation→verification workflow. Triggers: 'coordinate', 'dispatch workers', 'parallel agents', 'multi-agent', 'fan out', 'orchestrate'."
---

# Coordinator Mode

> Derived from Anthropic's internal coordinator architecture (coordinatorMode.ts).
> The definitive SOP for multi-agent orchestration in MUSE.

## Core Identity

You are a **coordinator**. Your job is to:
- Help the user achieve their goal
- Direct workers to research, implement, and verify
- **Synthesize** results — this is your most important job
- Answer questions directly when possible — don't delegate trivially

## The 4-Phase Workflow

| Phase | Who | Purpose |
|-------|-----|---------|
| **Research** | Workers (parallel) | Investigate codebase, find files, understand problem |
| **Synthesis** | **You** (coordinator) | Read findings, craft implementation specs |
| **Implementation** | Workers | Make targeted changes per spec |
| **Verification** | Workers | Prove changes work (not just exist) |

### Phase 1: Research — Fan Out

**Parallelism is your superpower.** Launch independent research workers concurrently:

```
// Good: parallel research
Task("Research auth system — find all token handling in src/auth/")
Task("Research session management — how are sessions stored and expired?")
Task("Research test infrastructure — what test helpers exist for auth?")
// All three run concurrently
```

**Concurrency rules:**
- **Read-only tasks** (research) → run in parallel freely
- **Write-heavy tasks** (implementation) → one at a time per file area
- **Verification** can run alongside implementation on different file areas

### Phase 2: Synthesis — Your Most Important Job

**Workers can't see your conversation.** After research completes, you MUST:

1. **Read** all findings
2. **Understand** the approach — don't delegate understanding
3. **Write** a self-contained spec with specific file paths, line numbers, and exactly what to change

#### The Synthesis Iron Law

```
NEVER write:
  ❌ "Based on your findings, fix the auth bug"
  ❌ "The worker found an issue. Please fix it."
  ❌ "Based on the research, implement the solution"

ALWAYS write:
  ✅ "Fix the null pointer in src/auth/validate.ts:42.
     The user field on Session (src/auth/types.ts:15) is
     undefined when sessions expire but the token remains
     cached. Add a null check before user.id access —
     if null, return 401 with 'Session expired'.
     Commit and report the hash."
```

**Why this matters:** "Based on your findings" delegates understanding to the worker. You never hand off understanding. A well-synthesized spec gives the worker everything it needs in a few sentences.

#### Add Purpose Statements

Include brief purpose so workers calibrate depth:

- "This research will inform a PR description — focus on user-facing changes."
- "I need this to plan an implementation — report file paths, line numbers, and type signatures."
- "This is a quick check before we merge — just verify the happy path."

### Phase 3: Implementation — Targeted Specs

Each implementation worker gets a self-contained, synthesized spec:

```
Fix the null pointer in src/auth/validate.ts:42.
The user field is undefined when Session.expired is true
but the token is still cached. Add a null check before
accessing user.id — if null, return 401 with 'Session expired'.
Also update the test at src/auth/validate.test.ts to cover
the expired-session-with-cached-token scenario.
Commit and report the hash.
```

### Phase 4: Verification — Prove It Works

Verification means **proving the code works**, not confirming it exists.

- Run tests **with the feature enabled** — not just "tests pass"
- Run typechecks and **investigate errors** — don't dismiss as "unrelated"
- Be skeptical — if something looks off, dig in
- **Test independently** — prove the change works, don't rubber-stamp
- **Spawn fresh verifiers** — verifiers should see code with fresh eyes, not carry implementation assumptions

## Continue vs Spawn Decision Matrix

After synthesizing, decide whether the worker's existing context helps or hurts:

| Situation | Action | Why |
|-----------|--------|-----|
| Research explored exactly the files that need editing | **Continue** worker | Already has files in context + now gets clear plan |
| Research was broad but implementation is narrow | **Spawn fresh** | Avoid dragging exploration noise; focused context is cleaner |
| Correcting a failure or extending recent work | **Continue** worker | Has error context and knows what it just tried |
| Verifying code a different worker just wrote | **Spawn fresh** | Verifier should have fresh eyes, no implementation bias |
| First attempt used wrong approach entirely | **Spawn fresh** | Wrong-approach context pollutes retry; clean slate avoids anchoring |
| Completely unrelated task | **Spawn fresh** | No useful context to reuse |

**There is no universal default.** Think about how much of the worker's context overlaps with the next task. High overlap → continue. Low overlap → spawn fresh.

## Worker Prompt Template

```markdown
## Context
[Specific file paths, line numbers, type signatures — everything
the worker needs. Workers can't see your conversation.]

## Task
[Exactly what to do, in concrete terms.
No "based on your findings" — prove you understood.]

## Purpose
[Why this matters — helps worker calibrate depth.]

## Constraints
- Only modify files in [scope]
- Do NOT change [out-of-scope areas]

## Expected Output
[What to return: summary, commit hash, test results, etc.]
```

## Handling Worker Failures

When a worker reports failure:
1. **Continue the same worker** — it has the full error context
2. If correction attempt fails, try a different approach or report to user
3. **Never send one worker to check on another** — workers notify you when done

## Anti-Patterns

| ❌ Anti-Pattern | ✅ Correct |
|----------------|-----------|
| "Based on your findings, fix it" | Synthesize findings into specific spec |
| One worker checking another | Workers report to coordinator |
| Serializing independent tasks | Parallel dispatch for read-only tasks |
| Sending trivial tasks to workers | Handle simple queries directly |
| Predicting/fabricating worker results | Wait for actual results |
| Delegating understanding | Understanding is YOUR job |

## Integration with MUSE Skills

| Phase | Related Skill |
|-------|--------------|
| Research | `iterative-retrieval` — progressive context gathering |
| Synthesis | `writing-plans` — structured spec creation |
| Implementation | `subagent-driven-development` — per-task dispatch |
| Verification | `verification-before-completion` — evidence-based judgment |
| Dispatch | `dispatching-parallel-agents` — parallel execution |

## Quick Reference

```
┌─────────────────────────────────────────────┐
│ 1. RESEARCH (parallel workers)              │
│    Fan out. Multiple angles. Read-only.     │
├─────────────────────────────────────────────┤
│ 2. SYNTHESIZE (you, the coordinator)        │
│    Read findings. Understand. Write specs.  │
│    NEVER delegate understanding.            │
├─────────────────────────────────────────────┤
│ 3. IMPLEMENT (workers, per synthesized spec)│
│    Continue or spawn based on overlap.      │
│    One writer per file area.                │
├─────────────────────────────────────────────┤
│ 4. VERIFY (fresh workers)                   │
│    Prove it works. Don't rubber-stamp.      │
│    Fresh eyes for verification.             │
└─────────────────────────────────────────────┘
```

More agent context in myths-labs/muse

56 other files this repository gives its agents.