@gavin-hjw/sddflow 0.3.2 → 0.3.4

package/templates/close.md

@@ -1,91 +1,252 @@
 ---
 name: sddflow/close
-description: Verify implementation consistency and archive
+description: Verify implementation with Superpowers + OpenSpec, archive change, then finish development branch
 ---
 
-# Close: 验证归档
+# Close: 验证 + 归档 + 收尾
 
 ## 目标
 
-验证代码实现与设计文档一致，确认规格变更全部体现，然后归档。
+按顺序执行五个阶段，确保实现正确性、规格一致性，完成 OpenSpec 归档，最后处理开发分支。**每个阶段必须通过才能进入下一阶段。**
 
 ## 中断续接规则
 
-如果用户在 close 阶段被打断后继续回复、说“继续”、或要求完成归档，保持 close 阶段并继续验证/归档。close 阶段不允许顺手修代码；发现差异只记录到 `close-issues.md`。
+- 被打断后继续回复 → 保持 close 阶段，从中断的步骤恢复
+- close 阶段不允许修改代码；发现问题记录后切到 `/sddflow amend` 或 `/sddflow build` 修复，修复完再回到 close
 
 ## 前置条件
 
-- `docs/superpowers/plans/` 下的实现计划全部 checkbox 已勾选
-- `openspec/changes/<变更名>/plan-ready.md` 存在
+- `docs/superpowers/plans/` 下对应 plan 文件的所有 checkbox 已勾选
+- `openspec/changes/<变更名>/tasks.md` 所有条目为 `[x]`
 
-## 流程
+有未完成 task 时终止：
+> "还有 N 个任务未完成。请先用 `/sddflow build` 完成实现后再归档。"
 
-### 1. 确认实现状态
+---
+
+## 阶段 1：实现验证（Superpowers verification-before-completion）
+
+> **使用 Superpowers `verification-before-completion` skill**
+
+**不允许跳过，不允许用"应该通过"代替实际运行。**
+
+### 1.1 测试套件验证
+
+运行项目完整测试命令（以实际技术栈为准）：
+
+```bash
+# 根据项目选择对应命令
+npm test / pytest / cargo test / go test ./... / ...
+```
+
+**必须看到实际输出，确认：**
+- 所有测试通过（0 failures）
+- 无警告或错误输出
+
+**测试失败时终止：**
+> "测试未通过（N failures）。请先用 `/sddflow build` 修复失败测试，再执行 close。"
+
+### 1.2 构建验证（如适用）
+
+```bash
+npm run build / cargo build --release / ...
+```
+
+确认 exit code 为 0。
+
+### 1.3 需求清单验证
 
-检查 `docs/superpowers/plans/` 下对应的计划文件，确认所有 checkbox 已勾选。
+重新读取 `plan-ready.md` 和 `openspec/changes/<变更名>/tasks.md`，逐条对照代码确认：
 
-如果有未完成的 task：
-> "还有 N 个任务未完成。请先用 /sddflow build 完成实现。"
+| 验证项 | 要求 |
+|--------|------|
+| 每条 task | 对应实现文件存在 |
+| 每条 task | 对应测试文件存在且通过 |
+| 所有 checkbox | 均为 `[x]` |
 
-### 2. 验证设计一致性
+**有任何项目无法用实际证据（文件路径、测试输出）确认时，记录到 `close-issues.md` 并终止：**
+> "验证失败：以下需求无实现证据 — [列表]。请先修复再执行 close。"
 
-读取 `openspec/changes/<变更名>/design.md`，逐项检查代码实现：
+---
+
+## 阶段 2：代码审查（Superpowers requesting-code-review，可选）
+
+> **使用 Superpowers `requesting-code-review` skill**
 
-- design.md 中的技术决策是否在代码中体现？
-- 标记的架构选择是否与代码结构一致？
+询问用户是否执行代码审查：
 
-对每一项，给出判定：✅ 一致 / ❌ 不一致（附具体差异）
+> "是否在归档前执行最终代码审查？（推荐在合并到主分支前执行）"
 
-### 3. 验证规格完整性
+**用户选择执行时：**
 
-读取 `openspec/changes/<变更名>/specs/` 目录，检查每个规格变更：
+1. 获取 git SHAs：
+   ```bash
+   BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD main)
+   HEAD_SHA=$(git rev-parse HEAD)
+   ```
 
