{"slug": "specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer", "title": "SpecFlow: Multi-Agent SDD in Cursor (4 phases, /approve, single code writer)", "summary": "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.", "body_md": "`/approve`\n\n, single code writer)\n**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.\n\n[ @ceatoleii/specflow](https://github.com/ceatoleii/specflow) · Pipeline:\n\n```\nnpx @ceatoleii/specflow init\n```\n\nFull guide: [ceatoleii.github.io/specflow](https://ceatoleii.github.io/specflow/)\n\n| Symptom | SpecFlow mechanism |\n|---|---|\n| Vague ask → huge diff |\nRefiner → `task.md` with AC1, AC2… |\n| Code before design agreement |\nSDD waits for `/approve` |\nMultiple “agents” touching `src/`\n|\nOnly Implementer writes source |\n| “Done” without evidence |\nReviewer → `review.md` per AC |\n\n**Pipeline:** Requirement → Plan → Tasks → Code → Review\n\n``` php\nflowchart LR\n  R[Refining<br/>task.md] --> D[Designing<br/>plan.md + tasks.md]\n  D -->|/approve| I[Implementing<br/>src/]\n  I --> V[Reviewing<br/>review.md]\n  V -->|PASS| A[history/ + flow off]\n  V -->|FAIL| I\n```\n\nPhase (`phase.md` ) |\nAgent | Writes code? | Output |\n|---|---|---|---|\n`refining` |\nRefiner | No | `task.md` |\n`designing` |\nSDD | No |\n`plan.md` , `tasks.md`\n|\n`implementing` |\nImplementer | Yes |\nCode + `tasks.md`\n|\n`reviewing` |\nReviewer | No | `review.md` |\n\n| Direct mode | Flow mode | |\n|---|---|---|\nSignal |\nNo `.agents-state/.flow-enabled`\n|\nFile present |\nStart |\n— |\n`new task` , `flow on`\n|\nStop |\n— |\n`flow off` , direct mode phrases |\nUse for |\nTypos, spikes, exploration | Features with clear ACs |\n\n**Requirements:** Node.js ≥ 18, interactive terminal, project root.\n\n```\nnpx @ceatoleii/specflow init\nspecflow doctor\n```\n\nAdd to `.gitignore`\n\n:\n\n```\n.agents-state/\n```\n\n`init`\n\ninstalls\n| Path | Maintained by | Notes |\n|---|---|---|\n`AGENTS.md` |\nSpecFlow (`init` / `sync` ) |\nUniversal entry for IDEs |\n`.agents/` |\nSpecFlow | Phase rules — do not edit\n|\n`.agents-docs/` |\nYou |\nStack, conventions, `verification.md`\n|\n`.agents-state/` |\nRuntime | Per-task state — gitignore |\n`.cursor/rules/_specflow.mdc` |\nSpecFlow | Cursor adapter (default v2.2+) |\n`.specflow-linear.json` |\nOptional | Linear sync via Cursor MCP |\n\n**Golden rule:** fill `.agents-docs/`\n\nbefore serious tasks — agents read it every flow.\n\n`/api/search`\n\nExample feature:\n\nMax 100 req/min per IP, HTTP 429 with standard JSON, existing tests stay green.\n\nIn Cursor chat:\n\n```\nnew task\n```\n\nAlso: `flow on`\n\n, or `new task from LIN-123`\n\n(Linear + MCP).\n\nVerify:\n\n```\nspecflow doctor\n# Expect .flow-enabled and phase.md = refining\n```\n\n`task.md`\n\nRefiner asks questions; you answer. Typical output:\n\n```\n# Task: Rate limit /api/search\n\n## Goal\nLimit anonymous traffic to /api/search without breaking current behavior.\n\n## Acceptance Criteria\n\n- **AC1:** >100 requests/min from same IP → HTTP 429\n- **AC2:** Body `{ \"error\": \"rate_limit_exceeded\", \"retryAfter\": <number> }`\n- **AC3:** Existing search endpoint tests pass unchanged\n\n## Constraints\n\n- Reuse existing error middleware patterns if present\n- No new env vars without team approval\n\n## Out of Scope\n\n- Per-API-key quotas\n- Admin dashboard for limits\n```\n\n**You review** ACs and Out of Scope — reply in chat to fix; no need to hand-edit the file.\n\n`plan.md`\n\n+ `tasks.md`\n\nSDD proposes design. Sample `tasks.md`\n\n(TDD order):\n\n```\n## Tasks\n\n- [ ] [test] Add integration test: 101 requests in 60s → 429 (AC1)\n- [ ] [test] Assert JSON body shape matches AC2\n- [ ] [impl] Create rateLimit middleware (in-memory store, 100/min)\n- [ ] [impl] Wire middleware on /api/search route only\n- [ ] [impl] Run full search test suite (AC3)\n```\n\nRead `plan.md`\n\n(files, approach). If the plan sneaks in unrequested refactors, ask for changes **before** approve.\n\n`/approve`\n\ngate\n\n```\n/approve\n```\n\nAlso valid: `approved`\n\n, `go ahead`\n\n(locale-dependent phrases in rules).\n\n`implementing`\n\n`src/`\n\nWatch:\n\n`tasks.md`\n\n— `[ ]`\n\n→ `[~]`\n\n→ `[x]`\n\n`git diff`\n\n— must match `plan.md`\n\nOn spec gaps, answer in chat — Implementer should not guess.\n\n`review.md`\n\nReviewer runs `.agents-docs/verification.md`\n\n(e.g. `npm test`\n\n, `npm run lint`\n\n).\n\nSample `review.md`\n\n:\n\n```\n# Review: Rate limit /api/search\n\n## Acceptance Criteria\n\n| AC | Evidence | Status |\n|----|----------|--------|\n| AC1 | `rate-limit.test.ts` — 101 req → 429 | PASS |\n| AC2 | Snapshot `error` + `retryAfter` fields | PASS |\n| AC3 | `npm test -- search` — 0 failures | PASS |\n\n## Verification\n\n- `npm test` — exit 0\n- `npm run lint` — exit 0\n\n## Decision\n\n**PASS** — archived to history/, flow disabled.\n```\n\n| Outcome | What happens |\n|---|---|\nPASS |\n`history/YYYY-MM-DD-slug/` , flow off |\nFAIL |\nBack to Implementer with concrete fixes |\n\n`/approve`\n\n, no implementation.`src/`\n\n, `lib/`\n\n, etc.`phase.md`\n\n, `task.md`\n\n, `plan.md`\n\nunder `.agents-state/current/`\n\n.`.agents/`\n\nvia `sync`\n\n; project facts in `.agents-docs/`\n\n(never overwritten by sync).| Command | When |\n|---|---|\n`specflow init` |\nFirst install |\n`specflow doctor` |\nVerify files and phase |\n`specflow doctor --run` |\n+ run `verification.md`\n|\n`specflow status` |\nVersion, Linear on/off, updates |\n`specflow sync` |\nUpdate engine and adapters |\n`specflow linear setup` |\nEnable Linear sync (MCP) |\n\n```\nspecflow status\nspecflow sync\n```\n\n`specflow linear setup`\n\nor wizard during `init`\n\n| SpecFlow event | Linear state |\n|---|---|\n| Refining complete | Todo |\n`/approve` |\nIn Progress |\n| Review PASS | Done |\n\nDetails: [Linear Integration](https://ceatoleii.github.io/specflow/linear-integration.html)\n\n| Use flow | Skip (direct mode) |\n|---|---|\n| Feature with ACs and scope | One-line fix |\n| You want to read plan before diff | Spec already signed elsewhere |\nTeam shares `.agents/` rules |\nFully ad-hoc spike |\n\n**Commit:** `AGENTS.md`\n\n, `.agents/`\n\n, `.agents-docs/`\n\n, adapters, `.specflow-version`\n\n**Do not commit:** `.agents-state/`\n\n```\nnpx @ceatoleii/specflow sync   # updates engine; keeps .agents-docs/\n```\n\n| Issue | First step |\n|---|---|\n| Assistant ignores phases | Is `.flow-enabled` present? `specflow doctor`\n|\n| Code without plan | Did you `/approve` ? Check `phase.md`\n|\n| Review fails tests | Fill `.agents-docs/verification.md`\n|\n\nMore: [Troubleshooting](https://ceatoleii.github.io/specflow/troubleshooting.html)\n\n`npx @ceatoleii/specflow init`\n\n`new task`\n\nwhen the contract matters`/approve`\n\nbefore the diff**Links**\n\n`article-medium-en.md`\n\nin the repoWhat feature would you run through `/approve`\n\nfirst? 👇", "url": "https://wpnews.pro/news/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer", "canonical_source": "https://dev.to/matas_espinoza_aaab42da0/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer-3nnl", "published_at": "2026-05-25 19:50:41+00:00", "updated_at": "2026-05-25 20:03:17.844745+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products", "ai-startups", "generative-ai"], "entities": ["SpecFlow", "Cursor", "SDD", "Implementer", "Refiner", "Reviewer", "ceatoleii", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer", "markdown": "https://wpnews.pro/news/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer.md", "text": "https://wpnews.pro/news/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer.txt", "jsonld": "https://wpnews.pro/news/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer.jsonld"}}