@house365/comate 0.9.4 → 0.9.6

package/skills/comate-open/SKILL.md

@@ -1,157 +1,210 @@
----
-name: comate-open
-description: "comate 阶段 1：开题。用 /comate-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）并初始化 .comate.yaml。"
----
-
-# comate 阶段 1：开题（Open）
-
-## 前置条件
-
-- 无活跃 change，或用户希望创建新 change
-
-## 步骤
-
-### 1. 探索想法
-
-**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过。加载后按其指引自由探索问题空间。
-
-### 2. PRD 门禁前置守卫（从 PRD 建 change 时必须先通过）
-
-若本 change **来自一份原始 PRD**（用户经 `/comate-gate` 拆分而来，或直接指定了来源 PRD），**在创建 change 结构之前**必须先过门禁守卫：
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
-
-bash "$COMATE" gate <prd路径> check
-```
-
-- **PASS（exit 0）**：`<PRD>.gate.yaml` 存在、`gate_status ∈ {passed, passed-with-tbd}`、且 PRD 哈希未漂移。继续下一步创建 change。
-- **BLOCK（exit 1）**：门禁不存在 / 未通过 / PRD 通过后被改（stale）。**不得创建 change**，停止并提示用户先跑 `/comate-gate` 对该 PRD 过门禁。
-
-需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。
-
-### 3. 创建 Change 结构 + 初始化状态
-
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需先形成建议，改为加载 `openspec-propose`。禁止跳过。
-
-**命名与范围守卫**：change name 必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
-
-确认产物已创建：
-
-```
-openspec/changes/<name>/
-├── .openspec.yaml
-├── proposal.md       # Why + What：问题、目标、范围、非目标
-├── design.md         # How（高层）：架构决策、方案选型、数据流
-└── tasks.md          # 任务清单（勾选框）
-```
-
-定位 comate 脚本并初始化 `.comate.yaml`：
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
-
-```
-
-### 3b. 判定需求来源(源文件追踪)
-
-`state init` 默认写入 `source_kind: conversation`、`source_manifest: null`(需求由对话产生)。
-
-若本次需求来自 `docs/knowledge-base/` 下的一份或多份知识库文档,追踪它们以支持后续双向排查:
-
-```bash
-bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可选说明>"
-```
-
-- 追踪成功后 `source_kind` 自动改为 `file`,并在 `openspec/changes/<name>/.comate/sources.manifest` 钉住每个文件当时的 sha256 与 commit ref。
-- 仅 `docs/knowledge-base/` 范围内的文件可追踪;范围外文件会被跳过并提示,`source_kind` 保持 `conversation`,不影响流程。
-- 边追踪边产生:若开题时为对话来源、设计中途才拿到知识库文档,后续任意阶段补 `sources <name> track` 即可,无需回到 open。
-
-### 3c. PRD 扇出记录（从 PRD 建 change 时必须登记）
-
-若本 change 来自 PRD，在创建完成后把该 change 记回门禁：
-
-```bash
-bash "$COMATE" gate <prd路径> spawned <name>
-```
-
-此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。
-
-需求**来自对话**时跳过本步。
-
-### 3. 入口状态验证
-
-```bash
-bash "$COMATE" state <name> check open
-```
-
-验证通过后继续 Step 4。失败时脚本输出具体原因。
-
-**幂等性**：open 阶段所有操作可安全重复。若 `.comate.yaml` 已是 `phase: open` 且三件套已存在，跳过已完成步骤，从第一个缺失步骤继续。
-
-### 4. 内容完整性检查
-
+---
+name: comate-open
+description: "comate 阶段 1：开题。用 /comate-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）并初始化 .comate.yaml。"
+---
+
+# comate 阶段 1：开题（Open）
+
+## 前置条件
+
+- 无活跃 change，或用户希望创建新 change
+
+## 步骤
+
+### 1. 探索想法
+
+**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过。加载后按其指引自由探索问题空间。
+
+### 2. PRD 门禁前置守卫（从 PRD 建 change 时必须先通过）
+
+若本 change **来自一份原始 PRD**（用户经 `/comate-gate` 拆分而来，或直接指定了来源 PRD），**在创建 change 结构之前**必须先过门禁守卫：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+bash "$COMATE" gate <prd路径> check
+```
+
+- **PASS（exit 0）**：`<PRD>.gate.yaml` 存在、`gate_status ∈ {passed, passed-with-tbd}`、且 PRD 哈希未漂移。继续下一步创建 change。
+- **BLOCK（exit 1）**：门禁不存在 / 未通过 / PRD 通过后被改（stale）。**不得创建 change**，停止并提示用户先跑 `/comate-gate` 对该 PRD 过门禁。
+
+需求**来自对话**（非 PRD）时跳过本步——门禁只约束「PRD → change」这条路径。
+
+### 3. 创建 Change 结构 + 初始化状态
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需先形成建议，改为加载 `openspec-propose`。禁止跳过。
+
+**命名与范围守卫**：change name 必须用用户指定或经 AskUserQuestion 确认的名称，不得自动生成或推断。变更范围必须与用户描述一致，不得自行扩大或缩小。
+
+确认产物已创建：
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── proposal.md       # Why + What：问题、目标、范围、非目标
+├── design.md         # How（高层）：架构决策、方案选型、数据流
+└── tasks.md          # 任务清单（勾选框）
+```
+
+定位 comate 脚本并初始化 `.comate.yaml`：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+bash "$COMATE" state <name> init full
+```
+
+这会创建 `openspec/changes/<name>/.comate.yaml`，初始状态：`workflow: full`, `phase: open`, `phase_step: null`。
+
+### 3b. 判定需求来源(源文件追踪)
+
+`state init` 默认写入 `source_kind: conversation`、`source_manifest: null`(需求由对话产生)。
+
+若本次需求来自 `docs/knowledge-base/` 下的一份或多份知识库文档,追踪它们以支持后续双向排查:
+
+```bash
+bash "$COMATE" sources <name> track docs/knowledge-base/<path>.md --note "<可选说明>"
+```
+
+- 追踪成功后 `source_kind` 自动改为 `file`,并在 `openspec/changes/<name>/.comate/sources.manifest` 钉住每个文件当时的 sha256 与 commit ref。
+- 仅 `docs/knowledge-base/` 范围内的文件可追踪;范围外文件会被跳过并提示,`source_kind` 保持 `conversation`,不影响流程。
+- 边追踪边产生:若开题时为对话来源、设计中途才拿到知识库文档,后续任意阶段补 `sources <name> track` 即可,无需回到 open。
+
+### 3c. PRD 扇出记录（从 PRD 建 change 时必须登记）
+
+若本 change 来自 PRD，在创建完成后把该 change 记回门禁：
+
+```bash
+bash "$COMATE" gate <prd路径> spawned <name>
+```
+
+此步将 change 名称追加到 `<PRD>.gate.yaml` 的 `spawned_changes` 列表，用于追溯 PRD → change 的完整扇出关系。
+
+需求**来自对话**时跳过本步。
+
+### 3. 入口状态验证与幂等性检查
+
+```bash
+bash "$COMATE" state <name> check open
+```
+
+验证通过后继续 Step 4。失败时脚本输出具体原因。
+
+**幂等性检查**：
+
+1. 读取 `.comate.yaml` 的 `phase`、`phase_step`、workflow、以及三件套文件路径
+
+2. **已完成 Step 5（产物已审视确认）** 的判定条件：
+   - `phase_step` 值为 `open.review-confirmed`（旧版 `5-confirmed` 兼容一次）
+   - 或 `phase` 已经不是 `open`（说明已流转到下一阶段）
+
+3. **幂等分支**：
+   - **已完成 Step 5** → 跳过所有步骤，说明「开题已完成，三件套已确认」，直接检查退出条件（guard）
+   - **未完成 Step 5** → 检查三件套是否存在：
+     - 三件套全部存在且非空 → 跳到 Step 4（内容完整性检查）
+     - 任一文件缺失或为空 → 从 Step 1 开始（如果是首次）或 Step 3b/3c（如果是 PRD 来源）
+
+4. **断点恢复**（根据 `phase_step` 值）：
+   - `phase_step` 为 `open.artifacts-created` → 从 Step 4 开始
+   - `phase_step` 为 `open.review-awaiting`（或旧版 `4`）→ 恢复 Step 5 的用户确认，并改写为新格式
+   - `phase_step` 为 `open.review-confirmed`（或旧版 `5-confirmed`）→ 见第 3 点幂等分支
+
+5. **open 阶段特点**：open 阶段的所有操作（explore、创建三件套、状态初始化）可安全重复执行。但**产物审视（Step 5）的用户确认不可重复**，一旦 `phase_step: open.review-confirmed` 被记录，即使上下文压缩也不得重新要求用户确认。
+
+### 4. 内容完整性检查
+
 逐个确认三个文件路径存在且非空：
-- **proposal.md**：问题背景、目标、范围、非目标
-- **design.md**：高层架构决策、方案选型、数据流
-- **tasks.md**：任务列表，每个任务有明确描述
-
+- **proposal.md**：问题背景、目标、范围、非目标
+- **design.md**：高层架构决策、方案选型、数据流
+- **tasks.md**：任务列表，每个任务有明确描述
+
 任一文件缺失或为空时，不得进入 Step 5 或执行守卫，必须回创建步骤补充。
 
-### 5. 产物审视（决策阻塞点 1，按来源分类）
-
-三件套完成且 Step 4 完整性检查通过后，**先按来源分类，再决定是否需要用户输入**。规则见 `comate/reference/decision-points.md` 第 1 条。
-
-#### 5a. 判定是否属"PRD 扇出且范围一致"（可自动流转）
-
-同时满足以下**全部**条件时，本决策点降级为自动流转，**不 AskUserQuestion**：
-
-1. `source_kind: file`（本 change 追踪了源文件）；
-2. 追踪的源是一份 PRD，且 `bash "$COMATE" gate <prd路径> check` 返回 PASS（exit 0）——即门禁 `passed`/`passed-with-tbd` 且 PRD 哈希未漂移。PRD 路径从 `sources <name> list` 或 Step 2c 的上下文取得；
-3. change 名已记入该 PRD 的 `spawned_changes`（Step 6 的 `gate spawned` 已执行，通常由 `/comate-gate` 备妥）；
-4. **范围一致性自检**：proposal 的目标/范围/非目标忠实承接 gate 映射里本 change 认领的功能项——没有擅自扩大或缩小、没有认领未分配的功能项、没有漏掉已分配项。
-
-四条全成立时：范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，无新的有效选项。直接进入退出条件执行守卫流转，并**如实报告**：本 change 承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
-
-#### 5b. 需要用户输入的两种情形（AskUserQuestion 阻塞）
-
-- **对话来源**（`source_kind: conversation`）：范围此前未经用户拍板，三件套第一次成形。
-- **PRD 扇出但 5a 第 4 条不成立**（范围与映射有偏差）：分歧重新出现。
+完整性检查通过后记录：
 
+```bash
+bash "$COMATE" state <name> set phase_step open.artifacts-created
+```
+
+### 5. 产物审视（决策阻塞点 1，按来源分类）
+
+三件套完成且 Step 4 完整性检查通过后，**先按来源分类，再决定是否需要用户输入**。规则见 `comate/reference/decision-points.md` 第 1 条。
+
+#### 5a. 判定是否属"PRD 扇出且范围一致"（可自动流转）
+
+同时满足以下**全部**条件时，本决策点降级为自动流转，**不 AskUserQuestion**：
+
+1. `source_kind: file`（本 change 追踪了源文件）；
+2. 追踪的源是一份 PRD，且 `bash "$COMATE" gate <prd路径> check` 返回 PASS（exit 0）——即门禁 `passed`/`passed-with-tbd` 且 PRD 哈希未漂移。PRD 路径从 `sources <name> list` 或 Step 3c 的上下文取得；
+3. change 名已记入该 PRD 的 `spawned_changes`（Step 3c 的 `gate spawned` 已执行，通常由 `/comate-gate` 备妥）；
+4. **范围一致性自检**：proposal 的目标/范围/非目标忠实承接 gate 映射里本 change 认领的功能项——没有擅自扩大或缩小、没有认领未分配的功能项、没有漏掉已分配项。
+
+四条全成立时：范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，无新的有效选项。
+
+**自动流转处理**：
+
+1. **记录自动确认状态**：
+   ```bash
+   bash "$COMATE" state <name> set phase_step open.review-confirmed
+   ```
+
+2. **如实报告**：「本 change 承接自 PRD <prd-name>，认领功能项：<列出项>。已核对范围与映射一致，自动进入下一阶段。」
+
+3. 直接进入退出条件执行守卫流转
+
+#### 5b. 需要用户输入的两种情形（AskUserQuestion 阻塞）
+
+- **对话来源**（`source_kind: conversation`）：范围此前未经用户拍板，三件套第一次成形。
+- **PRD 扇出但 5a 第 4 条不成立**（范围与映射有偏差）：分歧重新出现。
+
 以上任一情形，**必须使用 AskUserQuestion 工具暂停等待用户确认**。以单选题呈现摘要（proposal 问题/目标/范围、design 架构决策/选型、tasks 数量与关键任务；PRD 偏差场景额外列出偏差点）和选项：
-- 「确认，继续下一阶段」— 执行守卫流转
-- 「需要调整」— 附调整说明（PRD 偏差场景默认建议按映射修正），修改后重新请求确认
-
-## 退出条件
-
-- 三件套已创建且内容完整
-- **用户已确认**
-- **阶段守卫**：运行 `bash "$COMATE" guard <name> open --apply`，全 PASS 后自动流转
-
-退出前必须 `--apply`，否则 `.comate.yaml` 停留在 `phase: open`，下阶段入口检查会失败。
+- 「确认，继续下一阶段」— 记录确认状态后执行守卫流转
+- 「需要调整」— 附调整说明（PRD 偏差场景默认建议按映射修正），修改后重新请求确认
+
+**提问前先持久化等待状态**：
 
 ```bash