-- 标记为"新增"的功能是否已实现？
-- 标记为"修改"的行为是否已更新？
-- 标记为"删除"的旧逻辑是否已移除？
+2. 派发 code reviewer 子代理，提供：
+   - 变更描述（来自 proposal.md 摘要）
+   - 需求文档（plan-ready.md 路径）
+   - BASE_SHA 和 HEAD_SHA
 
-对每一项，给出判定：✅ 已体现 / ❌ 未体现（附具体缺失）
+3. 处理 reviewer 反馈：
 
-### 4. 处理不一致
+| 等级 | 处理方式 |
+|------|----------|
+| Critical | 终止 close，切到 `/sddflow build` 修复后重新 close |
+| Important | 终止 close，切到 `/sddflow build` 修复后重新 close |
+| Minor | 记录到 `close-issues.md`，可选修复，不阻塞继续 |
 
-如果发现不一致：
-- **不在 close 阶段改代码**
-- 将不一致项记录到 `openspec/changes/<变更名>/close-issues.md`
-- 提示用户：
-  > "发现 N 处不一致，已记录到 close-issues.md。是否需要开启新的变更来修复？"
+**用户选择跳过时：** 记录"用户跳过代码审查"，继续阶段 3。
+
+---
 
-### 5. 归档
+## 阶段 3：规格一致性验证
 
-全部一致（或用户接受不一致项）后，先校验变更：
+> 本项目无 `/opsx:verify` 命令；按下列步骤手工验证，并配合 OpenSpec CLI。
+
+### 3.1 CLI 校验（如可用）
 
 ```bash
 openspec validate <变更名> --strict
 ```
 
-校验通过后执行归档：
+校验失败 → 修正规格或实现后重新 close。
+
+### 3.2 三维度对照（记录到 `openspec/changes/<变更名>/close-issues.md`）
+
+| 维度 | 检查内容 |
+|------|----------|
+| **Completeness** | `tasks.md` checkbox 全部 `[x]`；plan 文件 checkbox 全部 `[x]`；所有规格需求有实现证据 |
+| **Correctness** | 实现与 `specs/**/spec.md` 中 Requirement、Scenario 一致 |
+| **Coherence** | 若存在 `design.md`：代码遵循其决策；若无 `design.md`：代码与 `proposal.md` / `specs/**` 一致，且符合项目既有模式 |
+
+### 3.3 处理结果
+
+| 等级 | 处理方式 |
+|------|----------|
+| CRITICAL | 终止 close；写入 `close-issues.md`；提示 `/sddflow amend` + `/sddflow build` 后重新 close |
+| WARNING | 展示给用户，询问是否修复；用户确认后可继续归档 |
+| SUGGESTION | 记录到 `close-issues.md`，不阻塞归档 |
+
+**存在 CRITICAL 时输出：**
+> "规格验证失败，存在 N 个 CRITICAL 问题（见 close-issues.md）。请用 `/sddflow amend` 修订需求或用 `/sddflow build` 补充实现后再执行 close。"
+
+---
+
+## 阶段 4：归档（OpenSpec: Archive + openspec/specs 同步）
+
+> **优先使用 Cursor/Claude 命令 `OpenSpec: Archive`，或 OpenSpec CLI `openspec archive`**
+
+### 4.1 前置确认
+
+阶段 3 通过（无 CRITICAL）后，向用户确认：
+
+> "验证通过。准备归档变更 `<变更名>`。此操作将：
+> 1. 将 delta specs 同步合并到 `openspec/specs/`（除非明确为纯工具变更）
+> 2. 将 `openspec/changes/<变更名>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<变更名>/`
+>
+> 确认归档？"
+
+### 4.2 执行归档
+
+**方式 A — 编辑器命令（推荐）：** 调用 `OpenSpec: Archive`，按提示选择变更 ID。
+
+**方式 B — CLI：**
 
 ```bash
 openspec archive <变更名> --yes
 ```
 
