A lightweight spec-driven development plugin for Claude Code.
Guides you from requirements hearing through design, implementation, and verification with 5 skills centered around plan.md.
/plugin marketplace add 884js/spec-flow
/plugin install spec-flow@884js-spec-flow
(research) → spec → build → check → done
^ |
| (NEEDS_FIX) |
+----------------+
fix can be invoked independently at any time
list can be invoked at any time as a navigation hub
| Step | Skill | Role |
|---|---|---|
| - | /spec-flow:list |
Displays all plans with status and lets you navigate to any skill |
| 0 | /spec-flow:research |
Technical investigation → research.md generation. Supports codebase analysis and web research |
| 1 | /spec-flow:spec |
Requirements hearing → integrated analysis → direction confirmation → plan.md generation → browser review (Annotation Cycle) → progress.md generation |
| 2 | /spec-flow:build |
Branch creation → task-by-task implementation → build verification → PR creation, all guided by plan.md |
| 3 | /spec-flow:check |
Compares implementation code against plan.md and reports PASS / PARTIAL / NEEDS_FIX |
| - | /spec-flow:fix |
Root cause investigation with no speculative fixes allowed. Supports feature mode and standalone mode |
Displays all plans under docs/plans/ with status (in progress / not started / spec only / completed / verified) and lets you select a plan to edit, build, research, or check. Plans are sorted by priority — in-progress and not-started plans appear first. Supports pagination for large plan lists.
/spec-flow:list
Completes everything from requirements hearing to technical design and implementation planning in a single command. Supports new mode (plan.md generation) and update mode (plan.md update from check results or additional requirements). Also generates progress.md for task tracking (single mode for small/medium, multi-pr mode for large features).
(research) → hearing → analysis → direction confirmation → plan.md generation
→ Annotation Cycle (browser review) → progress.md generation
After plan.md generation, offers an Annotation Cycle — a browser-based review loop:
- A local server starts and opens the browser with the rendered plan.md
- You add comments to sections, paragraphs, or selected text
- Click "submit comments" → writer agent auto-revises plan.md
- Browser re-opens with updated plan.md — repeat until satisfied
- Click "review complete (no changes)" → cycle ends
/spec-flow:spec add user notification feature
Output: docs/plans/{feature-name}/plan.md + progress.md
Implements features guided by plan.md. Covers branch creation → task-by-task coding → build verification → PR creation. Supports pause/resume via progress.md state tracking. Detects spec gaps during implementation and prompts for spec update.
/spec-flow:build
Reads implementation code directly and detects deviations from plan.md bidirectionally. Reports results as PASS (all conditions met) / PARTIAL (minor mismatches) / NEEDS_FIX (significant mismatches), generating result.md. On NEEDS_FIX, proposes spec update to close the loop.
/spec-flow:check
Prohibits speculative fixes and traces actual execution flows to identify root causes before proposing a fix. Operates in feature mode (with plan.md for spec correlation) or standalone mode (without plan.md).
/spec-flow:fix describe the error symptoms
Investigates technical topics through codebase analysis and web research.
Outputs research.md with findings, comparisons, and recommendations.
Results are automatically detected by /spec when creating a new spec.
/spec-flow:research authentication patterns for this project
Output: docs/plans/{feature-name}/research.md
skills/ ← User-facing entry points (orchestration)
list/spec/build/check/fix/research
agents/ ← Backend agents invoked via Task()
analyzer/ ← Project-wide integrated analysis
writer/ ← plan.md / progress.md / result.md generation
verifier/ ← Spec vs implementation comparison
researcher/ ← Technical investigation
scripts/ ← Utility scripts
annotation-viewer/ ← Browser-based plan.md review server
docs/plans/ ← All artifacts per feature
{feature-name}/
├── plan.md
├── progress.md
├── result.md
├── research.md
└── debug-*.md
This plugin is published on the Claude Code Plugin Marketplace.
/plugin marketplace add 884js/spec-flow
MIT