Spec-Flow

Spec-driven development workflow for AI coding agents

Spec-Flow transforms complex feature development into a guided, phase-by-phase workflow with living documentation. Works with any AI agent that supports the Skills format.

Features

• Phase-by-Phase Workflow: Proposal → Requirements → Design → Tasks → Implementation
• Interactive Confirmation: Each phase waits for your approval before proceeding
• Living Documentation: Creates .spec-flow/ directory with Markdown docs that guide implementation
• EARS Requirements: Industry-standard Easy Approach to Requirements Syntax
• 3 Execution Modes: Step (default), Batch, Phase — choose your speed
• Team Collaboration: Git-friendly, commit specs with your project

Installation

# Claude Code
cd ~/.claude/skills && git clone https://github.com/echoVic/spec-flow.git

# OpenClaw
cd ~/.openclaw/workspace/skills && git clone https://github.com/echoVic/spec-flow.git

# Blade
cd ~/.blade/skills && git clone https://github.com/echoVic/spec-flow.git

# Or any agent's skills directory

Quick Start

Trigger with: spec-flow, spec mode, need a plan, structured development, 写个方案, 做个规划

User: spec-flow — add user authentication

AI: [Creates proposal.md] → waits for confirmation
User: continue
AI: [Creates requirements.md] → waits for confirmation
User: continue
AI: [Creates design.md] → waits for confirmation
User: continue
AI: [Creates tasks.md] → waits for confirmation
User: execute all tasks
AI: [Implements everything]

Parameters: --fast (skip confirmations), --skip-design (simple features)

Five-Phase Workflow

┌──────────┐    ┌──────────────┐    ┌────────┐    ┌───────┐    ┌────────────────┐
│ Proposal │ → │ Requirements │ → │ Design │ → │ Tasks │ → │ Implementation │
└──────────┘    └──────────────┘    └────────┘    └───────┘    └────────────────┘
    WHY              WHAT              HOW        EXECUTE         BUILD

| Phase | Goal | Output | |-------|------|--------| | Proposal | Define WHY | Background, goals, non-goals, risks | | Requirements | Define WHAT | FR/NFR in EARS format, acceptance criteria | | Design | Define HOW | Architecture, API, data model (Mermaid) | | Tasks | Break down | Granular tasks with dependencies | | Implementation | Build | Code, tests, documentation |

Execution Modes

| Mode | Trigger | Behavior | |------|---------|----------| | Step (default) | "start implementation" | One task → confirm → next | | Batch | "execute all" / "全部执行" | All tasks consecutively | | Phase | "execute setup phase" | All tasks in one phase → confirm |

Directory Structure

.spec-flow/
├── steering/           # Optional: global project context
│   ├── constitution.md
│   ├── product.md
│   ├── tech.md
│   └── structure.md
├── active/             # Work in progress
│   └── <feature>/
│       ├── proposal.md
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── archive/            # Completed features

File Structure

spec-flow/
├── SKILL.md                              # Checklist workflow
├── references/
│   ├── ears-format.md                    # EARS requirement syntax
│   ├── task-decomposition.md             # Task breakdown patterns
│   ├── workflow.md                       # Detailed workflow guide
│   ├── interaction-rules.md              # Confirmation rules
│   ├── execution-modes.md               # Step/Batch/Phase modes
│   └── examples/
├── templates/                            # Document templates
│   ├── proposal.md.template
│   ├── requirements.md.template
│   ├── design.md.template
│   ├── tasks.md.template
│   └── steering/
└── scripts/
    ├── init-spec-flow.sh                 # Initialize spec directory
    ├── validate-spec-flow.py             # Validate completeness
    └── execute-task.sh                   # Execute a task

Language

• Workflow instructions: English
• Generated documents: Chinese (中文) by default

License

MIT