swarm plan

Interactively refine vague requirements before committing to the full pipeline. Three roles — PM, engineer, designer — each clarify from their perspective.

Usage

swarm plan "Add a dark mode toggle"
swarm plan -e   # Open editor for longer prompts

Planning Phases

Pre-Analysis — Scans the prompt for parallelizable research sub-tasks (e.g., “study this URL”, “research best practices”). Runs them concurrently. Skipped if no research tasks detected.
Requirements Clarification — A PM agent asks targeted questions to fill gaps. You answer in a split-pane editor (your answer on the left, agent’s questions on the right).
PM Review — A reviewer verifies the refined requirements are clear, complete, and actionable (up to 3 iterations).
Engineer Clarification — A senior engineer asks about API contracts, edge cases, testing expectations, and integration points.
Engineer Review — A reviewer verifies the engineering decisions are sound (up to 3 iterations).
Designer Clarification — A UI/UX designer clarifies visual, interaction, and accessibility details. Skipped for non-frontend tasks.
Designer Review — A reviewer verifies the design decisions (up to 3 iterations).
Technical Analysis — An engineering agent analyzes the codebase and reports complexity, affected files, risks, and suggested approach.
Cross-Model Review — If the review model differs from the primary, the complete plan is reviewed by a different model for accuracy and feasibility.

Async Question Harvest

Generate all questions up front and answer them offline:

# Step 1: Generate questions file
swarm plan --harvest "Add a dark mode toggle"

# Step 2: Edit the questions file
# .swarm/sessions/<sid>/questions.md

# Step 3: Resume with answers
swarm plan --resume

The questions file uses structured markdown with sections per role (plan-clarify, plan-eng-clarify, plan-design-clarify). Questions use section-prefixed numbering (Q1.1, Q1.2, …, Q2.1, …) for global uniqueness. A summary comment at the top shows the total and per-section question counts. Multiple-choice questions include labeled options (A, B, C, …) — just write the letter or provide a custom answer. Leave answers blank to let the agent decide.

Verifying Questions

Use --harvest-verify to consolidate and deduplicate an existing questions file — even one that already has answers filled in:

swarm plan --harvest-verify

This runs the same consolidation pass that happens during --harvest:

Deduplicates similar questions across roles
Re-categorizes misplaced questions into the correct role section
Normalizes formatting for consistency

All existing answers are preserved verbatim. If two answered questions are merged, both answers are concatenated so no information is lost. If the consolidation would lose any answers, the original file is kept unchanged.

Interactive Editor

During clarification, a split-pane editor opens:

Left panel — Editable text area for your answer
Right panel — Read-only scrollable context with agent questions
Tab — Switch focus between panels
PgUp/PgDown — Scroll the right panel
Command palette — Submit, Skip, or Cancel

Press Enter on an empty line to skip a round. All answers are checkpointed and replayed on resume.

Output

.swarm/plans/
  plan-latest.md              # Stable reference to the latest plan
  plan-<timestamp>.md         # Timestamped plan (never overwritten)

The plan file contains refined requirements, engineering decisions, design decisions, and technical analysis.

Running from a Plan

After planning, feed the plan into the run pipeline:

swarm --plan .swarm/plans/plan-latest.md

The spec phase is automatically skipped — the plan’s refined requirements become the specification.