swarm-plan

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.