Spec-Flow - Structured Development Workflow

Structured workflow for complex feature development. Creates living documentation that guides implementation and serves as team reference.

⚠️ Interaction Rules (MUST Follow)

This skill uses a phase-by-phase confirmation workflow, ensuring users can review and adjust at each stage.

Language Rule

All generated documents (.md files) MUST be written in Chinese (中文), including:

• proposal.md, requirements.md, design.md, tasks.md
• Section headings, descriptions, requirements text, task descriptions
• Comments and notes within documents

Core Principles

1. One phase at a time: Only work on the current phase. NEVER generate documents for subsequent phases in advance.
2. Mandatory confirmation: After completing each phase, you MUST stop and wait for user confirmation.
3. User-driven progression: Only proceed to the next phase when user explicitly says "continue", "ok", "next", "looks good", "继续", "好", "下一步", etc.

Confirmation Template

After completing each phase, you MUST use this format to request confirmation:

📋 **[Phase Name] Complete**

Created `.spec-flow/active/<feature>/<file>.md` containing:
- [Key content summary]

**Please review**:
1. [Review question]?
2. [Review question]?

✅ Say "continue" to proceed to next phase
✏️ Tell me what to modify if needed

❌ Prohibited Behaviors

• Generating multiple phase documents after user describes a feature
• Automatically proceeding to next phase without user confirmation
• Creating both proposal.md and requirements.md in one response
• Assuming user wants to skip confirmation for speed

✅ Correct Flow Example

User: I want to implement user authentication
AI: [Creates only proposal.md] + confirmation prompt

User: continue
AI: [Creates only requirements.md] + confirmation prompt

User: looks good, next
AI: [Creates only design.md] + confirmation prompt

User: continue
AI: [Creates only tasks.md] + confirmation prompt

Fast Mode (Optional)

If user explicitly requests to skip phase-by-phase confirmation:

• "generate all documents at once"
• "fast mode"
• "skip confirmations"

Then you may generate all documents consecutively, but still request final overall confirmation.

Quick Start

1. Initialize spec directory: Run scripts/init-spec-flow.sh <feature-name> or manually create .spec-flow/active/<feature-name>/
2. Copy templates from this skill's templates/ directory
3. Follow four-phase workflow below
4. Archive completed specs to .spec-flow/archive/ when done

Four-Phase Workflow

Phase 1: Proposal

Goal: Define WHY this change is needed

Create .spec-flow/active/<feature>/proposal.md using templates/proposal.md.template:

• Background: Context and motivation for the change
• Goals: What we want to achieve (with checkboxes)
• Non-Goals: What we explicitly won't do (reduces scope creep)
• Scope: In-scope vs out-of-scope boundaries
• Risks: Potential issues and mitigations
• Open Questions: Items needing clarification before proceeding

Exit Criteria: Proposal reviewed, open questions resolved, scope agreed.

⏸️ Phase Checkpoint: After creating proposal.md, ask user:

• Is the background accurate?
• Are goals clear and measurable?
• Is the scope boundary reasonable?
• Is risk assessment complete?

→ Wait for user confirmation before proceeding to Requirements phase

Phase 2: Requirements

Goal: Define WHAT the system should do

Create .spec-flow/active/<feature>/requirements.md using templates/requirements.md.template:

Use EARS Format (see references/ears-format.md):

• Ubiquitous: "The system shall..."
• Event-Driven: "When [trigger], the system shall..."
• State-Driven: "While [state], the system shall..."
• Unwanted Behavior: "If [condition], then the system shall NOT..."

Include:

• Functional requirements (FR-001, FR-002, ...)
• Non-functional requirements: Performance, Security, Reliability (NFR-001, ...)
• Acceptance criteria (AC-001, AC-002, ...)

Exit Criteria: All requirements testable, acceptance criteria clear.

⏸️ Phase Checkpoint: After creating requirements.md, ask user:

