Specflow

Specs that enforce themselves.

LLMs drift. You write a rule; three iterations later the model ignores it. Specflow turns your specs into contract tests that break the build when violated — so drift can't ship.

specflow init .          # scaffold contracts, hooks, skill
specflow doctor .        # check everything is wired up
specflow enforce .       # run contract enforcement

Nothing goes in your project root except CLAUDE.md. Contracts, tests, and config live in .specflow/ and .claude/.

---

Install

npm install -g @robotixai/specflow-cli

Or via install script:

curl -sSL https://raw.githubusercontent.com/fall-development-rob/specflow-cli/main/scripts/install.sh | bash

---

What You Get

After specflow init .:

.specflow/
  contracts/          generated contracts tailored to your stack
  tests/e2e/          journey test stubs
  config.json         your path preferences
  knowledge.db        knowledge graph (violations, fixes, trends)
  baseline.json       compliance snapshot
.claude/
  settings.json       Claude Code hook config
  skills/specflow.md  Specflow skill for Claude Code
  .defer-journal      journey deferrals
.git/hooks/commit-msg  rejects commits without #issue
CLAUDE.md              appended, never overwritten

Init detects your stack (language, framework, ORM) and generates contracts matched to it. Use -y for defaults, --skip-contracts for structure only.

---

CLI Commands

Command	What it does
specflow init [dir]	Detect stack, generate contracts, scaffold hooks and graph
specflow generate [dir]	Re-detect stack and regenerate contracts (no re-init)
specflow doctor [dir]	14 health checks across contracts, hooks, graph
specflow enforce [dir]	Run contracts against source code, record violations
specflow status [dir] [--history]	Compliance dashboard with trends and hotspots
specflow impact <contract-id>	Show blast radius of a contract change
specflow update [dir]	Update hooks and settings
specflow audit <issue>	Audit a GitHub issue (11 compliance markers)
specflow compile <csv>	Compile journey CSV to YAML contracts + test stubs
specflow graph [dir]	Validate contract cross-references
specflow contract list	List available contract templates
specflow contract create	Create contract from template or AI
specflow agent list	List all 28 agents by category
specflow agent show <name>	Show an agent's full prompt
specflow agent search <query>	Search agents
specflow mcp start	Start MCP server for Claude Code
specflow mcp register	Register as Claude Code MCP server

---

How It Works

Contracts are YAML files that define rules your code must follow:

- id: SEC-001
  scope:
    - "src/**/*.{ts,js}"
  behavior:
    forbidden_patterns:
      - pattern: /(password|secret|token)\s*[:=]\s*['"][^'"]{8,}['"]/i
        message: "Hardcoded secret — use environment variable"

Break a rule → build fails. specflow enforce scans source code against all contract patterns.

Hooks fire automatically in Claude Code:

• Write/Edit → compliance check against contracts
• Bash (build/commit) → journey test trigger
• commit-msg → rejects commits without #issue

Knowledge graph (.specflow/knowledge.db) tracks violations over time:

• specflow status --history shows compliance trends
• specflow impact shows blast radius of contract changes
• Fix suggestions based on what worked before

---

Agents

28 prompt-template agents across 7 categories:

Category	Count	Examples
Compliance	7	board-auditor, contract-validator, quality-gate
Generation	9	contract-generator, specflow-writer, ci-builder
Orchestration	5	waves-controller, sprint-executor, dependency-mapper
Documentation	3	readme-audit, readme-restructure, adoption-advisor
Remediation	2	heal-loop, specflow-uplifter
Testing	1	test-runner
Lifecycle	1	ticket-closer

specflow agent list              # see all agents
specflow agent show heal-loop    # read full prompt
specflow agent search testing    # find by category

Agents are markdown files with YAML frontmatter. They are prompt templates — use them with Claude Code or any LLM.

---

MCP Integration

Register Specflow as a Model Context Protocol server:

specflow mcp register

Exposes 14 tools to Claude Code:

Tool	Purpose
specflow_list_contracts	List contracts with rule counts
specflow_check_code	Check a code snippet against contracts
specflow_get_violations	Scan files for violations
specflow_validate_contract	Validate a YAML contract
specflow_audit_issue	Audit a GitHub issue
specflow_compile_journeys	Compile journey CSV
specflow_verify_graph	Verify contract cross-references
specflow_list_agents	List agents
specflow_get_agent	Get agent prompt
specflow_defer_journey	Defer/undefer journeys
specflow_get_schema	Get contract YAML schema
specflow_get_example	Get annotated example contract
specflow_query_graph	Query knowledge graph (trends, hotspots, impact)
specflow_get_fix_suggestion	Get fix suggestion for a rule

---

CI Integration

Instead of static templates, Specflow includes a ci-builder agent that inspects your project and generates a tailored CI pipeline:

specflow agent show ci-builder

Supports GitHub Actions, GitLab CI, Azure Pipelines, CircleCI, and Bitbucket.

---

FAQ

Isn't this just more testing? No. Tests verify behaviour. Contracts verify architecture. "No localStorage in service workers" survives any refactor.

What if I don't have a perfect spec? Run specflow init — it detects your stack and generates tailored contracts. Your first custom contract can be: whatever we're doing now, don't break it.

Can LLMs actually follow contracts? Even if they don't, specflow enforce catches it. You don't need the LLM to behave. You need it to be checkable.

---

Links

Architecture Docs	ADRs, PRDs, DDDs, master plan
CI Integration	CI pipeline setup via agent
Issues	Bugs and ideas