multi-agent-workflow

name	multi-agent-workflow
description	Design a multi-agent workflow using Claude Code's coordinator/swarm patterns — outputs a complete orchestration spec

/multi-agent-workflow — Multi-Agent Workflow Designer

Usage: /multi-agent-workflow <complex task description>

---

Your Role

Design a complete multi-agent workflow using Claude Code's proven patterns. Select the right coordination model, define each agent's role precisely, and specify how they communicate and recover from failures.

---

Step 1 — Read the reference files

Read in this order:

1. /Users/mjm/Claude Code/_reference/toolkit/coordinator-workflow-template.md
2. /Users/mjm/Claude Code/_reference/toolkit/swarm-team-template.md
3. /Users/mjm/Claude Code/_reference/toolkit/agent-spawning-template.md

---

Step 2 — Select coordination model

Model A: Coordinator + Workers

• Task has distinct phases (research, then synthesize, then implement, then verify)
• Each phase depends on the previous one
• Need anti-confirmation-bias: fresh verifier sees no implementation context
• Template: coordinator-workflow-template.md

Model B: Swarm

• Task is embarrassingly parallel (N independent items to process)
• Workers don't depend on each other's output
• Prefer autonomy: workers self-claim work from a shared queue
• Template: swarm-team-template.md

Model C: Fork (Context Inheritance)

• Child needs parent's full research context immediately
• Want to share prompt cache (zero re-tokenization cost)
• Sequential subtasks that build on parent's knowledge
• Template: agent-spawning-template.md

Hybrid: Most production systems combine models. E.g., Coordinator orchestrates Phase 1 with fan-out research (Model A), then Phase 2 as a Swarm for parallel implementation (Model B).

---

Step 3 — Produce the workflow design document

## Workflow Design: [Name]

### Coordination Model
**Primary model**: [A / B / C / Hybrid]
**Reason**: [why this model fits the task]

---

### Agent Roster

| Agent | Role | Tools Allowed | Spawn Mode | Output |
|-------|------|--------------|------------|--------|
| Coordinator | Orchestrate all phases | All (read-heavy) | Main thread | Synthesis doc |
| Research-A | [specific area] | Glob, Grep, Read | Background | `scratchpad/research-a.md` |
| Research-B | [specific area] | Glob, Grep, Read | Background | `scratchpad/research-b.md` |
| Implementer | Execute synthesis spec | All | Fork from Coordinator | File changes |
| Verifier | Independent review | Read-only | Fresh (no prior context) | Verdict report |

---

### Communication Design

**Coordinator → Workers**: [how tasks are assigned]
```
Option 1: Direct spawn — AgentTool({ prompt: task_description, run_in_background: true })
Option 2: Shared queue — TaskList.add(task), workers poll and claim
Option 3: SendMessage — to: "agent-id", message: "new task"
```
**Choice**: [which option and why]

**Workers → Coordinator**: [how results return]
```
Option 1: <task-notification> XML injected into coordinator's stream
Option 2: Write to scratchpad/[agent-name].md, coordinator reads all
Option 3: TaskOutputTool(task_id, block=true)
```
**Choice**: [which option and why]

**Shared State**: [cross-agent knowledge]
```
Scratchpad directory: .claude/scratchpad/[workflow-name]/
  ├── research-findings.md
  ├── synthesis.md
  └── implementation-log.md
```

---

### Phase Breakdown

**Phase 1: Research** *(N agents, parallel, ~X minutes)*
```
Coordinator spawns simultaneously:
  Agent "research-backend" → [specific search area, specific tools]
  Agent "research-frontend" → [specific search area, specific tools]
  Agent "research-tests" → [specific search area, specific tools]

Collection: Wait for all <task-notification> completions
Result: scratchpad/research-*.md files
```

**Phase 2: Synthesis** *(Coordinator only)*
```
Read all scratchpad/research-*.md
Produce: scratchpad/implementation-spec.md
  Contains: [list of specific changes with file paths and exact modifications]
```

**Phase 3: Implementation** *(1-N agents)*
```
[If one agent]: Fork from coordinator → inherits context → executes spec
[If multiple]: Swarm — coordinator splits spec into chunks, workers claim chunks
```

**Phase 4: Verification** *(1 FRESH agent — CRITICAL)*
```
⚠️  MUST be a fresh agent with NO implementation context
Only receives: original requirements + file diff
Checks:
  - [ ] Requirements are met
  - [ ] No regressions introduced
  - [ ] Tests pass
  - [ ] Code quality acceptable
```

---

### Prompt Cache Strategy

| Agent | Fork from? | Shared prefix | Savings |
|-------|-----------|---------------|---------|
| Research agents | No (independent context) | 0 | — |
| Implementer | Yes, from Coordinator | ~[N]k tokens | ~$[X] |
| Verifier | No (fresh — intentional) | 0 | — |

---

### Permission Model

```
Coordinator permissions: [list]
Workers inherit via permission sync: [list]
Bubble up to user for: [sensitive operations]
```

---

### Failure Recovery

| Failure scenario | Detection | Recovery |
|-----------------|-----------|----------|
| Research agent crashes | No task-notification after timeout | Re-spawn with same task |
| Coordinator crashes | Session .claude/pointer file | Resume from pointer |
| Verification fails | Verifier returns rejection | [escalate to user / re-implement / partial accept] |
| Scratchpad write conflict | File lock error | Retry with exponential backoff |

---

### Anti-Patterns Checklist

- [ ] ✅ Verifier has NO access to implementation plan (prevents confirmation bias)
- [ ] ✅ Workers do NOT share mutable state except via scratchpad (prevents races)
- [ ] ✅ Synthesis phase exists between research and implementation (prevents "telephone game")
- [ ] ✅ Context window per agent bounded by task scope (prevents overflow)
- [ ] ✅ Permission level appropriate per agent (researcher = read-only, implementer = full)

---

Built-in Agent Types

Ready to use — no custom definition needed:

Type	Key constraint	Best for
general-purpose	All tools	Research, implementation, multi-step
Explore	Read-only tools only	Fast codebase exploration
Plan	Read-only tools only	Architecture planning
verification	Read-only tools only	Independent review

Custom agents: create .claude/agents/[name].md with frontmatter:

---
name: my-agent
description: what it does and when to use it
model: claude-opus-4-6
tools: [Bash, Read, Grep, Glob, FileWriteTool]
---
You are a specialized agent that...