# spec-flow

Adopt this skill: https://proskills.md/skills/other/echovic-spec-flow

Page: https://proskills.md/skills/other/echovic-spec-flow
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 5755
upstream: https://github.com/echovic/spec-flow/blob/HEAD/SKILL.md

````text
---
name: spec-flow
description: "Spec-driven development workflow. Interactive phase-by-phase confirmation from proposal to implementation. Trigger: 'spec-flow', 'spec mode', 'need a plan', 'structured development', 'write a spec', 'feature spec', 'technical spec', '需求文档', '技术方案', '任务拆解', '规格驱动', '写个方案', '做个规划', '结构化开发', 'plan this feature', 'break this down', 'design doc'. Creates .spec-flow/ directory with proposal, requirements, design, and tasks."
argument-hint: "[feature description] [--fast] [--skip-design]"
---

# Spec-Flow - Structured Development Workflow

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

## Core Principles

1. **One phase at a time** — NEVER generate documents for subsequent phases in advance
2. **Mandatory confirmation** — After each phase, STOP and wait for user confirmation
3. **User-driven progression** — Only proceed when user says "continue"/"ok"/"next"/"继续"/"好"

## Parameters

| 参数 | 说明 |
|------|------|
| `--fast` | 跳过逐阶段确认，一次性生成所有文档（最后整体确认） |
| `--skip-design` | 跳过 Design 阶段（简单功能，架构显而易见时） |

## Language Rule

**所有生成的 .md 文件必须使用中文。**

## Interaction Rules

Load `references/interaction-rules.md` for detailed confirmation templates and prohibited behaviors.

---

## Five-Phase Workflow

Copy this checklist and check off items as you complete them:

### Spec-Flow Progress:

- [ ] **Phase 0: Initialize** ⚠️ REQUIRED
  - [ ] 0.1 Run `scripts/init-spec-flow.sh <feature-name>` or create `.spec-flow/active/<feature>/`
  - [ ] 0.2 Check if `.spec-flow/steering/` exists — if so, read for project context
  - [ ] 0.3 问自己：**这个功能的核心价值是什么？用一句话能说清吗？**

- [ ] **Phase 1: Proposal** ⚠️ REQUIRED
  - [ ] 1.1 Create `.spec-flow/active/<feature>/proposal.md` using `templates/proposal.md.template`
  - [ ] 1.2 包含：Background, Goals, Non-Goals, Scope, Risks, Open Questions
  - [ ] 1.3 问自己：**有没有隐含的需求没写出来？**
  - [ ] 1.4 问自己：**Non-Goals 是否足够明确？能防止 scope creep 吗？**
  - [ ] 1.5 ⏸️ 确认节点 — 等待用户确认后继续

- [ ] **Phase 2: Requirements**
  - [ ] 2.1 Create `.spec-flow/active/<feature>/requirements.md` using `templates/requirements.md.template`
  - [ ] 2.2 Load `references/ears-format.md` — 使用 EARS 格式编写需求
  - [ ] 2.3 包含：FR-xxx 功能需求, NFR-xxx 非功能需求, AC-xxx 验收标准
  - [ ] 2.4 问自己：**每条需求都是可测试的吗？**
  - [ ] 2.5 问自己：**边界情况覆盖了吗？错误场景呢？**
  - [ ] 2.6 ⏸️ 确认节点 — 等待用户确认后继续

- [ ] **Phase 3: Design**（除非 `--skip-design`）
  - [ ] 3.1 Create `.spec-flow/active/<feature>/design.md` using `templates/design.md.template`
  - [ ] 3.2 包含：Architecture (Mermaid), Components, API, Data Model, Error Handling
  - [ ] 3.3 问自己：**这个设计能满足所有 requirements 吗？逐条对照**
  - [ ] 3.4 问自己：**有没有更简单的方案？过度设计了吗？**
  - [ ] 3.5 ⏸️ 确认节点 — 等待用户确认后继续

- [ ] **Phase 4: Tasks**
  - [ ] 4.1 Create `.spec-flow/active/<feature>/tasks.md` using `templates/tasks.md.template`
  - [ ] 4.2 Load `references/task-decomposition.md` — 遵循任务拆解规范
  - [ ] 4.3 每个任务：1-2 tool calls 可完成，标注复杂度 Low/Medium/High
  - [ ] 4.4 分组：Setup → Implementation → Testing → Documentation
  - [ ] 4.5 问自己：**任务之间的依赖关系对吗？有没有可以并行的？**
  - [ ] 4.6 ⏸️ 确认节点 — 等待用户确认后继续

- [ ] **Phase 5: Implementation**
  - [ ] 5.1 Load `references/execution-modes.md` — 确认执行模式
  - [ ] 5.2 默认 Step Mode（逐任务确认），用户可切换 Batch/Phase Mode
  - [ ] 5.3 每个任务执行前：读 tasks.md → 检查依赖 → 读 design.md
  - [ ] 5.4 每个任务执行后：更新 tasks.md 状态（`- [ ]` → `- [x]`）
  - [ ] 5.5 全部完成后：归档到 `.spec-flow/archive/`

---

## Directory Structure

```
.spec-flow/
├── steering/           # 全局项目上下文（可选）
│   ├── constitution.md
│   ├── product.md
│   ├── tech.md
│   └── structure.md
├── active/             # 进行中
│   └── <feature>/
│       ├── proposal.md
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── archive/            # 已完成
```

## Steering Documents (Optional)

| Document | Purpose | Template |
|----------|---------|----------|
| `constitution.md` | 项目治理原则 | `templates/steering/constitution.md.template` |
| `product.md` | 产品愿景、目标用户 | `templates/steering/product.md.template` |
| `tech.md` | 技术栈、约束 | `templates/steering/tech.md.template` |
| `structure.md` | 代码组织、命名规范 | `templates/steering/structure.md.template` |

## Phase Transitions

| From | To | Condition |
|------|-----|-----------|
| Proposal | Requirements | Proposal approved, questions resolved |
| Requirements | Design | Requirements complete, testable |
| Requirements | Tasks | `--skip-design`, simple feature |
| Design | Tasks | Design approved |
| Tasks | Implementation | Tasks confirmed |
| Implementation | Done | All tasks complete → archive |

## Compatibility

Works with any AI agent that supports Skills format: Claude Code, Blade, OpenClaw, Cursor, Windsurf, etc.
````

## File: README.md
upstream: https://github.com/echovic/spec-flow/blob/HEAD/README.md

````text
# Spec-Flow

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
# 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
````
