| name | swarm-plan |
| description | Use when a product spec exists and needs to be broken into a concrete implementation plan — dispatches parallel research agents to scan the repo, then synthesizes findings into tasks with file paths, dependencies, and acceptance criteria. |
| argument-hint | [path to spec file] |
Swarm Plan
Turns a product spec into an implementation plan by dispatching 3 research agents in parallel, merging their findings, and producing a task-by-task plan ready for /swarm-work.
Flow
┌─────────────────┐
│ Read Spec │
│ $ARGUMENTS or │
│ latest in │
│ docs/specs/ │
└────────┬────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Research │ │ Codebase │ │ Docs │
│ Agent │ │ Agent │ │ Agent │
│ (Explore) │ │ (Explore) │ │ (Explore) │
└─────┬──────┘ └─────┬──────┘ └─────┬──────┘
│ │ │
└───────────────┼───────────────┘
▼
┌───────────────────┐
│ Merge Findings │
│ + Synthesize │
└────────┬──────────┘
▼
┌───────────────────┐
│ Write Plan │
│ docs/plans/ │
│ YYYY-MM-DD-*.md │
└───────────────────┘
Process
1. Locate the Spec
Read the spec file from $ARGUMENTS. If no argument, find the most recently modified file in docs/specs/. Store the full spec text for agent context.
2. Dispatch 3 Agents in Parallel
Send ALL THREE Agent tool calls in a SINGLE message:
| Agent | Prompt Source | subagent_type | Purpose |
|---|
| Research Agent | ${CLAUDE_SKILL_DIR}/../../prompts/research-agent.md | Explore | Tech stack, build/test, patterns, conventions |
| Codebase Agent | ${CLAUDE_SKILL_DIR}/../../prompts/codebase-agent.md | Explore | Integration points, shared utils, data models |
| Docs Agent | ${CLAUDE_SKILL_DIR}/../../prompts/docs-agent.md | Explore | README, CLAUDE.md, manifests, constraints |
Each agent's prompt parameter: read the corresponding prompt template file, then append the spec text as context.
3. Merge Findings
Combine all 3 agent reports into a unified context covering:
- Tech stack & tooling (from Research Agent)
- Existing code & integration points (from Codebase Agent)
- Project constraints & conventions (from Docs Agent)
4. Produce the Implementation Plan
Write to docs/plans/YYYY-MM-DD-<topic>.md with this structure:
# <Title> Implementation Plan
**Goal:** <one sentence>
**Architecture:** <key design choices>
**Tech Stack:** <from research findings>
---
## Task N: <Name>
**Files:**
- Modify: `path/to/existing.ts` (what changes)
- Create: `path/to/new.ts` (what it does)
**Depends on:** Task M (or "none")
**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
**Steps:**
1. Step with specifics
2. Step with specifics
---
## Execution Order & Dependencies
**Parallelizable:** Tasks X, Y, Z can run simultaneously (no shared files).
**Sequential:** Task A → Task B (B imports from A).
Every task must have: exact file paths, clear deps, testable acceptance criteria, and concrete steps. Independent tasks are explicitly marked for parallel execution by /swarm-work.
