SpecFlow Documentation

Security-first, cost-aware, test-driven AI development methodology.

What is SpecFlow?

SpecFlow is a PM-orchestrated development methodology that ensures every feature is properly analyzed, tested, and reviewed before shipping. Unlike traditional AI-assisted coding that produces fast but fragile code, SpecFlow enforces quality gates at every stage.

Key Differentiators

Test-Driven Development (TDD)

SpecFlow enforces TDD at the workflow level:

TEA (Test Engineering Analyst) creates test scenarios before development
QA-first routing: For behavioral features, QA writes failing tests BEFORE Dev implements
Test evidence required: Stories cannot be marked complete without passing test evidence
Automated verification: validate_completion() enforces test pass counts and timestamps

Automated User Acceptance Testing (UAT)

SpecFlow includes automated UAT triggers:

Signal detection: UI components, Gherkin scenarios, user-facing workflows trigger UAT
3+ signals threshold: Automatically routes to UAT verification
UAT execution skill: Review agent runs Gherkin scenarios against the implementation
Evidence capture: Screenshots and API responses prove acceptance criteria met

Multi-Lens Review Loop

Dynamic skill-based code review:

Skill discovery: Automatically detects which review skills apply to your code
Parallel review: Multiple reviewers (security, performance, accessibility) run simultaneously
Drift detection: Catches when implementation diverges from specification
Targeted re-review: PM can invoke specific skills mid-workflow

Slop Detection

Prevents AI-generated low-quality patterns:

Pattern recognition: Detects common AI "slop" patterns (unnecessary abstractions, over-engineering)
Automated flags: Raises concerns during review when slop patterns detected
Quality gates: Blocks completion until issues addressed
Library-first enforcement: Prefers battle-tested libraries over custom implementations

Tracker Integration (Upcoming)

Automated project management and scrum (that doesn't require a meeting to plan the planning meeting):

Issue sync: Bi-directional sync with GitHub Issues, Jira, Linear, and Rally
Autonomous development: Pick up stories, implement, create PRs, update tracker status
Sprint automation: Auto-create sprints from epics and stories
Status updates: Workflow transitions automatically update tracker status

Standing on the Shoulders of Giants

SpecFlow doesn't reinvent the wheel. We curate decades of battle-tested methodologies—STRIDE threat modeling, BOSS acceptance criteria, FinOps cost analysis, Gherkin test scenarios—and make them accessible through AI orchestration.

Built on the foundation of the BMAD Method (opens in a new tab), SpecFlow delivers the expertise without the complexity. You get rigorous software engineering practices without needing a PhD in each discipline.

Quick Start

npx specflow init
/sf:pm "build a user authentication system"

The Three Pillars

Every feature flows through these pillars based on its scope:

Scope	Pillars Applied	TDD Depth
trivial	None	None
small	Testing	Unit tests
medium	Security + Testing	Unit + E2E
large	All three	Full + UAT
complex	All three + research	Full + UAT + manual

How It Works

User Request
    ↓
PM Orchestrator ─────────────────────────────────────┐
    ↓                                                │
Analyst → Architect → Security → Cost → TEA          │
    ↓                                                │
Requirements Lock (frozen spec)                      │
    ↓                                                │
┌─────────────────────────────────────────┐         │
│ QA-First (if behavioral)                │         │
│   → QA writes failing tests             │         │
│   → Dev implements to pass              │         │
│                                         │         │
│ Dev-First (if technical)                │         │
│   → Dev implements with TDD             │         │
│   → QA validates                        │         │
└─────────────────────────────────────────┘         │
    ↓                                                │
Multi-Lens Review ←──────────────────────────────────┘
    ↓                  (drift? → back to PM)
UAT Verification (if triggered)
    ↓
Ship ✓

Documentation

Getting Started - Installation and first feature
Commands - All available slash commands
Architecture - PM orchestration and agent flow
Methodology - STRIDE, BOSS, TEA, and cost frameworks
Agents - The personas behind SpecFlow

Contributors

Dean Banik

Getting Started