-如果 OpenSpec CLI 不可用，手动归档：
+归档流程应完成：
+
+1. 检查所有 artifact 与 `tasks.md` 完成状态
+2. 评估 delta specs 与 `openspec/specs/` 的差异
+3. 同步 delta specs 到 `openspec/specs/<capability>/spec.md`（推荐；纯工具变更可用 `--skip-specs`）
+4. 将变更目录移入 `openspec/changes/archive/`
+
+归档后运行（如 CLI 可用）：
+
+```bash
+openspec validate --strict
+```
+
+### 4.3 确认归档结果
+
+归档完成后确认：
+- `openspec/changes/archive/YYYY-MM-DD-<变更名>/` 目录存在
+- `openspec/specs/` 相关能力的规格已更新（如有 delta specs）
+- `openspec/changes/<变更名>/` 已不在 active changes 列表
+
+---
+
+## 阶段 5：收尾开发分支（Superpowers finishing-a-development-branch）
+
+> **如果使用了 git worktree 或 feature branch，则执行本阶段**
+> **使用 Superpowers `finishing-a-development-branch` skill**
+
+**声明：** 输出：
+> "正在使用 finishing-a-development-branch skill 收尾开发分支。"
+
+### 5.1 检测是否需要执行
+
+检查当前工作区：
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+- 普通仓库且在主分支上 → 跳过本阶段，直接到完成提示
+- 在 feature branch 或 worktree 上 → 执行本阶段
+
+### 5.2 再次验证测试（finishing-a-development-branch 要求）
 
 ```bash
-mkdir -p openspec/changes/archive
-mv openspec/changes/<变更名> openspec/changes/archive/$(date +%Y-%m-%d)-<变更名>/
+# 运行完整测试套件
+<项目测试命令>
 ```
 
-归档后确认：
-- 规格增量已合并到主规格库（如适用）
-- 变更记录已移到 archive 目录
+测试失败时 finishing-a-development-branch 会拒绝继续，需先修复。
+
+### 5.3 呈现选项
 
-### 6. 完成提示
+按 `finishing-a-development-branch` skill 流程，呈现：
 
-> "变更 '<变更名>' 已验证并归档。可以开始下一个变更了。"
+```
+1. 合并到 <base-branch>（本地 merge）
+2. 推送并创建 Pull Request
+3. 保留分支现状（稍后处理）
+4. 丢弃此分支
+```
+
+### 5.4 执行选择并清理 worktree
+
+按用户选择执行，worktree 清理规则：
+- 选项 1（merge）或 选项 4（discard）→ 清理 worktree
+- 选项 2（PR）或 选项 3（keep）→ 保留 worktree
+
+---
+
+## 完成提示
+
+> "变更 `<变更名>` 已完成全部关闭流程：
+>
+> ✅ 阶段 1：实现验证通过（测试全绿）
+> ✅ 阶段 2：代码审查完成（或已跳过）
+> ✅ 阶段 3：OpenSpec 验证通过
+> ✅ 阶段 4：已归档至 openspec/changes/archive/YYYY-MM-DD-<变更名>/
+> ✅ 阶段 5：开发分支已处理（或不适用）
+>
+> 可以开始下一个变更了。"
+
+---
 
 ## 关键原则
 
-- close 阶段不做代码修改，只做验证和归档
-- 本阶段只允许写归档、验证记录或 `close-issues.md`；禁止修改任何代码或实现文件
-- 不一致先记录，不现场修复
-- 防止边写代码边改需求的恶性循环
+- close 阶段**不修改任何代码或实现文件**，只做验证、记录、归档
+- 验证必须有实际命令输出作为证据，不允许用"应该通过"代替运行
+- CRITICAL 问题必须修复后才能归档，WARNING 可询问用户决定
+- finishing-a-development-branch 放在最后，确保归档完成后再处理分支
+- 不一致项优先记录到 `close-issues.md`，不在 close 阶段现场修代码

package/templates/spec.md

@@ -1,68 +1,124 @@
 ---
 name: sddflow/spec
-description: Call OpenSpec to generate specs, auto-translate to plan-ready.md after user confirmation
+description: Complete OpenSpec change artifacts per AGENTS.md and OpenSpec Proposal, then translate to plan-ready.md and writing-plans
 ---
 
-# Spec: 生成规格并翻译
+# Spec: 生成规格 + 实现计划
 
 ## 目标
 
