DEV Community: Matías Espinoza

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

Matías Espinoza — Mon, 25 May 2026 19:50:41 +0000

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

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

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

Add to .gitignore:

.agents-state/

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

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

Verify:

specflow doctor
# Expect .flow-enabled and phase.md = refining

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

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)

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

4. `/approve` gate

/approve

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.

Outcome	What happens
PASS	`history/YYYY-MM-DD-slug/`, flow off
FAIL	Back to Implementer with concrete fixes

Five design principles

Spec before code — No /approve, no implementation.
One writer — Only Implementer in src/, lib/, etc.
Explicit state — phase.md, task.md, plan.md under .agents-state/current/.
Portable rules — .agents/ via sync; project facts in .agents-docs/ (never overwritten by sync).
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

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/

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

npm: @ceatoleii/specflow
Repo: github.com/ceatoleii/specflow
Docs: ceatoleii.github.io/specflow
More SDD context: article-medium-en.md in the repo

What feature would you run through /approve first? 👇

SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)

Matías Espinoza — Mon, 25 May 2026 19:49:01 +0000

SpecFlow: SDD multi-agente en Cursor (4 fases, `/approve`, un solo escritor de código)

SpecFlow es un CLI que instala Spec-Driven Development (SDD) en tu repositorio: cuatro agentes por fase, specs en markdown y solo Implementer puede editar código fuente. Sigue siendo chat en Cursor — activas el flujo cuando la feature lo merece.

@ceatoleii/specflow · Pipeline: Requisito → Plan → Tareas → Código → Revisión

npx @ceatoleii/specflow init

Guía completa: ceatoleii.github.io/specflow/es

Qué problema resuelve

Síntoma	Mecanismo SpecFlow
Requisito vago → diff enorme	Refiner → `task.md` con AC1, AC2…
Código antes de acordar diseño	SDD espera `/approve`
Varios “agentes” tocando `src/`	Solo Implementer escribe fuente
“Listo” sin evidencia	Reviewer → `review.md` por AC

Pipeline: Requisito → Plan → Tareas → Código → Revisión

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

Arquitectura en 60 segundos

Fase (`phase.md`)	Agente	¿Escribe código?	Salida
`refining`	Refiner	No	`task.md`
`designing`	SDD	No	`plan.md`, `tasks.md`
`implementing`	Implementer	Sí	Código + `tasks.md`
`reviewing`	Reviewer	No	`review.md`

Modo directo vs modo flujo

	Modo directo	Modo flujo
Señal	Sin `.agents-state/.flow-enabled`	Archivo presente
Activar	—	`nueva tarea`, `flow on`, `activar flujo`
Apagar	—	`flow off`, `modo directo`
Uso	Typos, spikes, exploración	Features con ACs claros

Instalación (2 minutos)

Requisitos: Node.js ≥ 18, terminal interactiva, raíz del proyecto.

npx @ceatoleii/specflow init
specflow doctor

Añade al .gitignore:

.agents-state/

Qué instala `init`

Ruta	Quién la mantiene	Notas
`AGENTS.md`	SpecFlow (`init` / `sync`)	Entrada para cualquier IDE
`.agents/`	SpecFlow	Reglas de fase — no editar
`.agents-docs/`	Tú	Stack, convenciones, `verification.md`
`.agents-state/`	Runtime	Estado por tarea — gitignore
`.cursor/rules/_specflow.mdc`	SpecFlow	Adaptador Cursor (default v2.2+)
`.specflow-linear.json`	Opcional	Sync Linear vía MCP en Cursor

Regla de oro: completa .agents-docs/ antes de tareas serias — los agentes leen eso en cada flujo.

Walkthrough: rate limiting en `/api/search`

Feature de ejemplo:

Máx. 100 req/min por IP, HTTP 429 con JSON estándar, tests existentes en verde.

1. Activar flujo

En el chat de Cursor:

nueva tarea

Alternativas: flow on, activar flujo, o nueva tarea desde LIN-123 (Linear + MCP).

Comprueba:

specflow doctor
# Debe ver .flow-enabled y phase.md = refining

2. Refining → `task.md`

El Refiner pregunta; tú respondes. Resultado típico:

# 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

Tú revisas ACs y Out of Scope — no hace falta editar el archivo; corrige en chat si algo falla.

3. Designing → `plan.md` + `tasks.md`

El SDD propone diseño. Fragmento de tasks.md (orden TDD):

## 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)

Lee plan.md (archivos, enfoque). Si el plan incluye refactors no pedidos, pide cambios antes de aprobar.

4. Puerta `/approve`

/approve

También válido: aprobado, dale.

Fase → implementing
Solo ahora Implementer puede tocar src/
Con Linear habilitado: issue → In Progress (vía MCP en Cursor)