-bash "$COMATE" guard <name> open --apply
+bash "$COMATE" state <name> set phase_step open.review-awaiting
 ```
 
-full 流程自动更新为 `phase: design`；fix 预设自动更新为 `phase: build`。
-
-## 自动流转
-
-用户确认后退出条件满足，自动流转：
-
-> **REQUIRED NEXT SKILL（完整流程）：** 调用 `comate-design` skill 进入深度设计。
->
-> fix 预设由 `/comate-fix` skill 控制后续流转（phase 直接进 build），不经过本节。
+**用户确认后立即记录**：
+
+```bash
+bash "$COMATE" state <name> set phase_step open.review-confirmed
+```
+
+然后继续执行退出条件（guard）。
+
+## 退出条件
+
+- 三件套已创建且内容完整
+- **用户已确认**
+- **阶段守卫**：运行 `bash "$COMATE" guard <name> open --apply`，全 PASS 后自动流转
+
+退出前必须 `--apply`，否则 `.comate.yaml` 停留在 `phase: open`，下阶段入口检查会失败。
+
+```bash
+bash "$COMATE" guard <name> open --apply
+```
+
+full 流程自动更新为 `phase: design`；fix 预设自动更新为 `phase: build`。
+
+## 自动流转
+
+用户确认后退出条件满足，自动流转：
+
+> **REQUIRED NEXT SKILL（完整流程）：** 调用 `comate-design` skill 进入深度设计。
+>
+> fix 预设由 `/comate-fix` skill 控制后续流转（phase 直接进 build），不经过本节。