Coordinator mode

Coordinator Mode

When to Use Multi-Agent Coordination

Use coordinator patterns when:

• A task has independent research + implementation phases
• Multiple file areas can be worked on in parallel
• Verification should run alongside implementation
• You need to synthesize findings before directing follow-up work

Don't use coordinator patterns when:

• The task is small enough for one session
• Steps are strictly sequential with no parallelism
• The overhead of coordination exceeds the work itself

Phase-Based Workflow

Most coordinated tasks follow four phases:

Phase	Who	Purpose
Research	Workers (parallel)	Investigate codebase, find files, understand problem
Synthesis	You (coordinator)	Read findings, understand the problem, craft implementation specs
Implementation	Workers	Make targeted changes per spec, commit
Verification	Workers	Test changes work, try to break them

The synthesis phase is the coordinator's most important job. When workers report research findings, you must understand them before directing follow-up work. Read the findings. Identify the approach. Then write a prompt that proves you understood by including specific file paths, line numbers, and exactly what to change.

Never write "based on your findings" or "based on the research." These phrases delegate understanding to the worker instead of doing it yourself.

Worker Prompt Best Practices

Workers cannot see your conversation. Every prompt must be self-contained:

Good — synthesized spec: "Fix the null pointer in src/auth/validate.ts:42. The user field is undefined when sessions expire but the token is still cached. Add a null check before user.id access. Commit and report the hash."

Bad — lazy delegation: "Based on your findings, fix the auth bug." "The worker found an issue. Please fix it."

Purpose Statement

Include a 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."

Continue vs Spawn Decision

Situation	Action	Why
Research explored exactly the files that need editing	Continue existing worker	Worker has files in context
Research was broad, implementation is narrow	Spawn fresh worker	Avoid context noise
Correcting a failure	Continue existing worker	Worker has error context
Verifying code a different worker wrote	Spawn fresh worker	Fresh eyes, no implementation bias
Wrong approach entirely	Spawn fresh worker	Clean slate avoids anchoring

Parallel Execution

Parallelism is the primary advantage. Launch independent workers concurrently:

• Read-only tasks (research) — run in parallel freely
• Write-heavy tasks (implementation) — one at a time per set of files
• Verification can sometimes run alongside implementation on different file areas

Scratchpad Pattern

For durable cross-worker knowledge, use a shared scratchpad file:

• Workers write findings to a known location
• Other workers read from it when they need context
• Structure files by topic, not by worker

Multi-Terminal Workflow

When running multiple Claude Code terminals (Boris Mode):

• Each terminal works on a separate feature branch or file area
• Use /sync on develop after merging to reconcile shared-state files
• Use /conflict-resolver if merges produce conflicts
• Shared-state files (PROGRESS.md, SPEC.md, package.json version) are ONLY modified on develop