• Do functional requirements cover all use cases?
• Are non-functional requirements (performance/security/reliability) sufficient?
• Are acceptance criteria testable?

→ Wait for user confirmation before proceeding to Design phase

Phase 3: Design

Goal: Define HOW to implement

Create .spec-flow/active/<feature>/design.md using templates/design.md.template:

• Architecture Overview: High-level component diagram (use Mermaid)
• Component Design: Responsibilities and interfaces for each component
• API Design: Endpoints, request/response schemas
• Data Model: Entity relationships (use Mermaid erDiagram)
• Error Handling: Error codes, descriptions, resolutions
• Migration Plan: Steps for data/schema migrations (if applicable)

Exit Criteria: Design addresses all requirements, trade-offs documented.

⏸️ Phase Checkpoint: After creating design.md, ask user:

• Does the architecture meet all requirements?
• Is the API design clear?
• Are there any missing edge cases?

→ Wait for user confirmation before proceeding to Tasks phase

Phase 4: Tasks

Goal: Break down into EXECUTABLE steps

Create .spec-flow/active/<feature>/tasks.md using templates/tasks.md.template:

Task Guidelines (see references/task-decomposition.md):

• Each task completable in 1-2 tool calls
• Include complexity estimate: Low/Medium/High
• List affected files
• Define dependencies between tasks
• Group into phases: Setup → Implementation → Testing → Documentation

Progress Tracking:

• ⏳ Pending → 🔄 In Progress → ✅ Done
• ❌ Blocked (add notes explaining blocker)

Exit Criteria: All tasks completed, tests passing, documentation updated.

⏸️ Phase Checkpoint: After creating tasks.md, ask user:

• Is the task granularity appropriate?
• Are dependencies correct?
• Ready to start implementation?

→ Wait for user confirmation before starting implementation

⚠️ Phase 5: Implementation

Goal: Execute tasks according to tasks.md

🎛️ Execution Modes

Implementation supports three execution modes. Default is Step Mode unless user specifies otherwise.

Mode	Trigger Phrases	Behavior
Step Mode (Default)	"start implementation", "开始执行"	Execute ONE task, wait for confirmation, repeat
Batch Mode	"execute all", "一口气执行", "全部执行", "batch mode"	Execute ALL tasks consecutively, report at end
Phase Mode	"execute phase 1", "执行第一阶段", "execute setup"	Execute all tasks in ONE phase, then wait

📋 Step Mode (Default)

Execute tasks one at a time with user confirmation between each.

When to use: Complex tasks, need careful review, first time using spec-flow

Flow:

User: start implementation

AI: 🔄 **Task T-001**: [description]
    [Executes task]
    ✅ Completed (1/10)
    👉 Say "continue" for next task

User: continue

AI: 🔄 **Task T-002**: [description]
    ...

⚡ Batch Mode

Execute all remaining tasks consecutively without waiting.

When to use: Simple tasks, trusted plan, want speed

Trigger phrases:

• "execute all tasks" / "全部执行"
• "batch mode" / "批量执行"
• "一口气执行完"
• "run all remaining tasks"

Flow:

User: execute all tasks

AI: ⚡ **Batch Mode Activated**

    🔄 T-001: [description] → ✅
    🔄 T-002: [description] → ✅
    🔄 T-003: [description] → ✅
    ...

    📊 **Batch Complete**: 10/10 tasks done

    **Summary**:
    - Files created: [list]
    - Files modified: [list]

    ⚠️ Stopped early? Check error above.

Batch Mode Rules:

1. Still update tasks.md after each task
2. Stop immediately if any task fails or has error
3. Provide summary at the end
4. User can interrupt with "stop" or "暂停"

📦 Phase Mode

Execute all tasks within a specific phase, then wait for confirmation.

When to use: Want to review after each phase (Setup → Core → Testing → Docs)

Trigger phrases:

• "execute phase 1" / "执行第一阶段"
• "execute setup phase" / "执行 Setup"
• "run all setup tasks"

Flow:

