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

> Source: <https://dev.to/matas_espinoza_aaab42da0/specflow-multi-agent-sdd-in-cursor-4-phases-approve-single-code-writer-3nnl>
> Published: 2026-05-25 19:50:41+00:00

`/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? 👇