SpecFlow is a simplified, open-source implementation of a spec-driven planning and verification layer for AI-assisted software development.
It explores the core idea behind tools like Traycer: making intent explicit, executable, and verifiable before AI-generated code reaches production.
Most AI coding tools jump directly from a vague prompt to code. This often leads to:
- Agent drift
- Unexpected file changes
- Violated constraints
- Costly rework
SpecFlow introduces a lightweight workflow layer that sits between intent and execution:
Plan → Execute → Verify → Repeat
Artifacts are structured, versioned specifications that capture intent explicitly.
They include:
- Scope
- Constraints
- Acceptance criteria
All planning, execution, and verification is anchored to an Artifact. Agents are never allowed to freestyle.
Artifacts are decomposed into a structured plan consisting of phases:
- DESIGN
- IMPLEMENTATION
- VERIFICATION
Each phase contains explicit, traceable tasks. The same Artifact always produces the same Plan.
SpecFlow does not own AI agents.
Instead, it defines a clean adapter interface that allows:
- Mock agents
- CLI-based agents
- AI coding tools (Cursor, Claude Code, etc.)
This mirrors real-world workflows where teams use multiple tools.
After each task execution, SpecFlow verifies results against the original Artifact.
Verification rules:
- Detect scope drift
- Enforce hard constraints
- Track acceptance criteria
Issues are categorized by severity:
- Info
- Warning
- Error
Critical violations halt the workflow immediately.
- Define an Artifact (e.g., "Add JWT authentication")
- Generate a deterministic Plan
- Execute tasks via an external agent
- Verify each result against intent
- Stop early if violations are detected
This ensures no surprises and production-ready changes.
SpecFlow demonstrates how AI-assisted development can scale safely on complex codebases by:
- Anchoring work to explicit specs
- Reducing hallucinations
- Making verification a first-class concern
- TypeScript
- Node.js
- Zod (schema validation)
- Deterministic mock agents
This project is a conceptual prototype intended to demonstrate workflow design and system thinking, not a full production tool.