SpecFlow: Multi-Agent SDD in Cursor (4 phases, /approve, single code writer)

SpecFlow, a new CLI tool from developer ceatoleii, installs Spec-Driven Development (SDD) in any repository by enforcing a four-phase agent pipeline where only a single "Implementer" agent can edit source code. The tool uses markdown specs and a `/approve` gate to ensure code is only written after design agreement, preventing vague requests from producing large diffs. SpecFlow operates within Cursor chat, allowing developers to toggle the flow on for features with clear acceptance criteria while using direct mode for typos and exploration.

/approve , single code writer SpecFlow is a CLI that installs Spec-Driven Development SDD in your repository: four phase agents, markdown specs, and only Implementer may edit source code. It still looks like Cursor chat — you turn on flow when the feature warrants it. @ceatoleii/specflow https://github.com/ceatoleii/specflow · Pipeline: npx @ceatoleii/specflow init Full guide: ceatoleii.github.io/specflow https://ceatoleii.github.io/specflow/ | Symptom | SpecFlow mechanism | |---|---| | Vague ask → huge diff | Refiner → task.md with AC1, AC2… | | Code before design agreement | SDD waits for /approve | Multiple “agents” touching src/ | Only Implementer writes source | | “Done” without evidence | Reviewer → review.md per AC | Pipeline: Requirement → Plan → Tasks → Code → Review php flowchart LR R Refining<br/ task.md -- D Designing<br/ plan.md + tasks.md D -- |/approve| I Implementing<br/ src/ I -- V Reviewing<br/ review.md V -- |PASS| A history/ + flow off V -- |FAIL| I Phase phase.md | Agent | Writes code? | Output | |---|---|---|---| refining | Refiner | No | task.md | designing | SDD | No | plan.md , tasks.md | implementing | Implementer | Yes | Code + tasks.md | reviewing | Reviewer | No | review.md | | Direct mode | Flow mode | | |---|---|---| Signal | No .agents-state/.flow-enabled | File present | Start | — | new task , flow on | Stop | — | flow off , direct mode phrases | Use for | Typos, spikes, exploration | Features with clear ACs | Requirements: Node.js ≥ 18, interactive terminal, project root. npx @ceatoleii/specflow init specflow doctor Add to .gitignore : .agents-state/ init installs | Path | Maintained by | Notes | |---|---|---| AGENTS.md | SpecFlow init / sync | Universal entry for IDEs | .agents/ | SpecFlow | Phase rules — do not edit | .agents-docs/ | You | Stack, conventions, verification.md | .agents-state/ | Runtime | Per-task state — gitignore | .cursor/rules/ specflow.mdc | SpecFlow | Cursor adapter default v2.2+ | .specflow-linear.json | Optional | Linear sync via Cursor MCP | Golden rule: fill .agents-docs/ before serious tasks — agents read it every flow. /api/search Example feature: Max 100 req/min per IP, HTTP 429 with standard JSON, existing tests stay green. In Cursor chat: new task Also: flow on , or new task from LIN-123 Linear + MCP . Verify: specflow doctor Expect .flow-enabled and phase.md = refining task.md Refiner asks questions; you answer. Typical output: Task: Rate limit /api/search Goal Limit anonymous traffic to /api/search without breaking current behavior. Acceptance Criteria - AC1: 100 requests/min from same IP → HTTP 429 - AC2: Body { "error": "rate limit exceeded", "retryAfter": <number } - AC3: Existing search endpoint tests pass unchanged Constraints - Reuse existing error middleware patterns if present - No new env vars without team approval Out of Scope - Per-API-key quotas - Admin dashboard for limits You review ACs and Out of Scope — reply in chat to fix; no need to hand-edit the file. plan.md + tasks.md SDD proposes design. Sample tasks.md TDD order : Tasks - test Add integration test: 101 requests in 60s → 429 AC1 - test Assert JSON body shape matches AC2 - impl Create rateLimit middleware in-memory store, 100/min - impl Wire middleware on /api/search route only - impl Run full search test suite AC3 Read plan.md files, approach . If the plan sneaks in unrequested refactors, ask for changes before approve. /approve gate /approve Also valid: approved , go ahead locale-dependent phrases in rules . implementing src/ Watch: tasks.md — → ~ → x git diff — must match plan.md On spec gaps, answer in chat — Implementer should not guess. review.md Reviewer runs .agents-docs/verification.md e.g. npm test , npm run lint . Sample review.md : Review: Rate limit /api/search Acceptance Criteria | AC | Evidence | Status | |----|----------|--------| | AC1 | rate-limit.test.ts — 101 req → 429 | PASS | | AC2 | Snapshot error + retryAfter fields | PASS | | AC3 | npm test -- search — 0 failures | PASS | Verification - npm test — exit 0 - npm run lint — exit 0 Decision PASS — archived to history/, flow disabled. | Outcome | What happens | |---|---| PASS | history/YYYY-MM-DD-slug/ , flow off | FAIL | Back to Implementer with concrete fixes | /approve , no implementation. src/ , lib/ , etc. phase.md , task.md , plan.md under .agents-state/current/ . .agents/ via sync ; project facts in .agents-docs/ never overwritten by sync .| Command | When | |---|---| specflow init | First install | specflow doctor | Verify files and phase | specflow doctor --run | + run verification.md | specflow status | Version, Linear on/off, updates | specflow sync | Update engine and adapters | specflow linear setup | Enable Linear sync MCP | specflow status specflow sync specflow linear setup or wizard during init | SpecFlow event | Linear state | |---|---| | Refining complete | Todo | /approve | In Progress | | Review PASS | Done | Details: Linear Integration https://ceatoleii.github.io/specflow/linear-integration.html | Use flow | Skip direct mode | |---|---| | Feature with ACs and scope | One-line fix | | You want to read plan before diff | Spec already signed elsewhere | Team shares .agents/ rules | Fully ad-hoc spike | Commit: AGENTS.md , .agents/ , .agents-docs/ , adapters, .specflow-version Do not commit: .agents-state/ npx @ceatoleii/specflow sync updates engine; keeps .agents-docs/ | Issue | First step | |---|---| | Assistant ignores phases | Is .flow-enabled present? specflow doctor | | Code without plan | Did you /approve ? Check phase.md | | Review fails tests | Fill .agents-docs/verification.md | More: Troubleshooting https://ceatoleii.github.io/specflow/troubleshooting.html npx @ceatoleii/specflow init new task when the contract matters /approve before the diff Links article-medium-en.md in the repoWhat feature would you run through /approve first? 👇