specflow

specflow

A Specification-Driven Development (SDD) toolkit for AI-assisted teams. specflow turns natural language into EARS requirements, wraps them in four-section Prompt Contracts, publishes them into a Vision → Epic → Feature → Task hierarchy on GitHub, drives TDD with explicit human-in-the-loop gates, and distils every cycle into an LLM-curated engineering wiki.

It ships two ways:

• Claude Code plugin — install with /plugin install, get nine /specflow:* slash-commands. See Install (Claude Code).
• GitHub Copilot customization layer — install with a curl ... install.sh | bash one-liner, get matching /specflow-* Copilot prompts and a wiki-curator custom agent. See Install (GitHub Copilot).

The same canonical skills (skills/<name>/SKILL.md) drive both runtimes — no duplicated logic.

Status & Scope

specflow is a personal experiment: an attempt to find a lighter middle ground between spec-kit and superpowers. spec-kit is a comprehensive SDD toolkit with a large surface area; superpowers is a broad, general-purpose skills framework. specflow picks a narrow slice — EARS → Prompt Contracts → GitHub Projects, plus a curated wiki on top — and wires it together in the way that fits my workflow.

That means:

• Opinionated by design. The pipeline, artifact layout, Kanban columns, wiki schema, and config shape reflect my own projects and preferences, not a general standard.
• Not a product. It ships as-is, without roadmap guarantees or support commitments.
• Use it freely, adapt it freely. MIT-licensed. Fork it, carve out the pieces you want, rewire the skills — everything is plain markdown.
• Composable, not exclusive. specflow is designed to work alongside superpowers rather than replace it. /specflow:implement can hand off to superpowers:test-driven-development, and the brainstorming / planning / verification skills from superpowers complement specflow's artifact pipeline cleanly.
• Pairs with triad. triad is a companion plugin — a multi-agent TDD orchestrator (DESIGN → RED → GREEN → REFACTOR → QUALITY) that specflow prefers for the implementation phase when it's installed. The wiki's per-cycle distillation hook (Mode A) is designed to fit a Phase 8.5 in that orchestrator.

If you want a more complete or vendor-backed SDD experience, use spec-kit. If you want a broader skills toolkit, use superpowers. If you want a small, hackable, GitHub-native pipeline tuned to one person's taste, this is it.

Why

AI-assisted development produces inconsistent results when requirements are informal and project memory is scattered across chat history. Vague specs lead to hallucinated features and missed edge cases; lost context across cycles leads to re-discovery, re-litigation of decisions, and gradual architectural drift. specflow tackles both halves of the problem:

Spec document / feature idea
    ↓  formalize
Unambiguous EARS requirements (testable, traceable)
    ↓  contract
Prompt Contracts (deterministic AI agent instructions)
    ↓  plan
GitHub hierarchy (Vision → Epic → Feature → Task)
    ↓  publish
Real GitHub milestones, issues, sub-issues
    ↓  implement
TDD execution with human gates
    ↓  track
Kanban status from live GitHub data
    ↓  distil
Curated engineering wiki (LLM-maintained second brain)

Every step produces a persistent markdown artifact. The files are the source of truth — not conversation memory.

Core Principles

Spec-as-Source

Every GitHub issue traces to a Prompt Contract, which traces to an EARS requirement, which traces to a spec document section. Nothing is invented by AI.

EARS Requirements

Easy Approach to Requirements Syntax eliminates ambiguity by constraining natural language into six patterns:

Pattern	Template	Use When
Ubiquitous	The system shall [action].	Always active, no trigger
Event-driven	When [event], the system shall [action].	Discrete trigger
State-driven	While [state], the system shall [action].	Sustained condition
Conditional	If [condition], then the system shall [action].	Error/edge cases
Negative	The system shall not [action].	Genuine prohibitions
Complex	While [state], when [event], the system shall [action].	State + trigger

If something can't be written as EARS, it's flagged as ambiguous — never guessed.

Prompt Contracts

Each atomic task gets a four-section contract that drives deterministic AI agent behavior: