Spec Flow

Spec-driven development workflow. Interactive phase-by-phase confirmation from proposal to implementation. Trigger: 'spec-flow', 'spec mode', 'need a plan',...

Security Scan

The skill's code and runtime instructions align with its stated purpose (a spec-driven, phase-by-phase workflow); no disproportionate credentials, downloads, or surprising network behavior were found, but one included script's contents were not provided so full review is recommended before use.

Purpose & Capability

Name/description (Spec Flow, phase-by-phase spec authoring + implementation) matches the included files: SKILL.md, templates, references, and helper scripts for initializing and managing .spec-flow. There are no requested credentials, binaries, or config paths that are unrelated to authoring specs and managing the .spec-flow directory.

Instruction Scope

SKILL.md confines operations to the .spec-flow/ directory and mandates user confirmation at each phase. The runtime instructions explicitly read and write local files (proposal.md, requirements.md, design.md, tasks.md) and reference included reference docs. This is appropriate for the stated purpose, but the workflow includes an Implementation phase where the agent (when instructed by the user) may execute tasks; you should be aware that executing tasks could involve running tool calls or edits in your project repository when you tell the agent to do so (the skill enforces confirmation points and has a --fast option to bypass them only if explicitly requested).

Install Mechanism

No install spec (instruction-only) and included helper scripts are local shell/Python files. Nothing is pulled from external URLs or installed automatically. This is low-risk from an install/download perspective.

Credentials

The skill declares no required environment variables, credentials, or config paths. Some documentation (CONTRIBUTING.md) mentions an example env var (SPEC_FLOW_TEMPLATES) but neither SKILL.md nor the visible scripts require it; if you rely on environment-driven template overrides, inspect the code to confirm behavior. Overall, requested environment access is proportionate to the task.

Persistence & Privilege

The skill does not request always:true and does not attempt to modify other skills or global agent config in the reviewed files. It will create and modify a .spec-flow/ directory in the current project — that is expected and appropriate for its function.

Assessment

This skill appears coherent for creating and managing specification documents and guiding implementation in a repo. Before installing and running: 1) Review the full contents of scripts/validate-spec-flow.py (not shown here) to ensure it doesn't call external endpoints or read unexpected files; 2) Be mindful that the Implementation phase implies the agent may execute tasks in your project — only allow 'execute all' or batch modes when you trust the generated tasks and the agent's behavior; 3) The skill will create and write files under .spec-flow/ in whatever workspace you run it in—run it from the intended repository; 4) If you keep sensitive data in your repo, verify the scripts do not upload or leak files (no evidence was found in the visible scripts); 5) If you want tighter control, prefer Step mode (default) so the agent stops for your confirmation between tasks.

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.