5. Implementing

Monitorea:

tasks.md — [ ] → [~] → [x]
git diff — debe alinearse con plan.md

Si hay ambigüedad en la spec, responde en chat; el Implementer no debe adivinar.

6. Reviewing → `review.md`

El Reviewer ejecuta comandos de .agents-docs/verification.md (ej. npm test, npm run lint).

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

Resultado	Qué pasa
PASS	`history/YYYY-MM-DD-slug/`, flujo apagado
FAIL	Vuelve a Implementer con lista concreta

Los 5 principios de diseño

Spec antes que código — Sin /approve, no hay implementación.
Un solo escritor — Solo Implementer en src/, lib/, etc.
Estado explícito — phase.md, task.md, plan.md en .agents-state/current/.
Reglas portables — .agents/ con sync; hechos del proyecto en .agents-docs/ (nunca sobrescrito por sync).
Cero overhead por defecto — Sin tarea activa, el asistente es normal.

Comandos del día a día

Comando	Cuándo
`specflow init`	Primera instalación
`specflow doctor`	Verificar archivos y fase
`specflow doctor --run`	+ ejecutar `verification.md`
`specflow status`	Versión, Linear on/off, updates
`specflow sync`	Actualizar motor y adaptadores
`specflow linear setup`	Habilitar sync Linear (MCP)

specflow status
specflow sync

Linear + Cursor MCP (opcional)

Config: specflow linear setup o wizard en init
No usa API keys en el CLI — el agente en Cursor llama al plugin Linear MCP
Eventos por defecto:

Evento SpecFlow	Estado Linear
Refining completo	Todo
`/approve`	In Progress
Review PASS	Done

Detalle: Integración Linear

Cuándo NO usar SpecFlow

Usa flujo	Omite (modo directo)
Feature con ACs y alcance	Fix de una línea
Quieres leer plan antes del diff	Spec ya firmada fuera del repo
Equipo con mismas reglas en `.agents/`	Spike exploratorio 100% ad-hoc

Trabajo en equipo

Commitear: AGENTS.md, .agents/, .agents-docs/, adaptadores, .specflow-version

No commitear: .agents-state/

npx @ceatoleii/specflow sync   # actualiza motor; preserva .agents-docs/

Troubleshooting rápido

Problema	Primer paso
El asistente ignora fases	¿Existe `.flow-enabled`? `specflow doctor`
Código sin plan	¿Dijiste `/approve`? Revisa `phase.md`
Review falla tests	Completa `.agents-docs/verification.md`

Más: Solución de problemas

Resumen

Instalas reglas y plantillas con npx @ceatoleii/specflow init
Activas con nueva tarea cuando el contrato importa
Apruebas diseño con /approve antes del diff
Un agente escribe código; Reviewer cierra con evidencia por AC

Links

npm: @ceatoleii/specflow
Repo: github.com/ceatoleii/specflow
Docs ES: ceatoleii.github.io/specflow/es
Más contexto SDD: article-medium-es.md en el repo

¿Qué feature probarías primero con /approve? 👇

DEV Community: Matías Espinoza

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

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

What problem it solves

Architecture in 60 seconds

Direct mode vs flow mode

Install (2 minutes)

What init installs

Walkthrough: rate limiting on /api/search

1. Start flow

2. Refining → task.md

3. Designing → plan.md + tasks.md

4. /approve gate

5. Implementing

6. Reviewing → review.md

Five design principles

Commands you’ll actually use

Linear + Cursor MCP (optional)

When to skip SpecFlow

Team workflow

Quick troubleshooting

Wrap-up

SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)

SpecFlow: SDD multi-agente en Cursor (4 fases, /approve, un solo escritor de código)

Qué problema resuelve

Arquitectura en 60 segundos

Modo directo vs modo flujo

Instalación (2 minutos)

Qué instala init

Walkthrough: rate limiting en /api/search

1. Activar flujo

2. Refining → task.md

3. Designing → plan.md + tasks.md

4. Puerta /approve

5. Implementing

6. Reviewing → review.md

Los 5 principios de diseño

Comandos del día a día

Linear + Cursor MCP (opcional)

Cuándo NO usar SpecFlow

Trabajo en equipo

Troubleshooting rápido

Resumen

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

What `init` installs

Walkthrough: rate limiting on `/api/search`

2. Refining → `task.md`

3. Designing → `plan.md` + `tasks.md`

4. `/approve` gate

6. Reviewing → `review.md`

SpecFlow: SDD multi-agente en Cursor (4 fases, `/approve`, un solo escritor de código)

Qué instala `init`

Walkthrough: rate limiting en `/api/search`

2. Refining → `task.md`

3. Designing → `plan.md` + `tasks.md`

4. Puerta `/approve`

6. Reviewing → `review.md`