SpecFlow

Turn AI coding sessions into a repeatable spec-driven workflow.

npx @ceatoleii/specflow init

Full guide: English · Español

What it does

SpecFlow installs a four-phase pipeline into your repo so your AI assistant:

1. Clarifies the requirement before coding (task.md with acceptance criteria)
2. Designs a plan you approve (plan.md, tasks.md)
3. Implements only what was approved (one agent writes code)
4. Reviews against your criteria and verification commands (review.md)

Until you start a task, nothing changes — your assistant works as usual (Direct mode). When you say nueva tarea or flow on, Flow mode routes each message to the right phase agent.

v2.2+ installs the Cursor adapter by default. Optional Linear sync moves issue states (Todo → In Progress → Done) via the Linear MCP plugin in Cursor — not via CLI API keys.

Full Linear setup: Linear Integration · ES

Install (2 minutes)

From your project root (Node.js ≥ 18, interactive terminal):

npx @ceatoleii/specflow init

The wizard asks for language, Cursor adapter, optional Linear sync, and .agents-docs/ templates. Then:

specflow doctor          # verify install

Add to .gitignore:

.agents-state/

Your first task (cheat sheet)

| Step | You say | You get | |------|---------|---------| | Start | nueva tarea or flow on (or nueva tarea desde LIN-123) | Refiner asks clarifying questions | | Refine | Answer questions | .agents-state/current/task.md | | Design | Wait, then review plan | plan.md, tasks.md | | Approve | /approve | Implementer writes code | | Done | Wait for review | Archive + flow off on PASS |

Stop anytime: flow off or modo directo.

Details, diagrams, and what to read in each phase: How it works · Primer flujo (ES)

Everyday commands

| Command | Why use it | |---------|------------| | specflow init | First-time install in a project | | specflow doctor | Check files, adapters, flow state | | specflow doctor --run | Same + run your verification.md commands | | specflow status | Version, adapters, Linear on/off, update available | | specflow sync | Update engine & adapters (keeps .agents-docs/) | | specflow linear setup | Enable Linear state sync (Cursor MCP) |

What you edit vs what SpecFlow manages

| You own | SpecFlow manages (init / sync) | |---------|-------------------------------------| | .agents-docs/ — stack, conventions, how to test | .agents/ — orchestrator & phase rules | | Your source code (via Implementer in flow) | AGENTS.md, adapters, .specflow-version | | .gitignore entry for .agents-state/ | |

Fill .agents-docs/ before serious tasks so agents know your stack and test commands.

Documentation

| | | |---|---| | Guide (EN) | ceatoleii.github.io/specflow | | Guía (ES) | ceatoleii.github.io/specflow/es | | npm | @ceatoleii/specflow | | Changelog | CHANGELOG.md |

License

MIT © ceatoleii