-调用 OpenSpec 生成完整的规格文档（proposal.md, design.md, specs/, tasks.md），用户确认后自动翻译成 Superpowers 可执行的 plan-ready.md。
+1. **按 OpenSpec 官方流程**补齐 `specs/`、`tasks.md`；`design.md` **按需**创建（`proposal.md` 通常已由前一阶段提供）
+2. 翻译为工程视角的 `plan-ready.md`（sddflow 翻译层，不改变 OpenSpec 制品格式）
+3. 调用 Superpowers `writing-plans` skill 生成可执行的详细实现计划（`docs/superpowers/plans/YYYY-MM-DD-<变更名>.md`）
+
+**spec 阶段产出全部文档后，build 阶段直接进入执行，不再生成计划。**
 
 ## 中断续接规则
 
-如果用户在本阶段被打断后继续回复、补充范围、要求调整规格、或确认规格摘要，仍然停留在 spec 阶段。只更新 `openspec/changes/**` 与 `plan-ready.md`，不要修改任何代码或实现文件。
+如果用户在本阶段被打断后继续回复、补充范围、要求调整规格、或确认规格摘要，仍然停留在 spec 阶段。只更新 `openspec/changes/**`、`plan-ready.md` 和 plan 文件，不要修改任何代码或实现文件。
 
 ## 前置条件
 
-- `openspec/changes/` 下存在活跃变更目录（由 proposal 或 brainstorming 阶段创建）
+- `openspec/changes/` 下存在活跃变更目录（由 brainstorming 阶段创建）
 - 变更目录下至少有 `proposal.md`
 
-## 流程
+---
 
-### 1. 确认活跃变更
+## 步骤 1：确认活跃变更
 
 检查 `openspec/changes/` 下是否有活跃变更（非 archive 子目录）。
 
-如果没有，提示用户：
-> "还没有活跃变更。请先用 /sddflow proposal 或 /sddflow brainstorming 创建需求。"
+没有时提示：
+> "还没有活跃变更。请先用 /sddflow brainstorming 创建需求。"
 
-如果有多个，列出并让用户选择：
+多个时列出并让用户选择：
 > "检测到多个活跃变更：[列表]。要对哪个生成规格？"
 
-### 2. 生成 OpenSpec 规格文件
+---
+
+## 步骤 2：生成 OpenSpec 规格制品（specs/ + tasks.md；design.md 按需）
+
+<HARD-GATE>
+本步骤**必须**完全遵循 OpenSpec 官方规范，**禁止**使用 sddflow 自订格式、自订章节结构或替代生成流程。
+</HARD-GATE>
+
+### 2.1 必读与唯一规范来源
+
+执行前**完整阅读**并严格遵守（冲突时以 OpenSpec 为准）：
+
+1. `openspec/AGENTS.md` — Stage 1、Creating Change Proposals、Spec File Format、Delta Operations、Troubleshooting
+2. 项目内 **`OpenSpec: Proposal`** 命令（如 `.claude/commands/openspec/proposal.md`）中 `<!-- OPENSPEC:START -->` … `<!-- OPENSPEC:END -->` 的 **Guardrails** 与 **Steps**
 
-根据 proposal.md 的内容生成或补齐以下文件：
+**声明（必须输出）：**
+> "正在按 OpenSpec 官方流程补齐 specs/ 与 tasks.md（design.md 按需；遵循 openspec/AGENTS.md 与 OpenSpec: Proposal）。"
 
-- `openspec/changes/<变更名>/proposal.md` — 已存在，可补充
-- `openspec/changes/<变更名>/design.md` — 技术方案
-- `openspec/changes/<变更名>/specs/` — 具体规格变更（标记新增/修改/删除）
-- `openspec/changes/<变更名>/tasks.md` — 实现任务清单
+### 2.2 执行方式
 
-如果 OpenSpec CLI 可用，生成后运行校验：
+在已确认 `<变更名>` 且 `openspec/changes/<变更名>/proposal.md` 已存在的前提下，**逐条执行 OpenSpec: Proposal 的步骤 1–7**（与 AGENTS.md Stage 1 一致）：
+
+1. 调研上下文：`openspec/project.md`、`openspec list`、`openspec list --specs`，必要时 `rg` / `openspec show` / 阅读相关代码
+2. 确认 `change-id` 为 `<变更名>`；**不要**用 sddflow 模板替换已有 `proposal.md`，仅在 OpenSpec 规范要求或与用户确认后，将内容对齐为 AGENTS.md 的 `## Why` / `## What Changes` / `## Impact` 结构
+3. 将变更映射到 capability，按 OpenSpec: Proposal 步骤 3 拆分多能力 delta
+4. 按 AGENTS.md **Creating Change Proposals** 第 5 节判定是否创建 `design.md`；不需要则**不得**添加空 `design.md`
+5. 在 `openspec/changes/<变更名>/specs/<capability>/spec.md` 撰写 delta（`## ADDED|MODIFIED|REMOVED|RENAMED Requirements`；每条 requirement 至少一个 `#### Scenario:`；`MODIFIED` 须粘贴 `openspec/specs/` 中完整 requirement 后再改）
+6. 按 OpenSpec: Proposal 步骤 6 撰写 `tasks.md`（有序、可勾选、含验证项）；生成后须符合「三文档 Checkbox 对齐扩展」中 **tasks.md** 条款
+7. 运行严格校验（见 2.3）
+
+**禁止：**
+
+- 自订 spec 模板、自订 requirement/scenario 写法（一律以 AGENTS.md 为准）
+- 凭经验生成 delta 而未对照 `openspec/specs/` 与 AGENTS.md
+- 跳过 `openspec validate` 或忽略校验错误
+
+### 2.3 校验
 
 ```bash
 openspec validate <变更名> --strict
 ```
 
-如果校验失败，根据错误修正上述文件后重新校验。
+校验失败时：使用 `openspec show <变更名> --json --deltas-only` 排查，按 AGENTS.md **Troubleshooting** 修正后重新校验，直至通过。
 
-### 3. 与用户确认规格
+---
+
+## 步骤 3：与用户确认规格
 
 展示规格摘要，逐项确认：
 
 > "以下是规格摘要：
 > - **提案**：[proposal.md 核心内容]
-> - **设计**：[design.md 核心决策]
+> - **设计**：[若存在 design.md → 核心决策；否则 → 无 design.md（OpenSpec 判定无需技术设计文档）]
+> - **规格**：[specs/ 变更列表]
 > - **任务**：[tasks.md 任务列表]
 >
 > 有需要调整的地方吗？"
 
-用户确认后才进入翻译步骤。
+用户确认后才进入步骤 4。
+
+---
+
+## 三文档 Checkbox 对齐扩展（通用）
+
+以下扩展**不改变**各文档的原有生成逻辑，仅在生成结果上**追加/保留** Markdown checkbox（`- [ ]` / `- [x]`），用于判断「是否已实现」并在 `/sddflow build` 时三向同步。`[ ]` = 未完成，`[x]` = 已完成。
+
+| 文档 | 原有生成逻辑（不得替换） | sddflow 追加：必须有 checkbox |
+|------|------------------------|------------------------------|
+| **tasks.md** | OpenSpec: Proposal 步骤 6 + AGENTS.md 任务清单结构 | 每条**可交付/可验收**的实现项必须以 `- [ ]` 或 `- [x]` 开头；保留 OpenSpec 章节与编号（如 `## 1. Implementation`、`- [ ] 1.1 ...`），**禁止**改成无 checkbox 的纯列表或段落 |
+| **plan-ready.md** | 步骤 4 翻译层（目标 / 改动文件 / 验证方式） | 每个 `### Task N:` 块内**首行**必须为 `- [ ] **任务完成**`（build 完成该 Task 后改为 `[x]`）；不得删除翻译正文，仅追加该行 |
+| **superpowers plan** | Superpowers `writing-plans`（Header、Task、Step、TDD 步骤） | 保留 writing-plans 规定的**每个 Step** `- [ ]`；在每个 `### Task N` 块**末尾**（最后一个 Step 之后）追加 `- [ ] **Task complete**`（该 Task 全部 Step 已为 `[x]` 后方可勾选，并与 plan-ready、tasks 同步） |
+
+**对齐规则：**
+
+- `Task N` 序号在三份文档间一一对应（从 1 递增）
+- 判断「整个 Task 是否完成」：三份文档中该 Task 的**任务级** checkbox 均为 `[x]`，且 superpowers plan 该 Task 下**所有 Step** checkbox 均为 `[x]`
+- 判断「变更是否全部完成」：三份文档中**全部**任务级 checkbox 与 superpowers plan **全部** Step checkbox 均为 `[x]`（供 `/sddflow close` 前置检查）
+
+步骤 2、4、5 完成后须自检上表；缺 checkbox 或 Task 序号不一致 → 修正后再进入下一步。
+
+---
 
