DEV Community

Cover image for SpecFlow: Multi-Agent SDD in Cursor (4 phases, /approve, single code writer)
Matías Espinoza
Matías Espinoza

Posted on • Originally published at ceatoleii.github.io

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

#cursor #ai #opensource #devtools

SpecFlow: Multi-Agent SDD in Cursor (4 phases, /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 · Pipeline: Requirement → Plan → Tasks → Code → Review

npx @ceatoleii/specflow init
Enter fullscreen mode Exit fullscreen mode

Full guide: ceatoleii.github.io/specflow

What problem it solves

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

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
Enter fullscreen mode Exit fullscreen mode

Architecture in 60 seconds

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 vs flow mode

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

Install (2 minutes)

Requirements: Node.js ≥ 18, interactive terminal, project root.

npx @ceatoleii/specflow init
specflow doctor
Enter fullscreen mode Exit fullscreen mode

Add to .gitignore:

.agents-state/
Enter fullscreen mode Exit fullscreen mode

What 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.

Walkthrough: rate limiting on /api/search

Example feature:

Max 100 req/min per IP, HTTP 429 with standard JSON, existing tests stay green.

1. Start flow

In Cursor chat:

new task
Enter fullscreen mode Exit fullscreen mode

Also: flow on, or new task from LIN-123 (Linear + MCP).

Verify:

specflow doctor
# Expect .flow-enabled and phase.md = refining
Enter fullscreen mode Exit fullscreen mode

2. 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
Enter fullscreen mode Exit fullscreen mode

You review ACs and Out of Scope — reply in chat to fix; no need to hand-edit the file.

3. Designing → 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)
Enter fullscreen mode Exit fullscreen mode

Read plan.md (files, approach). If the plan sneaks in unrequested refactors, ask for changes before approve.

4. /approve gate 

/approve
Enter fullscreen mode Exit fullscreen mode

Also valid: approved, go ahead (locale-dependent phrases in rules).

  • Phase → implementing
  • Only now may Implementer touch src/
  • With Linear enabled: issue → In Progress (via Cursor MCP)

5. Implementing

Watch:

  • tasks.md — [ ] → [~] → [x]
  • git diff — must match plan.md

On spec gaps, answer in chat — Implementer should not guess.

6. Reviewing → 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.
Enter fullscreen mode Exit fullscreen mode
Outcome What happens
PASS history/YYYY-MM-DD-slug/, flow off
FAIL Back to Implementer with concrete fixes

Five design principles

  1. Spec before code — No /approve, no implementation.
  2. One writer — Only Implementer in src/, lib/, etc.
  3. Explicit state — phase.md, task.md, plan.md under .agents-state/current/.
  4. Portable rules — .agents/ via sync; project facts in .agents-docs/ (never overwritten by sync).
  5. Zero overhead by default — Without an active task, assistant behaves normally.

Commands you’ll actually use

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
Enter fullscreen mode Exit fullscreen mode

Linear + Cursor MCP (optional)

  • Config: specflow linear setup or wizard during init
  • No API keys in the CLI — the Cursor agent uses the Linear MCP plugin
  • Default state mapping:
SpecFlow event Linear state
Refining complete Todo
/approve In Progress
Review PASS Done

Details: Linear Integration

When to skip SpecFlow

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

Team workflow

Commit: AGENTS.md, .agents/, .agents-docs/, adapters, .specflow-version

Do not commit: .agents-state/

npx @ceatoleii/specflow sync   # updates engine; keeps .agents-docs/
Enter fullscreen mode Exit fullscreen mode

Quick troubleshooting

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

Wrap-up

  • Install rules and templates with npx @ceatoleii/specflow init
  • Start with new task when the contract matters
  • Approve design with /approve before the diff
  • One agent writes code; Reviewer closes with per-AC evidence

Links

What feature would you run through /approve first? 👇

Top comments (0)