User: execute setup phase

AI: 📦 **Phase Mode: Setup**

    🔄 T-001: [description] → ✅
    🔄 T-002: [description] → ✅

    ✅ **Setup Phase Complete** (2/10 total)

    **Next phase**: Core Implementation (T-010 to T-015)
    👉 Say "continue" or "execute next phase"

🚨 BEFORE Starting Any Task (All Modes)

You MUST do these steps before executing:

1. Read tasks.md - Get current task list and statuses
2. Identify target tasks - Based on mode (one task / all tasks / phase tasks)
3. Check dependencies - Ensure dependency tasks are completed (- [x])
4. Read design.md - Review relevant design sections

✅ REQUIRED Behaviors (All Modes)

Action	Step Mode	Batch Mode	Phase Mode
Read tasks.md before starting	✅	✅	✅
Check dependencies	✅	✅	✅
Update - [ ] to - [x] after each task	✅	✅	✅
Show progress	After each	After each	After each
Wait for confirmation	After each task	After all done	After phase done
Stop on error	✅	✅	✅

❌ PROHIBITED Behaviors (All Modes)

Prohibited Action	Why It's Wrong
Skip a task	Breaks dependency chain
Execute tasks out of order	Dependencies may not be met
Do work not in tasks.md	Scope creep, untracked changes
Forget to update tasks.md	Progress tracking inaccurate
Continue after error without user approval	May cause cascading failures

🛑 When to STOP (All Modes)

Stop and ask user for guidance when:

• A task fails or produces errors
• Design is incomplete for current task
• A dependency is missing or blocked
• Task description is ambiguous
• Need a decision not covered in design.md

Directory Structure

project-root/
└── .spec-flow/
    ├── steering/           # Global project context (optional)
    │   ├── constitution.md # Project governance principles
    │   ├── product.md      # Product vision and goals
    │   ├── tech.md         # Technology constraints
    │   └── structure.md    # Code organization patterns
    ├── active/             # Work in progress
    │   └── <feature-name>/
    │       ├── proposal.md
    │       ├── requirements.md
    │       ├── design.md
    │       ├── tasks.md
    │       └── .meta.json  # Status, timestamps, owner
    └── archive/            # Completed features (for reference)
        └── <feature-name>/
            └── ...

Steering Documents (Optional)

For larger projects, create .spec-flow/steering/ documents to provide consistent context across all specs:

Document	Purpose	Template
constitution.md	Project governance, decision-making principles	templates/steering/constitution.md.template
product.md	Product vision, target users, key metrics	templates/steering/product.md.template
tech.md	Tech stack, constraints, dependencies	templates/steering/tech.md.template
structure.md	Code organization, naming conventions	templates/steering/structure.md.template

Workflow Tips

Phase Transitions

From	To	Condition
Proposal	Requirements	Proposal approved, questions resolved
Requirements	Design	Requirements complete, testable
Requirements	Tasks	Simple feature, design implicit
Design	Tasks	Design approved
Tasks	Done	All tasks complete, archived

When to Skip Phases

• Skip Design: For simple features where architecture is obvious
• Never Skip: Proposal and Tasks (always clarify intent and break down work)

Best Practices

1. Keep specs updated: Update status as work progresses
2. Link to code: Reference commits, PRs, file paths in tasks
3. Archive completed specs: Move to .spec-flow/archive/ when done
4. Review steering docs: Reference them when writing new specs
5. Validate completeness: Run scripts/validate-spec-flow.py before implementation

References

• Complete workflow guide: See references/workflow.md
• EARS requirement format: See references/ears-format.md
• Task decomposition patterns: See references/task-decomposition.md
• Real-world examples: See references/examples/

Compatibility

This skill works with any AI agent that supports the Skills format:

• Claude Code (~/.claude/skills/)
• Blade (~/.blade/skills/)
• Other compatible agents

The .spec-flow/ directory is Git-friendly and can be committed with your project for team collaboration.