-### 4. 自动生成 plan-ready.md（翻译层）
+## 步骤 4：生成 plan-ready.md（翻译层）
 
-用户确认后，自动将 OpenSpec 四文件翻译为 Superpowers 可执行的格式。
+将 OpenSpec 制品翻译为工程视角的执行格式（**并满足上文「三文档 Checkbox 对齐扩展」中 plan-ready.md 条款**）。
 
 **翻译规则：**
 1. 每个 OpenSpec Task 拆成 2-5 个细粒度步骤（对应 2-5 分钟工作量）
@@ -71,26 +127,21 @@ openspec validate <变更名> --strict
 4. **按执行依赖排序，不是按功能模块排序**
 5. 记录来源路径，方便回溯
 
-读取以下文件作为翻译输入：
-- `openspec/changes/<变更名>/proposal.md`
-- `openspec/changes/<变更名>/design.md`
-- `openspec/changes/<变更名>/specs/` 目录下所有文件
-- `openspec/changes/<变更名>/tasks.md`
-
-生成 `openspec/changes/<变更名>/plan-ready.md`，格式如下：
+**输出路径：** `openspec/changes/<变更名>/plan-ready.md`
 
 ```markdown
 # 实现计划：<变更名>
 
 ## 来源
 - 提案：openspec/changes/<变更名>/proposal.md
-- 设计：openspec/changes/<变更名>/design.md
+- 设计：<若存在 design.md 则写路径；否则写「无（OpenSpec 判定无需）」>
 - 规格：openspec/changes/<变更名>/specs/
 - 任务：openspec/changes/<变更名>/tasks.md
 
 ## 实现步骤
 
 ### Task 1: <任务名>
+- [ ] **任务完成**（与 superpowers plan `Task 1`、`tasks.md` 对应条目同步勾选）
 - 目标：<做什么>
 - 改动文件：<哪些文件>
 - 验证方式：<怎么验证>
@@ -98,14 +149,119 @@ openspec validate <变更名> --strict
 ### Task 2: ...
 ```
 
