Skip to content
Back to search

Spec-Flow

Turn product ideas into production launches with Spec-Driven Development. Repeatable Claude Code workflows with quality gates, token budgets, and auditable artifacts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marcusgoll--spec-flow/badge.svg)](/listings/marcusgoll--spec-flow)

HTML

<a href="/listings/marcusgoll--spec-flow"><img src="/api/listings/marcusgoll--spec-flow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install

npx spec-flow init

This copies workflow files directly into your project (`.claude/`, `.codex/`, `.spec-flow/`, `CLAUDE.md`). No dependency is added to your `package.json` — Spec-Flow becomes part of your codebase.

`npx spec-flow ...` is the installer and maintenance CLI. After installation, you use the installed workflow commands such as `/feature`, `/plan`, and `/ship` inside your tool environment.

2. Build your first feature

/feature "add dark mode toggle"

Spec-Flow runs you through:

spec → plan → tasks → implement → optimize → ship

Each phase produces artifacts, runs quality checks, and hands off cleanly to the next.

3. That's it

Your feature is deployed. All decisions documented. Tests passing. Ready for the next one.

Staying Updated

Check for updates anytime:

npx spec-flow status

Update to the latest version:

npx spec-flow update

For CI/CD pipelines, use `--check` to fail if outdated:

npx spec-flow status --check

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 541 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <h1>Spec-Flow</h1>
  3. <p><strong>Ship features faster with AI-powered spec-driven development.</strong></p>
  4. <p>
  5. <a href="https://www.npmjs.com/package/spec-flow">
  6. <img src="https://img.shields.io/npm/v/spec-flow.svg?logo=npm&color=CB3837" alt="npm package">
  7. </a>
  8. <a href="https://github.com/marcusgoll/Spec-Flow/blob/main/LICENSE">
  9. <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT">
  10. </a>
  11. <a href="https://github.com/marcusgoll/Spec-Flow/actions/workflows/ci.yml">
  12. <img src="https://img.shields.io/github/actions/workflow/status/marcusgoll/Spec-Flow/ci.yml?branch=main" alt="CI Status">
  13. </a>
  14. <a href="https://github.com/marcusgoll/Spec-Flow/stargazers">
  15. <img src="https://img.shields.io/github/stars/marcusgoll/Spec-Flow?style=social" alt="GitHub Stars">
  16. </a>
  17. <a href="https://github.com/ithiria894/awesome-claude-code-workflows">
  18. <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in awesome-claude-code-workflows">
  19. </a>
  20. </p>
  21. </div>
  22. ---
  23. Spec-Flow is a workflow toolkit for [Claude Code](https://claude.ai/code) that transforms how you build software with AI. Instead of ad-hoc prompting, you get a structured pipeline that takes ideas from specification to production.
  24. ```
  25. /feature "add user authentication"
  26. ```
  27. That's it. Spec-Flow handles the rest: writing specs, planning architecture, breaking down tasks, implementing with TDD, running quality gates, and deploying.
  28. ## Why Spec-Flow?
  29. | Without Spec-Flow | With Spec-Flow |
  30. |-------------------|----------------|
  31. | "What were we building again?" | Every decision tracked in NOTES.md |
  32. | Features shipped without tests | TDD enforced, quality gates block bad code |
  33. | Context bloat slows Claude down | Auto-compaction keeps context efficient |
  34. | Each feature starts from scratch | Reusable patterns, proven workflows |
  35. | "Did we test this? Who approved?" | Auditable artifacts for every phase |
  36. ## Quick Start
  37. ### 1. Install
  38. ```bash
  39. npx spec-flow init
  40. ```
  41. This copies workflow files directly into your project (`.claude/`, `.codex/`, `.spec-flow/`, `CLAUDE.md`). No dependency is added to your `package.json` — Spec-Flow becomes part of your codebase.
  42. `npx spec-flow ...` is the installer and maintenance CLI. After installation,
  43. you use the installed workflow commands such as `/feature`, `/plan`, and
  44. `/ship` inside your tool environment.
  45. ### 2. Build your first feature
  46. ```bash
  47. /feature "add dark mode toggle"
  48. ```
  49. Spec-Flow runs you through:
  50. ```
  51. spec → plan → tasks → implement → optimize → ship
  52. ```
  53. Each phase produces artifacts, runs quality checks, and hands off cleanly to the next.
  54. ### 3. That's it
  55. Your feature is deployed. All decisions documented. Tests passing. Ready for the next one.
  56. ### Staying Updated
  57. Check for updates anytime:
  58. ```bash
  59. npx spec-flow status
  60. ```
  61. Update to the latest version:
  62. ```bash
  63. npx spec-flow update
  64. ```
  65. For CI/CD pipelines, use `--check` to fail if outdated:
  66. ```bash
  67. npx spec-flow status --check
  68. ```
  69. ---
  70. ## The Workflow
  71. ### Features (< 16 hours)
  72. For focused work on a single subsystem:
  73. ```bash
  74. /feature "user profile editing" # Start the workflow
  75. /feature continue # Resume after a break
  76. ```
  77. ### Epics (> 16 hours)
  78. For complex work spanning multiple subsystems:
  79. ```bash
  80. /epic "OAuth 2.1 authentication" # Multi-sprint orchestration
  81. /epic continue # Resume epic work
  82. ```
  83. Epics break down into parallel sprints with locked API contracts, giving you 3-5x velocity through parallelization.
  84. ### Quick fixes (< 30 min)
  85. For small changes that don't need the full workflow:
  86. ```bash
  87. /quick "fix login button alignment"
  88. ```
  89. ## Commands
  90. ### Core Workflow
  91. | Command | What it does |
  92. |---------|--------------|
  93. | `/feature "name"` | Start a feature workflow |
  94. | `/epic "goal"` | Start a multi-sprint epic |
  95. | `/quick "fix"` | Fast path for small changes |
  96. | `/help` | Context-aware guidance |
  97. ### Phase Commands
  98. | Command | Phase |
  99. |---------|-------|
  100. | `/spec` | Generate specification |
  101. | `/plan` | Create implementation plan |
  102. | `/tasks` | Break down into TDD tasks |
  103. | `/implement` | Execute tasks |
  104. | `/optimize` | Run quality gates |
  105. | `/ship` | Deploy to staging/production |
  106. ### Project Setup
  107. | Command | What it does |
  108. |---------|--------------|
  109. | `/init-project` | Generate project documentation |
  110. | `/init-preferences` | Configure workflow defaults |
  111. | `/roadmap` | Manage features via GitHub Issues |
  112. See [the public installed workflow command reference](docs/commands.md) for
  113. the slash-command surface. For installer and maintenance commands, run
  114. `npx spec-flow help`.
  115. ## How It Works
  116. ### 1. Specification Phase
  117. ```bash
  118. /spec "user authentication"
  119. ```
  120. Generates `spec.md` with:
  121. - User scenarios in Gherkin format
  122. - Functional and non-functional requirements
  123. - Acceptance criteria
  124. - Success metrics
  125. ### 2. Planning Phase
  126. ```bash
  127. /plan
  128. ```
  129. Creates `plan.md` with:
  130. - Architecture decisions
  131. - Component breakdown
  132. - Code reuse opportunities
  133. - Risk assessment
  134. ### 3. Task Breakdown
  135. ```bash
  136. /tasks
  137. ```
  138. Produces `tasks.md` with:
  139. - 20-30 concrete implementation tasks
  140. - TDD sequencing (Red → Green → Refactor)
  141. - Dependency ordering
  142. - Acceptance criteria per task
  143. ### 4. Implementation
  144. ```bash
  145. /implement
  146. ```
  147. Executes tasks with:
  148. - Test-first development
  149. - Specialist agents (backend, frontend, database)
  150. - Parallel batch execution
  151. - Automatic error recovery
  152. ### 5. Quality Gates
  153. ```bash
  154. /optimize
  155. ```
  156. Runs parallel checks:
  157. - Performance benchmarks
  158. - Security scanning
  159. - Accessibility audits
  160. - Code review
  161. - Test coverage validation
  162. ### 6. Deployment
  163. ```bash
  164. /ship
  165. ```
  166. Handles:
  167. - Staging deployment
  168. - Validation checks
  169. - Production promotion
  170. - Rollback capability
  171. ## Installed Project Structure
  172. This is the typical consumer-project layout after `npx spec-flow init`. It is
  173. not the source repo layout for Spec-Flow itself.
  174. ```
  175. your-project/
  176. ├── .claude/
  177. │ ├── commands/ # Slash commands
  178. │ ├── agents/ # Specialist agent briefs
  179. │ ├── skills/ # Progressive disclosure content
  180. │ └── hooks/ # Event handlers
  181. ├── .spec-flow/
  182. │ ├── scripts/ # Automation scripts
  183. │ ├── config/ # User preferences
  184. │ └── templates/ # Artifact templates
  185. ├── specs/
  186. │ └── NNN-feature/ # Feature workspaces
  187. ├── epics/
  188. │ └── NNN-epic/ # Epic workspaces
  189. └── docs/
  190. └── project/ # Project documentation
  191. ```
  192. ## Using the Codex prompt adapters
  193. Run `npx spec-flow init` (or `update`) in your project to install the supporting workflow files,
  194. then run `npx spec-flow install-codex-prompts`. The latter installs the packaged public commands
  195. into `$CODEX_HOME/prompts`, or `~/.codex/prompts` when `CODEX_HOME` is unset. It works from any
  196. directory; it does not load commands from that directory.
  197. Project `.codex` files are added only when missing, regardless of the install conflict strategy.
  198. Existing guidance and customized commands are preserved. Updates do not refresh those existing
  199. files; back up and remove an individual file before rerunning `update` to replace it deliberately.
  200. Use `--dry-run` to inspect the files first. Existing prompts require confirmation before
  201. replacement; `--force` explicitly allows replacement. Nested commands are flattened by filename.
  202. Reference documents and maintainer-only commands are excluded; conflicting names stop installation
  203. before any writes.
  204. These are the existing prompt adapters, not a native-skill migration or a new autonomous engine.
  205. Several direct shared-engine phases remain compatibility-only; see the
  206. [shared engine reference](.spec-flow/docs/internal/spec-cli-usage.md) for their current limits.
  207. ## Using with Gemini CLI
  208. Spec-Flow can be installed as a Gemini CLI extension to bring the same structured workflow to Gemini.
  209. 1. **Install**:
  210. ```bash
  211. # From within your project root
  212. npx spec-flow install-gemini-extension
  213. ```
  214. *Alternatively, run: `gemini extensions install .` inside your project.*
  215. 2. **Use**:
  216. The extension provides the same slash commands (`/feature`, `/plan`, etc.) directly within your Gemini CLI session.
  217. ```
  218. /feature "add user authentication"
  219. ```
  220. 3. **Skills & Agents**:
  221. The Gemini extension automatically adapts Spec-Flow's agents and skills to work within the Gemini environment, allowing you to leverage specialized personas like `backend-dev` or `git-workflow-enforcer`.
  222. ## Requirements
  223. - **Claude Code** with slash command support
  224. - **Git** 2.39+
  225. - **Python** 3.10+
  226. - **yq** 4.0+ for YAML processing
  227. Windows users: Install [Git for Windows](https://git-scm.com/download/win) for full compatibility.
  228. ## Documentation
  229. | Guide | Description |
  230. |-------|-------------|
  231. | [Getting Started](docs/getting-started.md) | Step-by-step tutorial |
  232. | [Developer Guide](docs/developer-guide.md) | Complete reference |
  233. | [Commands Reference](docs/commands.md) | All slash commands |
  234. | [Architecture](docs/architecture.md) | System design |
  235. | [Troubleshooting](docs/troubleshooting.md) | Common issues |
  236. ## Examples
  237. Checked-in example project docs live under
  238. [`docs/examples/flightpro-sample-project/`](docs/examples/flightpro-sample-project/).
  239. Consumer projects will create `specs/NNN-feature/` and `epics/NNN-epic/`
  240. workspaces after installation.
  241. ## 🆕 Recent Updates
  242. ### v11.9.1 (April 2026)
  243. **Source-of-Truth Cleanup and Honest Engine Surfaces** - Align the shipped package with the repo's real public and internal boundaries
  244. - **Locked domain contract**: Added `CONTEXT.md` to define source-repo ownership, consumer-project boundaries, and canonical terms
  245. - **Truthful command surfaces**: Public docs now clearly separate `npx spec-flow ...` installer commands from installed workflow commands
  246. - **Honest shared engine**: `spec-cli.py` now labels planned surfaces and compatibility shims explicitly instead of failing through missing-file behavior
  247. - **Safer compatibility path**: Phase shim entrypoints for `tasks`, `validate`, `implement`, and `preview` now fail cleanly with structured guidance
  248. ---
  249. ### v11.9.0 (December 2025)
  250. **shadcn/ui Integration with Token Bridge Pattern** - Generate OKLCH tokens + shadcn-compatible CSS variables
  251. - **8 customization options**: Style Preset, Base Color, Theme Mode, Icon Library, Font Family, Border Radius, Menu Color, Menu Accent
  252. - **Token Bridge Pattern**: OKLCH tokens remain source of truth, shadcn CSS variable aliases generated
  253. - **Brownfield scanning**: Auto-detect and consolidate existing color tokens
  254. - **Menu theming**: New menu-specific tokens for background, hover, active, and accent styles
  255. **Ultrathink Philosophy Checkpoints** - Deep thinking embedded across all workflow phases
  256. - **Phase checkpoints**: Think Different (spec), Obsess+Simplify (plan), Simplify Ruthlessly (tasks), Craft Don't Code (implement)
  257. - **Progressive depth**: Trivial → Standard → Complex → Epic with increasing thinking requirements
  258. - **Assumption inventory**: Question everything before designing
  259. - **Complexity budgets**: Justify each new component
  260. ---
  261. ### v11.7.0 (December 2025)
  262. **Auto-Mode for End-to-End Workflow Execution** - Run entire workflows without stopping
  263. - **`--auto` flag**: Added to `/feature` and `/epic` commands
  264. - Continue automatically through optimize → ship → finalize
  265. - Skip manual approval prompts
  266. - Auto-merge PR when CI passes (controlled by preference)
  267. - **`/ship --auto`**: Full autopilot for deployment phase
  268. - **New preferences**: `deployment.auto_ship`, `deployment.auto_merge`, `deployment.auto_finalize`
  269. - **Full autopilot**: `/feature "add auth" --auto` runs entire workflow unattended
  270. ---
  271. ### v11.5.0 (December 2025)
  272. **CLI Version Awareness** - Stay current with automatic update detection
  273. - **Version checking**: `npx spec-flow status` shows installed vs latest version
  274. - Fetches from npm registry with graceful offline handling
  275. - Clear "update available" indicator when behind
  276. - **CI/CD integration**: `--check` flag exits code 1 if update available
  277. - **Bug fix**: Fixed healthCheck variable shadowing bug
  278. ---
  279. ### v11.3.0 (December 2025)
  280. **Git Worktree Integration** - Parallel development with isolated git state per feature/epic
  281. - **worktree-context.sh**: Root orchestration utilities for worktree-based development
  282. - Automatic worktree creation for features/epics
  283. - Merge and cleanup functions for ship workflow
  284. - Task() agent context generation with cd-first pattern
  285. - **Worktree-aware agents**: Worker agent supports isolated worktree execution
  286. - **Command integration**: `/feature`, `/implement-epic`, `/ship` now create and manage worktrees
  287. - **Enabled by default**: `worktrees.auto_create: true` - reduces merge conflicts ~90%
  288. ---
  289. ### v11.2.0 (December 2025)
  290. **Automatic Regression Test Generation** - Bugs captured as tests to prevent recurrence
  291. - **regression-test-generator skill**: Auto-generates framework-specific regression tests
  292. - Framework auto-detection (Jest, Vitest, pytest, Playwright)
  293. - Arrange-Act-Assert test structure with error ID references
  294. - Links tests back to error-log.md entries
  295. - **Auto-invoke /debug on test failures**: When tests fail during `/implement`, `/debug` is automatically invoked
  296. - Generates regression test for the failure (Step 3.5)
  297. - Updates error-log.md with test reference
  298. - **Continuous checks integration**: Check 7/7 triggers auto-debug on test failures
  299. ---
  300. ### v11.1.0 (December 2025)
  301. **/quick Command - Task() Orchestrator Pattern** - Consistent architecture across all workflow commands
  302. - **quick-worker agent**: Isolated agent for atomic quick change execution
  303. - Domain detection (backend/frontend/test/docs)
  304. - Test framework detection and execution
  305. - Style guide validation (UI changes)
  306. - Automatic commit with conventional message
  307. - **Delimiter-based returns**: `---COMPLETED---`, `---NEEDS_INPUT---`, `---FAILED---`
  308. - **Full Q&A support**: Test failure decisions batched to main context
  309. ---
  310. ### v11.0.0 (December 2025)
  311. **Imperative Task() Architecture** - Commands now properly spawn isolated agents
  312. - **Breaking Change**: `/feature` and `/epic` commands rewritten to use imperative Task() spawning
  313. - Phase agents now return structured delimiters (`---COMPLETED---`, `---NEEDS_INPUT---`, `---FAILED---`)
  314. - Questions batch to main context - agents return questions, main asks user, re-spawns with answers
  315. - Parallel sprint execution for epics via `run_in_background: true`
  316. - **Ultra-lightweight Orchestrator Pattern**
  317. - Read state from disk, spawn isolated agents, handle Q&A, update state
  318. - Never carry implementation details in context
  319. - Unlimited feature/epic complexity (no context overflow)
  320. - **Updated Agents**:
  321. - `spec-agent.md`, `plan-agent.md`: Delimiter-based return format
  322. - `worker.md`: WORKER_COMPLETED, WORKER_FAILED, ALL_DONE, BLOCKED delimiters
  323. - `initializer.md`: INITIALIZED, INIT_FAILED delimiters
  324. ---
  325. ### v10.17.0 (December 2025)
  326. **Domain Memory v2 - Full Phase Isolation** - Revolutionary architecture preventing context overflow
  327. - **Domain Memory System** - Persistent disk-based state for unlimited iterations
  328. - Workers pick ONE task, implement, test, update disk, exit
  329. - Zero shared context between workers (prevents overflow)
  330. - 13-command CLI for state management
  331. - **Phase Isolation Pattern** - All phases spawn isolated agents via Task()
  332. - Question batching: agents return questions, main asks user, agents resume
  333. - Resumable at any point via interaction-state.yaml
  334. - **Project Setup Agents** - Hybrid pattern for /init-project, /prototype, /roadmap
  335. - Questionnaire inline, heavy generation isolated
  336. - **mgrep Semantic Search** - Find code by meaning, not exact text
  337. - Integrated as PRIMARY search in anti-duplication skill
  338. - Added to agent boot-up rituals
  339. ---
  340. ### v10.16.0 (December 2025)
  341. **Quality Feedback Loop System** - Multi-agent voting, continuous checks, and perpetual learning
  342. - **Multi-Agent Voting** - Error decorrelation through diverse sampling (MAKER algorithm)
  343. - 3-agent voting with k=2 strategy for code reviews, security audits, breaking changes
  344. - Temperature variation (0.5, 0.7, 0.9) decorrelates errors across agents
  345. - Automatic in `/optimize` phase, manual via `/review --voting`
  346. - **Continuous Quality Checks** - Lightweight validation during `/implement` phase
  347. - Runs after each task batch (3-4 tasks), < 30s performance target
  348. - 6 checks: linting (auto-fix), type checking, unit tests, coverage delta, dead code, gap detection
  349. - Non-blocking warnings with user choice: fix now, continue, or abort
  350. - **Progressive Quality Gates** - Three escalating levels throughout workflow
  351. - Level 1: Continuous (after each batch, < 30s, warn & continue)
  352. - Level 2: Full quality gates (`/optimize` phase, 10-15m, block deployment)
  353. - Level 3: Critical pre-flight (`/ship`, < 2m, block production)
  354. - **On-Demand Review** - New `/review` command for anytime code review
  355. - Quick review (single agent, ~2-3 min) or comprehensive voting review (3 agents, ~5-8 min)
  356. - Auto-fix linting, extract file:line references, generate coverage gaps
  357. - **Perpetual Learning** - Auto-apply proven patterns at workflow start
  358. - Performance optimizations (≥0.90 confidence) auto-applied
  359. - Anti-patterns (≥0.85 confidence) generate warnings
  360. - Custom abbreviations (≥0.95 confidence) auto-expanded
  361. - **Early Gap Detection** - Find missing implementations before staging validation
  362. - Scans for TODO/FIXME/HACK comments, placeholders, edge cases
  363. - High-confidence gaps (≥0.8) flag likely issues before deployment
  364. ---
  365. ### v10.15.1 (December 2025)
  366. **Command Architecture Optimization** - Cleaner package structure with 27% size reduction
  367. - **Consolidated Commands**: Merged 11 archived commands into 4 active commands
  368. - `/gate` now handles both CI and security gates
  369. - `/create` consolidated 6 creation commands
  370. - `/context` merged session management commands
  371. - `/init` updated routing to new active paths
  372. - **Optimized Distribution**: Excluded 48 archived commands from npm package
  373. - Package size: 8.5 MB → 6.27 MB (27% reduction)
  374. - Archived commands accessible via GitHub source only
  375. - All essential functionality in 30 active commands
  376. - **Moved Essential Commands**: Project, deployment, and meta commands organized in active directories
  377. ---
  378. ## Contributing
  379. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  380. ## Changelog
  381. See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
  382. ## License
  383. MIT License - see [LICENSE](LICENSE) for details.
  384. ---
  385. <div align="center">
  386. <p>Built by <a href="https://x.com/marcusgoll">@marcusgoll</a></p>
  387. <p>
  388. <a href="https://github.com/marcusgoll/Spec-Flow/issues">Report a bug</a> ·
  389. <a href="https://github.com/marcusgoll/Spec-Flow/discussions">Ask a question</a> ·
  390. <a href="https://github.com/marcusgoll/Spec-Flow/stargazers">Star on GitHub</a>
  391. </p>
  392. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.