SpecFlow streamlines multi-agent SDD workflows in Cursor with clear approvals

Spec-Driven Development (SDD) often suffers from vague requirements leading to bloated code changes and unclear ownership. The open-source tool SpecFlow bridges this gap by embedding a four-phase multi-agent workflow directly into Cursor, ensuring only one agent can write source code at a time. Triggered selectively for high-stakes features, the tool enforces an approval gate before any implementation starts, reducing ambiguity and miscommunication in engineering teams.

From chaotic specs to structured development

Traditional SDD workflows struggle when requirements are ambiguous or acceptance criteria are scattered across discussions. SpecFlow addresses this by introducing a four-phase pipeline—Refining, Designing, Implementing, and Reviewing—each managed by a dedicated agent. The Refiner agent clarifies vague requirements into structured task documents, while the Design agent proposes a technical plan without touching source code. Only after an explicit /approve command does the Implementer agent gain write access to the codebase, ensuring that code changes are always aligned with approved specifications.

How the four phases work together

Each phase in SpecFlow operates with strict boundaries and outputs that become inputs for the next stage. The Refining phase generates a task.md document containing clearly defined acceptance criteria, constraints, and out-of-scope items. The Design phase then produces plan.md and tasks.md files, breaking down the implementation into verifiable tasks. Once the /approve command is issued, the Implementer agent executes the plan, updating the tasks.md status as work progresses. Finally, the Reviewer agent validates the changes against the acceptance criteria, producing a review.md document that either passes or fails the implementation.

Agent responsibilities by phase

• Refiner – Clarifies requirements and writes task.md with acceptance criteria
• SDD Agent – Proposes design plans in plan.md and task breakdowns in tasks.md
• Implementer – Writes source code and updates tasks.md based on progress
• Reviewer – Validates the implementation and generates review.md

Teams can toggle between direct mode—for quick fixes or exploration—and flow mode, which activates the multi-agent pipeline for features with well-defined acceptance criteria.

Setting up SpecFlow in under two minutes

Getting started with SpecFlow requires Node.js 18 or higher and a terminal with interactive capabilities. Begin by running:

npx @ceatoleii/specflow init specflow doctor

This command scaffolds the necessary directory structure, including .agents-docs/ for project-specific rules and .agents-state/ for runtime tracking. Add .agents-state/ to your .gitignore to prevent accidental commits of runtime states.

Key directories and their purpose

• AGENTS.md – Maintained by SpecFlow, defines the agent roles and rules
• .agents-docs/ – Contains project-specific conventions and verification scripts
• .agents-state/current/ – Tracks the active task and phase (e.g., phase.md, task.md)
• .cursor/rules/_specflow.mdc – Cursor-specific rules to enforce SpecFlow behavior

Before initiating any serious feature development, ensure .agents-docs/verification.md is complete, as agents rely on these scripts to validate acceptance criteria during the Review phase.

A step-by-step walkthrough: implementing rate limiting

Consider a feature requiring rate limiting for an /api/search endpoint. The goal is to block anonymous traffic exceeding 100 requests per minute while ensuring existing tests remain unaffected. Here’s how SpecFlow guides the process:

1. Activating the flow

Begin by triggering the multi-agent workflow in Cursor:

nueva tarea

Alternative commands include flow on or activar flujo. Verify the setup with:

specflow doctor

This command checks for .flow-enabled and confirms the current phase is set to refining.

2. Refining the requirement

The Refiner agent prompts for clarification, resulting in a structured task.md document. For the rate-limiting feature, the output might include:

• A clear goal statement
• Three acceptance criteria, including HTTP 429 responses and JSON error payloads
• Constraints, such as reusing existing error middleware
• Explicit out-of-scope items, like per-API-key quotas

Review the generated file, and correct any inaccuracies directly in the Cursor chat before proceeding.

3. Designing the solution

The SDD agent drafts a technical plan in plan.md and breaks it into actionable tasks in tasks.md. Example tasks include:

• Writing an integration test to verify the 429 response
• Creating an in-memory rate-limiting middleware
• Wiring the middleware to the /api/search route only
• Running the full test suite to ensure no regressions

If the plan introduces unrequested refactors, request changes before approving the design.

4. Approving the design

Issue the /approve command to transition from design to implementation. This command:

• Shifts the phase to implementing
• Grants the Implementer agent exclusive write access to source files
• Updates the Linear issue status to "In Progress" if integrated via MCP

Only after this approval can the Implementer begin coding.

5. Implementing the feature

Monitor progress by tracking the tasks.md file, where tasks transition from [ ] to [~] to [x] as work completes. The Implementer should strictly adhere to the plan.md and avoid speculative changes. If ambiguities arise in the specification, seek clarification in the Cursor chat rather than making assumptions.

6. Reviewing the implementation

The Reviewer agent executes verification scripts from .agents-docs/verification.md and generates a review.md report. For the rate-limiting feature, the report might validate:

• The 429 response for rate-limited requests
• The exact JSON error payload structure
• Zero failures in the existing test suite

If all criteria pass, the task is archived to history/YYYY-MM-DD-slug/ and the flow is disabled. If any criteria fail, the implementation returns to the Implementer with specific feedback.

Design principles behind SpecFlow

SpecFlow enforces five core principles to maintain clarity and accountability:

• Specification-first development – No code changes occur without an approved specification
• Single writer rule – Only the Implementer agent can modify source code during active flows
• Explicit state tracking – Each phase writes clear, versioned artifacts (e.g., phase.md, task.md)
• Portable rules – Agent roles and conventions live in .agents/, while project-specific rules reside in .agents-docs/
• Minimal overhead – When no task is active, Cursor behaves as usual, avoiding unnecessary complexity

Essential day-to-day commands

• specflow init – Initialize SpecFlow in a new project
• specflow doctor – Verify the current setup and active phase
• specflow doctor --run – Execute verification scripts for the current task
• specflow status – Check SpecFlow version and Linear integration status
• specflow sync – Update agent rules and Cursor adapters
• specflow linear setup – Configure Linear integration via MCP without API keys

By integrating SpecFlow into Cursor, engineering teams gain a structured, approval-gated workflow that reduces ambiguity, enforces accountability, and ensures every code change aligns with approved specifications.