@gordon.gan/specflow 1.0.1 → 1.1.0

package/README.md

@@ -4,345 +4,274 @@
 [![npm downloads](https://img.shields.io/npm/dm/@gordon.gan/specflow.svg)](https://www.npmjs.com/package/@gordon.gan/specflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**一句话：plan 想清楚，refine 打磨透，build 做到位，done 归档好。**
+**规范驱动开发，从想清楚到归档上线，一条流水线走完。**
 
-> Cursor 用户可直接参考：`CURSOR_PACKAGING_AND_USAGE_GUIDE.md`  
-> Codex 用户可直接参考：`CODEX_PACKAGING_AND_USAGE_GUIDE.md`
+SpecFlow 把 **OpenSpec**（结构化需求规划）和 **Superpowers**（TDD、调试、代码审查等工程纪律）合并为一个工具：一个 CLI 负责确定性操作，一套跨 IDE 工作流技能负责 AI 编排，覆盖从探索需求到归档合并的完整生命周期。
 
-SpecFlow 把两个开源框架合并成一个工具：
-- **OpenSpec** — 结构化需求规划（proposal → specs → design → tasks）
-- **Superpowers** — 工程执行纪律（TDD、系统化调试、代码审查、subagent 编排）
-
-一个 CLI + 一套跨 IDE 工作流技能（Claude Code / Cursor / Codex），覆盖从「扫描代码库」到「归档上线」的完整开发生命周期。
+| 环境 | 命令形式 | 详细指南 |
+|------|----------|----------|
+| Claude Code | `/specflow:propose` 等斜杠命令 | 本文 |
+| Cursor | `specflow:propose` 等命令 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
+| OpenAI Codex | `$specflow-propose` 等技能 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
 
 ---
 
-## 前置依赖
-
-- **Node.js ≥ 20.19.0**（`node --version` 检查）
-- **Git**（用于 build 的 worktree 和 done 的分支管理）
-- **AI 编码环境（任选其一或组合）**
-  - **Claude Code** — `/specflow:*` 斜杠命令
-  - **Cursor** — `specflow:*` 命令（见 Cursor 指南）
-  - **OpenAI Codex** — `$specflow-*` 技能（见 Codex 指南）
+## 这是什么
 
----
+用 AI 写代码时，常见两类问题：
 
-## 安装
+1. **想不清楚就开始写** — 需求模糊、方案没比过、边界没定，返工多
+2. **写完了对不上规格** — 没有可验收的 spec、变更难追溯、棕地项目更难接手
 
-### 方式 1：从 npm 全局安装（推荐）
+SpecFlow 的解法是把开发拆成**有门禁的阶段**，每个阶段产出可审查的 artifact（文档 + 规格），CLI 负责合并与校验，AI 技能负责按流程执行。
 
-```bash
-npm install -g @gordon.gan/specflow
+```
+explore（可选）→ propose → refine → apply → review → test → verify → archive
 ```
 
-### 方式 2：从 GitHub 直接安装（发布前/最新代码）
+棕地项目（已有代码库）不需要单独的「扫描」命令：用 **explore** 读代码定边界，或在 **propose** 的 Q&A 里描述现有行为 + 本次变更，由 delta spec 建立基线。
 
-```bash
-npm install -g github:Gordon-Gan-Jiang/specflow
-```
+---
 
-### 方式 3：本地源码安装（开发者 / 贡献者）
+## 核心能力
 
-```bash
-git clone https://github.com/Gordon-Gan-Jiang/specflow.git
-cd specflow
-npm install
-npm run build
-npm link
-```
+| 能力 | 说明 |
+|------|------|
+| **结构化规划** | 一次 propose 产出 proposal、delta specs、design、tasks 四个 artifact |
+| **多轮精化** | refine 内部循环（≥2 轮），攻击性审查假设、边界与 scope |
+| **纪律化构建** | apply 先重写 tasks.md，再逐任务 TDD；design 有漏则回 refine |
+| **双重验收** | verify 对照 delta specs 与主 specs 做回归检查 |
+| **变更归档** | archive 自动 merge delta、移入 archive、可做 git 分支清理 |
+| **跨 IDE 一致** | Claude / Cursor / Codex 共享同一套技能与 prompt，parity 可校验 |
+| **确定性 CLI** | 校验、合并、状态追踪、资产同步 — 不依赖 AI 猜 |
 
-使用 `npm link` 后，在源码里改代码 → 重新 `npm run build` → 全局的 `specflow` 命令立即生效（符号链接）。
+---
 
-### 方式 4：通过本地 tarball 分发
+## 工作流程
+
+### 阶段总览
 
-在有源码的机器上打包：
-```bash
-npm run build
-npm pack          # 生成 gordon.gan-specflow-1.0.1.tgz
 ```
-在目标机器上安装：
-```bash
-npm install -g ./gordon.gan-specflow-1.0.1.tgz
+┌─────────────────────────────────────────────────────────────────────────┐
+│  explore [可选]   需求模糊时：读代码、比方案、定边界 → explore.md        │
+│       ↓  handoff：explore.md Status 必须为 confirmed                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│  propose          产出 proposal + delta specs + design + tasks          │
+│       ↓                                                                 │
+│  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
+│       ↓                                                                 │
+│  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
+│       ↓                                                                 │
+│  review → test → verify                                                 │
+│       ↓                                                                 │
+│  archive          delta merge 入主 specs，变更移入 archive/              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+快捷通道：
+  fix   — 修 Bug：调试 → TDD 修复 → 审查 → 测试 → 归档
+  snap  — 事后补档：从 git diff 反推变更记录并归档
 ```
 
-### 验证安装
+### 变更生命周期（phase）
 
-```bash
-specflow --version   # 应输出 1.0.1
-specflow --help
-```
+每个 change 在 `.specflow.yaml` 中追踪 `phase`：
 
-### 卸载
+| phase | 含义 | 典型触发 |
+|-------|------|----------|
+| `propose` | 规划阶段（explore / propose） | `specflow change new` 默认值 |
+| `refined` | refine 收敛完成 | refine 结束后 |
+| `apply` | 代码已实现 | apply Phase B 完成后 |
+| `archived` | 已归档 | archive 完成后 |
 
-```bash
-npm uninstall -g @gordon.gan/specflow
-# 如果用的是 npm link（本地源码安装）：
-npm unlink -g specflow
-```
+`specflow change archive` **默认要求** `phase=apply`；可用 `--force` 跳过。老版本 change 若仍写 `plan` / `built`，CLI 读取时会自动映射为 `propose` / `apply`。
+
+### explore 门禁
+
+- `explore.md` 中 `**Status**: draft` → propose **被阻止**，需先确认方向
+- `**Status**: confirmed` → propose 读取已确认结论并合成 artifact
+- apply / refine 卡住时，可对**子问题**再次 explore（mid-change re-explore）
 
 ---
 
-## 在项目中使用
+## 快速开始
+
+### 前置依赖
 
-### 初始化（每个项目一次）
+- Node.js **≥ 20.19.0**
+- Git（worktree 与归档分支管理）
+- 任选 AI 编码环境：Claude Code / Cursor / Codex
+
+### 安装
 
 ```bash
-cd your-project
-specflow init              # 默认：Claude + Cursor（--ide both）
-specflow init --ide codex  # 仅 Codex
-specflow init --ide all    # Claude + Cursor + Codex
-```
+# 推荐：npm 全局安装
+npm install -g @gordon.gan/specflow
 
-这一步会：
-- 创建 `specflow/` 目录（存放 specs 和 changes）
-- 写入 `specflow/config.yaml`（项目上下文）
-- 按 `--ide` 生成对应托管资产：
-  - **Claude**：`.claude/skills/`、`.claude/commands/specflow/`、`.claude/specflow/`
-  - **Cursor**：`.cursor/skills/`、`.cursor/commands/specflow/`、`.cursor/rules/`、`.cursor/specflow/`
-  - **Codex**：`.agents/skills/`、`.agents/specflow/`、`AGENTS.md` 上下文块
-- **自动追加** `.gitignore`，忽略可再生的 prompts/schemas/templates（幂等，不覆盖已有内容）
+# 或从 GitHub 安装最新代码
+npm install -g github:Gordon-Gan-Jiang/specflow
 
-init 后：
-- Claude Code：斜杠命令 `/specflow:*` 立即可用
-- Cursor：命令 `specflow:*` 立即可用
-- Codex：技能 `$specflow-*` 立即可用
+# 验证
+specflow --version   # 当前 1.1.0
+specflow --help
+```
 
-### 重新初始化
+开发者本地调试：
 
 ```bash
-# 删掉后重新跑 init
-rm -rf specflow/config.yaml .claude/specflow/
-specflow init
+git clone https://github.com/Gordon-Gan-Jiang/specflow.git
+cd specflow && npm install && npm run build && npm link
 ```
 
-（init 检测到已初始化会拒绝运行，避免误覆盖）
+### 在项目中初始化
 
----
+```bash
+cd your-project
+specflow init              # 默认：Claude + Cursor
+specflow init --ide codex  # 仅 Codex
+specflow init --ide all    # Claude + Cursor + Codex
+```
 
-## 核心流程
+init 会创建 `specflow/` 目录、写入 `config.yaml`，并按 `--ide` 生成对应托管资产（skills、commands、prompts 等），同时幂等地追加 `.gitignore` 忽略可再生的 prompts/schemas/templates。
 
-**每阶段深度思考 → 多轮迭代精化**：每个阶段一次性产出实质内容（非占位骨架），再通过内部多轮迭代把 artifact 精化到稳态，最后进入执行。
+### 跑通第一个变更
+
+**需求已清晰：**
 
 ```
-/specflow:scan    [规划中 · v0.3] 扫描已有代码生成 specs 基线；当前请直接用 /specflow:propose 描述已有行为
-       ↓
-/specflow:explore [可选] 需求模糊时：读代码、比方案、定边界 → 产出 explore.md
-       ↓
-/specflow:propose    一次产出 4 个 artifact：proposal + delta specs + design + tasks（first-iteration 深度思考，非纯骨架）
-       ↓
-/specflow:refine  内部多轮精化循环（≥2 rounds，AI 收敛判定，不设上限）
-                   每轮攻击性审查 + 4 个挑战行为：
-                     · 挑战假设   · 提新 options
-                     · 探边界     · 质疑 scope
-                   可更新任意 artifact（proposal / specs / design / tasks）
-       ↓
-/specflow:apply   Phase A：基于 refine 稳定后的 artifact，用 writing-plans 严格精化（rewrite）tasks.md
-                   Phase B：逐任务 TDD 执行（subagent 模式）
-                   design 有漏即停，回 refine 补齐
-       ↓
-/specflow:review  代码审查（对照 specs 检查回归）
-       ↓
-/specflow:test    全量测试（单元 + 集成 + E2E + 回归）
-       ↓
-/specflow:verify  双重校验（delta specs 验收 + 主 specs 回归）
-       ↓
-/specflow:archive    归档变更 → specs 合并 → git 分支清理
-                   默认要求 phase=built，可用 --force 跳过
+/specflow:propose "给用户管理模块加批量导入"
+/specflow:refine
+/specflow:apply
+/specflow:verify
+/specflow:archive
 ```
 
-另外两个快捷命令：
+**需求模糊：**
+
 ```
-/specflow:fix     修 Bug 一条龙（调试 → TDD 修复 → 自动归档）
-/specflow:snap    事后补档（从 git diff 反推变更记录）
+/specflow:explore "不确定用 CSV 还是 Excel，也不清楚现有用户表结构"
+# 确认 explore.md 后：
+/specflow:propose
+/specflow:refine
+...
 ```
 
-### 新机制（v0.2.0）
-
-- **plan 一次产出 4 artifact**：proposal、delta specs、design、tasks 同步生成，每个都是实质的"第一轮深度思考"（first-iteration），不再是占位骨架
-- **refine 内部多轮循环**：至少 2 轮，AI 语义判断收敛，不设上限；每轮显式执行 4 个挑战行为（挑战假设 / 提新 options / 探边界 / 质疑 scope）；可更新任意 artifact
-- **build Phase A 改为 rewrite**：不再是"生成" tasks.md，而是基于 refine 稳定后的 artifact 用 Superpowers writing-plans 严格规则"精化"重写；发现 design 缺漏即停并回 refine
-- **`.specflow.yaml` 新增 `phase` 字段**：追踪变更生命周期（`plan` / `refined` / `built` / `archived`）；`specflow change archive` 默认要求 `phase=built`，可用 `--force` 跳过守门
+（Cursor 用 `specflow:propose`；Codex 用 `$specflow-propose`，其余类推。）
 
 ---
 
-## 快速上手示例
+## 典型场景
 
-### 5 分钟跑通全流程
+### 新项目（greenfield）
 
-```bash
-# 1. 安装（任选一种）
-npm install -g @gordon.gan/specflow
+需求清晰时直接从 propose 开始；每个阶段产出实质内容，refine 多轮打磨后再 apply。
 
-# 2. 进入你的项目
-cd my-project
+### 棕地项目（brownfield）
 
-# 3. 初始化
+```bash
 specflow init
-
-# 4. 打开 Claude Code，在会话里输入（二选一）：
-
-# 需求已清晰 — 直接 plan：
-/specflow:propose "给用户管理模块加个批量导入功能"
-
-# 需求模糊 — 先 explore 再 propose：
-/specflow:explore "批量导入时不确定该用 CSV 还是 Excel，也不清楚现有用户表结构"
-# 确认 explore.md 后：
-/specflow:propose
-```
-
-Claude Code 接下来会：
-1. 读 `.claude/skills/specflow-propose/SKILL.md` 编排器
-2. 问你几个澄清问题（一次一个）
-3. 生成 `specflow/changes/bulk-import/proposal.md`
-4. 展示 proposal 等你**确认**
-5. 确认后生成 delta specs `specs/*/spec.md`
-6. 提示你下一步是 `/specflow:refine`
-
-### 更完整的示例（4 个场景）
-
-#### 场景 1：新项目从零开始（需求已清晰）
-
-```
-/specflow:propose "添加用户注册和登录功能"
-/specflow:refine           # 讨论技术方案，输出 design.md
-/specflow:apply            # TDD 实现，每任务用户确认
-/specflow:review           # 代码审查
-/specflow:test             # 跑测试
-/specflow:verify           # 对照 specs 验收
-/specflow:archive             # 归档 + merge
 ```
 
-#### 场景 1b：需求模糊，先探索再规划
-
 ```
-/specflow:explore "登录有时返回 500，不确定是 token 校验还是 session 存储的问题"
-# AI 读代码、比方案、产出 explore.md；你确认方向后：
-/specflow:propose             # 读取 explore.md，合成 proposal + specs + design + tasks
+/specflow:explore "描述模糊问题或不确定的改法"    # 可选
+/specflow:propose "描述已有行为 + 本次要改什么"
 /specflow:refine
 /specflow:apply
 /specflow:archive
 ```
 
-#### 场景 2：接手已有项目（v0.2.x 工作流）
-
-```bash
-cd legacy-project
-specflow init
-
-# 在 Claude Code 里：
-# 注意：/specflow:scan 当前规划在 v0.3，未实现。
-# v0.2.x 的推荐做法是：需求模糊时先 /specflow:explore；或需求清晰时直接进 plan，
-# 在 proposal Q&A 里描述已有行为 + 新增变更，让 propose 为将要改动的 capability 生成 delta spec 基线。
-/specflow:explore "描述模糊问题或不确定的改法"   # 可选
-/specflow:propose "描述已有行为 + 你这次要改的新功能"
-/specflow:refine             # 对 propose 产出做 ≥2 轮攻击性审查
-/specflow:apply              # Phase A 重写 tasks.md → Phase B TDD
-/specflow:archive               # 归档，delta spec 合入主 specs/
-```
+在 propose 阶段通过 delta spec 为将要改动的 capability 建立基线，无需单独扫描命令。
 
-#### 场景 3：紧急修 Bug
+### 紧急修 Bug
 
 ```
-/specflow:fix "登录接口在 token 过期时返回 500 而不是 401"
+/specflow:fix "登录接口 token 过期时返回 500 而不是 401"
 ```
 
-一条命令包含：
-1. 自动创建轻量变更
-2. 定位相关 specs（对照规格理解预期行为）
-3. 系统化调试（4 步法：调查 → 模式 → 假设 → 验证）
-4. TDD 修复（先写复现测试让它红，再修代码让它绿）
-5. 自动代码审查
-6. 跑测试
-7. 归档
-
-紧急模式跳过审查：
-```
-/specflow:fix --urgent "生产环境崩溃"
-```
+包含：创建轻量变更 → 对照 specs 调试 → TDD 修复 → 审查 → 测试 → 归档。加 `--urgent` 可跳过审查。
 
-#### 场景 4：同事改了代码没走流程，事后补档
+### 同事没走流程，事后补档
 
 ```
 /specflow:snap "重构了认证模块"
 ```
 
-分析 git diff + git log，反推完整变更记录，推断受影响的 specs，用户确认后自动归档。
+分析 git diff + log，反推变更记录，用户确认后归档。
 
 ---
 
-## 命令速查
+## IDE 工作流命令
+
+共 **10 个**技能，命名因 IDE 而异：
+
+| 阶段 | Claude Code | Cursor | Codex |
+|------|-------------|--------|-------|
+| 探索（可选） | `/specflow:explore` | `specflow:explore` | `$specflow-explore` |
+| 规划 | `/specflow:propose` | `specflow:propose` | `$specflow-propose` |
+| 精化 | `/specflow:refine` | `specflow:refine` | `$specflow-refine` |
+| 构建 | `/specflow:apply` | `specflow:apply` | `$specflow-apply` |
+| 审查 | `/specflow:review` | `specflow:review` | `$specflow-review` |
+| 测试 | `/specflow:test` | `specflow:test` | `$specflow-test` |
+| 验收 | `/specflow:verify` | `specflow:verify` | `$specflow-verify` |
+| 归档 | `/specflow:archive` | `specflow:archive` | `$specflow-archive` |
+| 修 Bug | `/specflow:fix` | `specflow:fix` | `$specflow-fix` |
+| 补档 | `/specflow:snap` | `specflow:snap` | `$specflow-snap` |
+
+### 各命令职责
+
+| 命令 | 做什么 |
+|------|--------|
+| **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
+| **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架） |
+| **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
+| **apply** | Phase A 用 writing-plans 规则重写 tasks.md；Phase B subagent TDD 逐任务执行 |
+| **review** | 代码审查，对照 specs 检查回归 |
+| **test** | 单元 + 集成 + E2E + 回归测试 |
+| **verify** | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped） |
+| **archive** | 归档变更、delta merge、git 分支清理；默认要求 phase=apply |
+| **fix** | 修 Bug 一条龙 |
+| **snap** | 从 git 历史反推变更并归档 |
+
+> **v1.0.1 起命令已重命名**（对齐 OpenSpec 术语）：`plan→propose`、`build→apply`、`done→archive`。`.specflow.yaml` 的 phase 枚举同步为 `propose/refined/apply/archived`（读取时兼容旧值 `plan`/`built`）。
 
-### Claude Code 技能命令（在 Claude Code 会话里用）
-
-| 命令 | 说明 |
-|---|---|
-| `/specflow:scan` | **[规划中 · v0.3]** 扫描已有代码库生成 specs 基线；v0.2.x 未实现，触发时 skill 会提示替代方案 |
-| `/specflow:explore` | **需求模糊时** 先探索：读代码、比方案、定边界，产出 `explore.md`，再 handoff 到 propose |
-| `/specflow:propose` | 需求规划：生成 proposal + delta specs |
-| `/specflow:refine` | 技术方案探讨（brainstorming + design.md） |
-| `/specflow:apply` | 两阶段构建：生成计划 → subagent TDD 执行 |
-| `/specflow:review` | 代码审查（含 specs 回归检查） |
-| `/specflow:test` | 全量测试 + 验证（单元/集成/E2E/回归） |
-| `/specflow:verify` | 双重校验：delta specs 验收 + 主 specs 回归 |
-| `/specflow:archive` | 归档变更 + specs 合并 + git 分支清理 |
-| `/specflow:fix` | 修 Bug 快速通道（调试 → TDD → 归档） |
-| `/specflow:snap` | 事后补档（从 git diff 反推变更记录） |
-
-### CLI 命令（在终端里用）
+---
 
-| 命令 | 说明 |
-|---|---|
-| `specflow init` | 初始化项目（生成目录、技能、prompts） |
-| `specflow change new <名称>` | 创建新的变更 |
-| `specflow change status <名称>` | 查看变更的 artifact 完成状态 |
-| `specflow change archive <名称>` | 归档变更（delta merge + 移入 archive） |
-| `specflow validate <文件>` | 校验 spec 文件格式 |
-| `specflow instructions <artifact> <change>` | 查看某个 artifact 的创建指令 |
+## CLI 命令
 
-CLI 命令会从当前目录**向上查找**项目根（找 `specflow/config.yaml`），类似 `git` 的行为。在项目任意子目录下运行都能工作。
+CLI 从当前目录**向上查找**项目根（识别 `specflow/config.yaml`），类似 `git` 行为。
 
----
+### 项目初始化
 
-## 架构
+| 命令 | 说明 |
+|------|------|
+| `specflow init [--ide claude\|cursor\|codex\|both\|all]` | 初始化项目目录与 IDE 托管资产 |
+| `specflow sync [--ide ...] [--no-parity-strict]` | 从已安装的 specflow 包同步/更新 IDE 资产（升级后用） |
+| `specflow doctor [--parity] [--json]` | 诊断 IDE 资产是否完整、迁移状态是否正常 |
+| `specflow parity-report [--json]` | 对比 Claude / Cursor / Codex 能力是否一致 |
 
-SpecFlow 分三层，各司其职：
+### 变更管理
 
-```
-┌─────────────────────────────────────────────────┐
-│  CLI 层（确定性逻辑）                              │
-│  TypeScript 实现。负责文件操作、specs 校验、        │
-│  artifact 状态追踪、delta merge、归档。            │
-│  不涉及任何 AI 逻辑。                             │
-├─────────────────────────────────────────────────┤
-│  SKILL.md 层（编排层）                             │
-│  每个命令一个 SKILL.md（50-100 行）。              │
-│  定义工作流阶段、hard gate 门禁、用户确认点。       │
-│  通过 Read 指令按需加载 prompt 文件。              │
-├─────────────────────────────────────────────────┤
-│  Prompts 层（执行指令）                            │
-│  详细的指令文件，告诉 Claude Code 在每个阶段        │
-│  具体怎么做：写 proposal、做 brainstorming、       │
-│  执行 TDD、做 code review 等。                    │
-│  按需加载，不会一次全部塞进 context。               │
-└─────────────────────────────────────────────────┘
-```
+| 命令 | 说明 |
+|------|------|
+| `specflow change new <名称>` | 创建新变更（`.specflow.yaml` 默认 `phase: propose`） |
+| `specflow change status <名称>` | 查看 artifact 完成状态 |
+| `specflow change phase <名称>` | 查看当前 phase |
+| `specflow change phase <名称> --set <phase>` | 设置 phase（`propose \| refined \| apply \| archived`） |
+| `specflow change archive <名称> [--force]` | 归档变更；`--force` 跳过 phase=apply 门禁 |
 
-**为什么这样设计？**
+### 规格与指令
 
-- **渐进加载**：一个 SKILL.md 如果把所有 prompt 内嵌进去会超过 1000 行，Claude Code 容易"迷路"。拆成小文件按阶段加载，每个阶段的指令清晰聚焦。
-- **Hard Gate 双重保障**：关键门禁（如"设计未确认不许写代码"）在 SKILL.md 编排层和 prompt 文件两处都声明，防止执行漂移。
-- **CLI 处理确定性操作**：delta specs 合并、格式校验等需要精确文本操作的工作由 TypeScript 代码执行，不靠 AI 猜。
+| 命令 | 说明 |
+|------|------|
+| `specflow validate <文件>` | 校验 spec 文件格式（WHEN/THEN scenario 等） |
+| `specflow instructions <artifact> <change>` | 查看某 artifact 的创建指令 |
 
 ---
 
 ## 关键概念
 
-### Specs（规格文件）
-
-存放在 `specflow/specs/` 目录，是项目的 **Source of Truth（唯一事实来源）**。
+### Specs — 唯一事实来源
 
-每个 spec 文件描述一个功能模块的行为规格：
+存放在 `specflow/specs/`，描述各 capability 的行为规格：
 
 ```markdown
 ### Requirement: 用户登录
@@ -351,114 +280,143 @@ SpecFlow 分三层，各司其职：
 #### Scenario: 登录成功
 - **WHEN** 用户提交有效凭据
 - **THEN** 系统返回认证 token
-
-#### Scenario: 登录失败
-- **WHEN** 用户提交错误密码
-- **THEN** 系统返回 401 错误
 ```
 
-### Changes（变更记录）
-
-存放在 `specflow/changes/` 目录。每次新功能或修复都是一个 change。
+### Changes — 一次功能或修复
 
-一个 change 包含：
-- `proposal.md` — 为什么做、做什么
-- `specs/` — delta specs（ADDED/MODIFIED/REMOVED/RENAMED 的需求变更）
-- `design.md` — 技术方案
-- `tasks.md` — 实施任务清单（带 checkbox）
+存放在 `specflow/changes/<name>/`：
 
-归档时，delta specs 会自动合并到主 specs，change 移入 `specflow/changes/archive/`。
+| 文件 | 作用 |
+|------|------|
+| `explore.md` | 可选；探索结论，Status 控制 propose 门禁 |
+| `proposal.md` | 为什么做、做什么 |
+| `specs/` | delta specs（对主 specs 的增量变更） |
+| `design.md` | 技术方案 |
+| `tasks.md` | 实施任务清单（带 checkbox） |
+| `.specflow.yaml` | 变更元数据（含 phase） |
 
-### Delta Specs（增量规格）
+归档后 delta 自动 merge 进 `specflow/specs/`，change 移入 `specflow/changes/archive/`。
 
-描述对现有 specs 的变更，支持四种操作：
+### Delta Specs — 四种操作
 
 ```markdown
-## ADDED Requirements
-（新增的需求）
-
-## MODIFIED Requirements
-（修改的需求 — 必须包含完整更新内容）
-
-## REMOVED Requirements
-（删除的需求 — 必须说明原因和迁移方案）
-
-## RENAMED Requirements
-（重命名 — FROM: 旧名 / TO: 新名）
+## ADDED Requirements      # 新增
+## MODIFIED Requirements   # 修改（须写完整更新内容）
+## REMOVED Requirements    # 删除（须说明原因与迁移）
+## RENAMED Requirements    # 重命名（FROM / TO）
 ```
 
 ---
 
-## 项目产生的目录结构
+## 目录结构
 
-`specflow init` 后，你的项目会新增：
+`specflow init` 后项目新增（按 `--ide` 不同，IDE 目录有所差异）：
 
 ```
 your-project/
-├── specflow/              # 需求管理（应该跟踪到 git）
-│   ├── config.yaml         # 项目上下文配置
-│   ├── specs/              # 主 specs（Source of Truth）
-│   ├── changes/            # 活跃的变更
-│   │   └── <name>/         # 每个变更的 artifact
-│   │       ├── proposal.md
-│   │       ├── specs/
-│   │       ├── design.md
-│   │       └── tasks.md
-│   └── changes/archive/    # 归档的变更
+├── specflow/                    # 规格与变更（应纳入 git）
+│   ├── config.yaml
+│   ├── specs/                   # 主 specs（Source of Truth）
+│   └── changes/
+│       ├── <name>/              # 活跃变更
+│       │   ├── explore.md       # 可选
+│       │   ├── proposal.md
+│       │   ├── specs/
+│       │   ├── design.md
+│       │   ├── tasks.md
+│       │   └── .specflow.yaml
+│       └── archive/             # 已归档变更
 │
-└── .claude/
-    ├── skills/specflow-*/ # 10 个技能（应该跟踪）
-    ├── commands/specflow/ # 10 个命令别名（应该跟踪）
-    └── specflow/          # 资源文件（.gitignore 自动忽略）
-        ├── prompts/
-        ├── schemas/
-        └── templates/
+├── .claude/                     # Claude Code（--ide 含 claude 时）
+│   ├── skills/specflow-*/
+│   ├── commands/specflow/
+│   └── specflow/                # prompts/schemas/templates（可再生，gitignore）
+│
+├── .cursor/                     # Cursor（--ide 含 cursor 时）
+│   ├── skills/specflow-*/
+│   ├── commands/specflow/
+│   └── specflow/
+│
+└── .agents/                     # Codex（--ide 含 codex 时）
+    ├── skills/specflow-*/
+    └── specflow/
 ```
 
-建议的 git 策略：
-- **跟踪**：`specflow/`、`.claude/skills/`、`.claude/commands/specflow/`（团队共享的规格和技能）
-- **忽略**：`.claude/specflow/{prompts,schemas,templates}/`（`specflow init` 自动忽略，因为这些可由升级 specflow 重新生成）
+**Git 建议：**
+
+- **跟踪**：`specflow/`、各 IDE 的 `skills/` 与 `commands/specflow/`
+- **忽略**：各 IDE 下可再生的 `specflow/{prompts,schemas,templates}/`（init 自动追加）
 
 ---
 
-## 故障排查
+## 架构
+
+三层分离，各司其职：
+
+```
+┌──────────────────────────────────────────────┐
+│  CLI 层（TypeScript，确定性）                  │
+│  文件操作、校验、delta merge、归档、资产同步    │
+├──────────────────────────────────────────────┤
+│  SKILL.md 层（编排）                          │
+│  阶段划分、hard gate、用户确认点、按需加载 prompt │
+├──────────────────────────────────────────────┤
+│  Prompts 层（执行指令）                       │
+│  各阶段具体操作：写 proposal、TDD、审查等       │
+└──────────────────────────────────────────────┘
+```
 
-### `specflow: command not found`
+- **渐进加载**：SKILL.md 保持精简，prompt 按阶段 Read，避免 context 膨胀
+- **Hard Gate 双重声明**：编排层与 prompt 层同时约束关键门禁
+- **CLI 不做 AI 逻辑**：文本合并与格式校验由代码精确执行
 
-- 确认 `npm install -g @gordon.gan/specflow` 成功
-- 检查 `npm config get prefix` 下的 `bin` 目录是否在 PATH 里
+---
 
-### `No specflow project found at or above <dir>`
+## 维护与升级
 
-CLI 找不到项目根。确保：
-- 你在一个跑过 `specflow init` 的项目目录里（或其子目录）
-- `specflow/config.yaml` 存在
+升级全局 specflow 后，在项目里同步资产：
 
-### `错误: Change "xxx" already exists`
+```bash
+specflow sync --ide all
+```
+
+检查资产健康与跨 IDE 一致性：
 
-变更名冲突。要么用不同名字，要么先归档已有的。
+```bash
+specflow doctor --parity
+specflow parity-report
+```
 
-### Node 版本不兼容
+重新初始化（init 检测到已初始化会拒绝，需先删除 `specflow/config.yaml` 等标记文件）：
 
-SpecFlow 需要 Node ≥ 20.19.0。用 `nvm` 切版本：
 ```bash
-nvm install 20
-nvm use 20
-npm install -g @gordon.gan/specflow
+rm -rf specflow/config.yaml .claude/specflow/   # 按需清理其他 IDE 目录
+specflow init
 ```
 
-### code-review-graph 安装失败
+---
 
-`/specflow:scan` 规划在 v0.3 实现时会用到 code-review-graph（当前在 optionalDependencies 里占位）。这个依赖是从 GitHub 安装的，如果网络问题导致失败，**不影响任何 v0.2.x 功能**——scan 本身在 v0.2.x 不可用，其余所有命令与此依赖无关。
+## 故障排查
+
+| 现象 | 处理 |
+|------|------|
+| `specflow: command not found` | 确认 `npm install -g` 成功；检查 `npm config get prefix`/bin 是否在 PATH |
+| `No specflow project found` | 确认已 `specflow init` 且 `specflow/config.yaml` 存在 |
+| `Change "xxx" already exists` | 换名称或先归档已有变更 |
+| propose 被 explore 阻止 | 将 `explore.md` 的 `**Status**` 改为 `confirmed` |
+| archive 拒绝（phase 不对） | 完成 apply 使 phase=apply，或 `specflow change archive --force` |
+| Node 版本不兼容 | 需要 ≥ 20.19.0：`nvm install 20 && nvm use 20` |
+| parity-report FAIL | 运行 `specflow sync --ide all` 后重试 `specflow doctor --parity` |
 
 ---
 
 ## 来源与许可
 
-SpecFlow 基于两个开源项目构建（均为 MIT 许可）：
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — artifact graph、delta merge、validation 等核心运行时
-- [Superpowers](https://github.com/obra/superpowers) — brainstorming、TDD、debugging、code review 等 prompt
+基于两个开源项目（均为 MIT）：
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — artifact graph、delta merge、validation
+- [Superpowers](https://github.com/obra/superpowers) — brainstorming、TDD、debugging、code review
 
-所有来源内容已按 SpecFlow 风格改写，通过 `<!-- SOURCE: ... -->` 注释标注出处。
+来源内容已按 SpecFlow 风格改写，通过 `<!-- SOURCE: ... -->` 标注出处。
 
 **许可证：MIT**