/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:
npx @ceatoleii/specflow init
Full guide: 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
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
task.md
Refiner asks questions; you answer. Typical output:
## 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
:
## 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
| 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
npx @ceatoleii/specflow init
new task
when the contract matters/approve
before the diffLinks
article-medium-en.md
in the repoWhat feature would you run through /approve
first? 👇