-### 5. 提示下一步
+步骤 4 中每个 `### Task N` 的标题与序号须与 `tasks.md`、`writing-plans` 产出中的 Task N **一一对应**。
+
+---
+
+## 步骤 5：生成详细实现计划（writing-plans）
+
+<HARD-GATE>
+本步骤**必须**完整遵循 Superpowers **`writing-plans`** skill（读取并执行其全文：Scope Check、File Structure、Bite-Sized Task Granularity、Plan Document Header、Task Structure、No Placeholders、Self-Review）。**禁止**用本节自订格式替代 writing-plans 的 Task/Step 结构或占位符规则。
+</HARD-GATE>
+
+### 5.1 调用 writing-plans
+
+1. **先读取** Superpowers `writing-plans` skill（`writing-plans/SKILL.md`）
+2. **必须声明**（与 skill 一致，可中英任选其一）：
+   > "I'm using the writing-plans skill to create the implementation plan."
+   > 或：「正在使用 writing-plans skill 生成详细实现计划。」
+3. **输入上下文**（除 writing-plans 要求的 spec 外，sddflow 强制一并阅读）：
+   - `openspec/changes/<变更名>/plan-ready.md`
+   - `openspec/changes/<变更名>/tasks.md`
+   - `openspec/changes/<变更名>/proposal.md`、`design.md`（若存在）、`specs/`
+4. **保存路径**（与 writing-plans 默认一致，变更名替换 feature-name）：
+   `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md`
+
+按 writing-plans 顺序执行：**Scope Check → File Structure → 分解 Task/Step → 写入计划 → Self-Review**。
+
+### 5.2 sddflow 追溯与 Checkbox 扩展（在 writing-plans 规则之上追加）
+
+在**不修改** writing-plans 规定的 Plan Header 与 Task/Step 主体结构的前提下，追加：
+
+1. **Checkbox** — 须满足「三文档 Checkbox 对齐扩展」中 **superpowers plan** 条款（含每个 Task 末尾的 `- [ ] **Task complete**`）
+2. **追溯字段** — 供 `/sddflow build` 定位并同步三份文档：
+
+**Plan Header 在 writing-plans 必填项之后追加：**
+
+```markdown
+**Traceability (sddflow):**
+- plan-ready: `openspec/changes/<变更名>/plan-ready.md`
+- tasks: `openspec/changes/<变更名>/tasks.md`
+- plan: `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md`
+```
+
+**每个 `### Task N` 正文开头（位于 `**Files:**` 之前）必须包含：**
+
+```markdown
+> **trace:** plan-ready.md → `### Task N: <与 plan-ready 完全一致的标题>` | tasks.md → `<tasks.md 中对应条目的原文整行，含 checkbox>`
+> **sync:** tasks.md → `<与 trace 中 tasks.md 行相同的原文整行>` | plan-ready.md → `### Task N: <标题>`
+```
+
+规则：
+- `Task N` 序号在 plan 文件、`plan-ready.md`、`tasks.md` 三者间**一一对应**（N 从 1 递增，不跳号）
+- `trace` / `sync` 中的 `tasks.md`、`plan-ready.md` 引用必须是**可精确匹配的原文**（build 靠此行定位勾选位置）
+- 每个 OpenSpec `tasks.md` 顶层待实现 checkbox 条目至少对应一个 superpowers plan `Task`；每个 `plan-ready.md` 的 `### Task N` 至少对应一个 superpowers plan `Task`
+- writing-plans 的每个 Step 仍使用 `- [ ]` checkbox（build 每完成 Step 立即勾选）
+
+**每个 Task 末尾追加（最后一个 Step 之后）：**
+
+```markdown
+- [ ] **Task complete**（本 Task 全部 Step 为 `[x]` 后勾选；与 plan-ready **任务完成**、tasks.md 对应行同步）
+```
+
+**build 阶段同步契约（写入计划时须自检）：**
+
+| 完成粒度 | 须勾选位置 |
+|----------|------------|
+| 每个 Step 完成 | superpowers plan 对应该 Step 的 `- [ ]` → `[x]` |
+| 整个 Task 完成 | 该 Task 全部 Step 为 `[x]`；superpowers plan **Task complete** → `[x]`；`tasks.md` 中 `sync` 指向行 → `[x]`；`plan-ready.md` 中 **任务完成** → `[x]` |
+
+### 5.3 禁止占位符与自检
+
+**占位符：** 以 writing-plans skill **No Placeholders** 为准（禁止 TBD/TODO/无代码的「写测试」等）；不得因 sddflow 追溯字段而省略完整代码与命令。
+
+**写完计划后依次执行：**
+
+1. writing-plans **Self-Review**（Spec coverage、Placeholder scan、Type consistency）
+2. **三文档 Checkbox 自检**（见「三文档 Checkbox 对齐扩展」）：tasks.md、plan-ready.md、superpowers plan 任务级与 Step 级 checkbox 齐全
+3. sddflow 追溯自检（全部为真才进入步骤 6）：
+   - [ ] `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md` 已存在
+   - [ ] Plan Header 含 writing-plans 必填项 + `**Traceability (sddflow):**`
+   - [ ] 至少 1 个 Task，且 Task 数与 `tasks.md`、`plan-ready.md` 的 `### Task` 数量一致
+   - [ ] 每个 Task 含 `> **trace:**`、`> **sync:**`，且末尾有 `- [ ] **Task complete**`
+   - [ ] 每个 Step 为 writing-plans 粒度，含完整代码块与 Run/Expected（无占位符）
+
+有任一不通过 → 按 writing-plans Self-Review 修正后重做追溯自检，禁止进入步骤 6。
+
+---
+
+## 步骤 6：汇总确认并提示
+
+向用户展示所有产出：
+
+> "spec 阶段完成，以下文件已就绪：
+>
+> **OpenSpec 规格：**
+> - `openspec/changes/<变更名>/proposal.md` ✓
+> - `openspec/changes/<变更名>/design.md` ✓（若存在；否则注明「无 design.md，符合 OpenSpec 可选规则」）
+> - `openspec/changes/<变更名>/specs/` ✓
+> - `openspec/changes/<变更名>/tasks.md` ✓
+>
+> **执行计划：**
+> - `openspec/changes/<变更名>/plan-ready.md` ✓
+> - `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md` ✓
+>
+> 接下来可以用 `/sddflow build` 开始实现。build 会严格校验以上文件完整性后直接执行，不再重新生成计划。"
 
