Work in progress. SpecFlow is in active development and used daily by the author across multiple projects, but the API surface, skill interfaces, and documentation are still evolving. Expect rough edges. Issues and feedback welcome.

SpecFlow gives AI coding agents a structured development lifecycle. Instead of jumping straight to code, features go through Requirements → Design → Tasks → Implementation, with human approval gates at each transition. A real-time web dashboard lets you review, approve, or reject at every phase.

Built on Pimzino/spec-workflow-mcp's core engine (sequential spec workflow, real-time dashboard, blocking approval gates). This project extends the lifecycle with additional phases, multi-project support, and a shipped skill system.

What You Get

The npm package (@lbruton/specflow) ships:

• 8 MCP tools and 7 MCP prompts for spec lifecycle management
• A real-time web dashboard for approvals and progress tracking
• 11 spec templates (requirements, discovery, design, tasks, readiness report, steering docs, review prompts)
• Multi-project support via project config files

The GitHub repo additionally ships:

• 12 lifecycle skills (/spec, /start, /prime, /wrap, /retro, /audit, /discover, /chat, /issue, /pr-cleanup, /publish-templates, /migrate-skill)
• 11 slash commands and background subagent definitions
• Agent-specific instruction files (CLAUDE.md, GEMINI.md, CODEX.md)

These are plain markdown files, installed by copying — not bundled in npm.

Quick Start

Install the MCP server

Add to your agent's MCP config (Claude Code example — ~/.claude/settings.json):

{
  "mcpServers": {
    "specflow": {
      "command": "npx",
      "args": ["-y", "@lbruton/specflow@latest", "."]
    }
  }
}

Works with any MCP-compatible agent. Verified with Claude Code, Gemini CLI, Codex CLI, and OpenCode.

Install skills and commands (optional, recommended for Claude Code)

git clone https://github.com/lbruton/specflow.git ~/specflow-source
cp -r ~/specflow-source/skills/* ~/.claude/skills/
cp -r ~/specflow-source/commands/* ~/.claude/commands/
cp -r ~/specflow-source/agents/* ~/.claude/agents/

Start the dashboard

npx @lbruton/specflow@latest --dashboard --port 5051

Spec Workflow

Every non-trivial feature follows the same path. Approval required at each gate.

[Discovery]  →  Requirements  →  Design  →  Tasks  →  Implementation
  optional          ↑              ↑          ↑            ↑
                 approval       approval   approval    log artifacts

An optional Discovery phase (/discover) supports structured research before committing to a spec. Specs live on disk as structured markdown — not in any agent's memory. This means you can start a spec in one agent and continue in another. The dashboard tracks progress regardless of which agent is driving.

MCP Tools

| Tool | Description | | --------------------- | ------------------------------------------------------- | | spec-status | Get detailed status of a spec | | spec-list | List all specs across projects | | approvals | Manage phase approval workflow | | log-implementation | Record implementation artifacts | | write-spec-doc | Create or update spec documents | | detect-conventions | Detect and persist project-conventions.json from source | | spec-workflow-guide | Get workflow guidance | | steering-guide | Access project steering documents |

MCP Prompts

| Prompt | Description | | ---------------------------- | ----------------------------------------------- | | create-spec | Create a new spec from requirements | | create-steering-doc | Create project steering documentation | | implement-task | Generate implementation plan for a task | | refresh-tasks | Re-sync task state from spec files | | spec-status | Phase and completion summary for a spec | | inject-spec-workflow-guide | Inject the spec workflow guide into the session | | inject-steering-guide | Inject the steering doc guide into the session |

Shipped Skills

These are markdown skill definitions installed by copying from the repo, not MCP tools.

| Skill | Purpose | | -------------------- | ----------------------------------------------- | | /spec | Full spec lifecycle orchestrator | | /discover | Structured research before committing to a spec | | /chat | Exploratory conversation with context | | /start | Quick session resume (~15s) | | /prime | Full session boot with health checks | | /wrap | End-of-session cleanup and summary | | /retro | Extract prescriptive lessons from the session | | /audit | On-demand project health check | | /issue | Create and manage project issues | | /pr-cleanup | Post-merge branch and worktree cleanup | | /publish-templates | Promote a template into the plugin | | /migrate-skill | Port a user-level skill into the plugin |

Quality & Security Gates

SpecFlow's shipped templates, skills, and subagents come wired to the author's default gates — Codacy (security + code quality) via its official Gen-3 skills, and CodeRabbit for cross-model review:

• Templates — tasks-template closing gates run the codacy-analysis-cli and coderabbit:review plugin skills (a local Gen-3 codacy-analysis SAST/quality scan and an AI cross-model review); design-template and code-quality-reviewer-template include a Codacy SRM security pre-check and cross-reference.
• Skills — the shipped /audit and /prime skills query Codacy for live security and quality findings.
• Subagents — code-oracle uses Codacy for repository analysis.

These are defaults, not requirements. The MCP server itself bundles no scanner — every reference lives in the markdown you copy and control, and reaches Codacy or CodeRabbit only when you've installed the matching skill, CLI, or MCP server. To run a different toolchain (SonarQube, Semgrep, Snyk, GitHub Advanced Security, or a different reviewer), edit the corresponding template, skill, or subagent after installing it.

Knowledge Structure

Spec documents, steering docs, and templates are stored as structured markdown in an Obsidian-compatible layout. If you use Obsidian, you get graph visualization and wikilink navigation for free. If not, it's still just a folder of markdown files.

your-vault/specflow/
  templates/                  # global spec templates (auto-populated)
  {Project}/
    steering/                 # product.md, tech.md, structure.md
    specs/                    # requirements, design, tasks, logs
    approvals/

Each project needs a thin config file (.specflow/config.json) pointing to the vault:

{ "project": "MyProject", "docvault": "../my-vault" }

Multi-Agent Support

SpecFlow is an MCP server — any agent that speaks MCP can use it. Spec state lives on disk, so you can start a spec in one agent and continue in another.

| Agent | Status | Notes | | --------------- | -------- | ------------------------- | | Claude Code | Verified | Full MCP + skills support | | Gemini CLI | Verified | MCP tools, uses GEMINI.md | | Codex CLI | Verified | MCP tools, uses CODEX.md | | OpenCode | Verified | MCP tools |

Extending the Stack

SpecFlow handles the spec lifecycle — it doesn't try to be a memory system, code search engine, or knowledge base. Those are separate concerns best served by separate tools. The author's personal stack includes:

• SessionFlow — session history indexing and recall
• claude-context — semantic code search via Milvus (hardened fork of zilliztech/claude-context)
• mem0 — cross-session episodic memory
• Obsidian — knowledge base (DocVault)
• Code Graph Context — structural code analysis via Neo4j

None of these are required to use SpecFlow. The MCP server and dashboard work standalone with just Node.js.

Prerequisites

• Node.js (18+) — required
• An MCP-compatible agent — Claude Code, Gemini CLI, Codex CLI, or similar

Development

npm install
npm run build        # TypeScript + Vite dashboard
npm test             # vitest unit tests
npm run test:e2e     # Playwright E2E
npm run dev          # Development mode with hot reload

Credits

Pimzino/spec-workflow-mcp — the foundation. Pimzino designed and built the core: MCP server, sequential spec workflow, real-time dashboard with blocking approval gates, approval storage, Markdown parser, implementation logging, template engine, multi-language support, VSCode extension, Docker deployment, and security hardening.

zilliztech/claude-context — upstream for the semantic code search fork.

mwgreen/claude-code-session-rag — upstream for SessionFlow.

License

GPL-3.0 — same as upstream.