-> "规格已确认，plan-ready.md 已生成。接下来可以用 `/sddflow build` 开始实现。"
+---
 
 ## 关键原则
 
+- **OpenSpec 制品（design.md / specs/ / tasks.md）只按 AGENTS.md + OpenSpec: Proposal 生成**，sddflow 不在此步骤引入自订规则
 - **一条代码都不许写** — spec 阶段只产出文档
-- 本阶段只允许写 `openspec/changes/**` 与 `plan-ready.md`，禁止修改任何代码或实现文件
-- 翻译必须在用户确认后自动生成，不需要用户手动触发
-- plan-ready.md 的 ## 来源 部分必须写明路径，方便 Superpowers 执行时回溯
+- 只允许写 `openspec/changes/**`、`plan-ready.md`、`docs/superpowers/plans/*.md`，禁止修改任何代码
+- 翻译（plan-ready.md、writing-plans）在用户确认 OpenSpec 规格后进行，不改变 delta spec 格式
+- 三份任务文档均须满足「三文档 Checkbox 对齐扩展」，便于对齐是否已实现
+- 步骤 5 须通过 writing-plans Self-Review、Checkbox 自检与追溯自检，否则不允许结束 spec 阶段
+- plan-ready.md 的 `## 来源` 部分必须写明路径
 - 按执行依赖排序是翻译的关键步骤：先依赖后依赖方

package/templates/proposal.md

@@ -1,62 +0,0 @@
----
-name: sddflow/proposal
-description: Lightweight requirement capture — 3-5 questions to quickly converge on requirements
----
-
-# Proposal: 轻量需求捕获
-
-## 目标
-
-用最少的提问，把用户脑子里的需求变成可执行的变更描述。不做深度设计，不生成代码。
-
-## 中断续接规则
-
-如果用户在本阶段被打断后继续回复、补充范围、回答确认问题、或修正边界，仍然停留在 proposal 阶段。继续更新 `openspec/changes/**/proposal.md`，不要因为用户说“就这样做”“继续”“范围改成 X”而写任何代码或实现文件。
-
-典型错误：proposal 阶段确认“只改企业端？”后，用户回复“运营端也要做回显”。这只是需求范围补充，必须继续更新 proposal，不得直接修改任何代码或实现文件。
-
-## 流程
-
-### 1. 提出关键问题
-
-一次性提出以下 3-5 个核心问题（根据上下文调整措辞）：
-
-1. **做什么** — 你想实现什么功能/变更？
-2. **为什么** — 解决什么问题？给谁用的？
-3. **成功标准** — 怎样算做完了？验收条件是什么？
-4. **边界** — 什么不在范围内？
-5. **现有约束** — 有没有技术栈、兼容性、时间上的限制？
-
-### 2. 确认需求
-
-用户回答后，整理成一段简洁的需求描述，与用户确认：
-
-> "我理解的需求是：[一句话概括]。具体来说：[2-3 条要点]。这样理解对吗？"
-
-### 3. 创建 OpenSpec 变更目录
-
-用户确认后，按 OpenSpec 目录约定创建变更。`<变更名>` 使用 kebab-case、动词开头（如 `add-user-login`）：
-
-```bash
-mkdir -p openspec/changes/<变更名>/specs
-```
-
-将确认的需求描述写入 `openspec/changes/<变更名>/proposal.md`。
-
-如果 OpenSpec CLI 可用，可用以下命令检查当前变更列表：
-
-```bash
-openspec list
-```
-
-### 4. 提示下一步
-
-> "需求已记录。接下来可以用 `/sddflow spec` 生成完整规格，或继续补充细节。"
-
-## 注意
-
-- 不要做技术设计，那是 spec 和 brainstorming 的事
-- 不要写代码
-- 本阶段只允许写 OpenSpec 需求文档，禁止修改任何代码或实现文件
-- 问题要具体，不要泛泛而谈
-- 如果用户的需求很大（跨多个独立子系统），建议拆分