@house365/comate 0.9.24 → 0.9.26

package/skills/comate/SKILL.md

@@ -1,48 +1,48 @@
----
-name: comate
-description: "comate —— SDD (规约驱动开发) 编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
----
-
-# comate —— SDD (规约驱动开发) 编排器
-
-
-**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
-
----
-
-## 决策核心
-
-agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
-
-### 自动阶段探测
-
-**Step 0：活跃 change 发现 + 决策状态优先检查**
-
-<CRITICAL>
+---
+name: comate
+description: "comate —— SDD (规约驱动开发) 编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
+---
+
+# comate —— SDD (规约驱动开发) 编排器
+
+
+**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
+
+---
+
+## 决策核心
+
+agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
+
+### 自动阶段探测
+
+**Step 0：活跃 change 发现 + 决策状态优先检查**
+
+<CRITICAL>
 **执行顺序不可颠倒**：先识别用户是否明确要求新建 change；否则读取状态检查明确的 `*-awaiting` 决策标记，再做普通意图过滤和 change 匹配。
 若用户正在回答已持久化的决策问题（如"worktree + TDD"、"确认方案A"），直接路由到对应子 skill。
-</CRITICAL>
-
-1. **活跃 change 快速发现**：
-   
-   运行 `openspec list --json` 获取所有活跃 change。
-   
-   - **无活跃 change** → 跳到步骤 3（意图快速过滤 + 预设探测）
-   - **有活跃 change** → 继续步骤 2
-
+</CRITICAL>
+
+1. **活跃 change 快速发现**：
+   
+   运行 `openspec list --json` 获取所有活跃 change。
+   
+   - **无活跃 change** → 跳到步骤 3（意图快速过滤 + 预设探测）
+   - **有活跃 change** → 继续步骤 2
+
 2. **待决策状态检查**（防止决策答复被误判为新任务）：
-   
-   a. **确定目标 change**：
-      - 恰好 1 个活跃 change → 自动选中
-      - 多个活跃 change 且用户指定了 change 名称（`/comate <name>`）→ 选中该 change
-      - 多个活跃 change 且用户未指定 → **暂存待选列表，继续检查**（稍后在步骤 3.2 处理）
-   
-   b. **读取状态（若已确定目标 change）**：
-      
-      读取 `openspec/changes/<name>/.comate.yaml`，获取 `phase` 和 `phase_step`。
-   
+   
+   a. **确定目标 change**：
+      - 恰好 1 个活跃 change → 自动选中
+      - 多个活跃 change 且用户指定了 change 名称（`/comate <name>`）→ 选中该 change
+      - 多个活跃 change 且用户未指定 → **暂存待选列表，继续检查**（稍后在步骤 3.2 处理）
+   
+   b. **读取状态（若已确定目标 change）**：
+      
+      读取 `openspec/changes/<name>/.comate.yaml`，获取 `phase` 和 `phase_step`。
+   
    c. **检查是否在等待决策**：
-      
+      
       只有 `phase_step` 是当前阶段的明确等待标记时，才说明子 skill 正在等待用户答复：
       - `open.review-awaiting`
       - `design.approval-awaiting`
@@ -52,297 +52,297 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
       兼容 `bd16c0f` 产生的活跃状态：仅在 phase 对应时，把 `open:4`、`design:1b`、`build:2` 分别视为上述等待标记；恢复后立即写入新格式。其它旧值只是普通进度。
 
       普通进度（如 `design.brainstorm-complete`）、已确认状态和依赖阻塞状态都**不是**待决策，不得抢占用户的新请求。用户明确说“新建 change”时也优先按新建意图处理。
-      
+      
       **立即路由到对应子 skill**（根据 `phase` 字段）：
       - `phase_step: fix.upgrade-awaiting` → 无论当前是 `phase: open` 还是 `phase: build`，调用 `/comate-fix`
       - `phase: open` → 调用 `/comate-open`
-      - `phase: design` → 调用 `/comate-design`
-      - `phase: build` → 调用 `/comate-build`
-      - `phase: verify` → 调用 `/comate-verify`
-      - `phase: archive` → 调用 `/comate-archive`
-      
-      子 skill 的**幂等性检查**会：
-      1. 读取 `phase_step` 的值
-      2. 验证该步骤是否与当前 `phase` 匹配
-      3. 恢复到正确的步骤（跳过已完成的步骤，直接进入下一步）
-      
-      **结束 Step 0，不执行后续逻辑**。
-   
+      - `phase: design` → 调用 `/comate-design`
+      - `phase: build` → 调用 `/comate-build`
+      - `phase: verify` → 调用 `/comate-verify`
+      - `phase: archive` → 调用 `/comate-archive`
+      
+      子 skill 的**幂等性检查**会：
+      1. 读取 `phase_step` 的值
+      2. 验证该步骤是否与当前 `phase` 匹配
+      3. 恢复到正确的步骤（跳过已完成的步骤，直接进入下一步）
+      
+      **结束 Step 0，不执行后续逻辑**。
+   
    d. **若没有匹配当前阶段的等待标记**：
-      
-      说明没有未完成的决策点，继续步骤 3（意图过滤）。
-
-3. **意图快速过滤 + 幂等性匹配**：
-
-   3.1. **意图快速过滤**（仅当步骤 2 未命中时执行）：
-
-   先检查用户输入是否**明确表达了希望进入某个特定阶段**。如果用户没有明确指示，则无条件自动探测当前阶段，不询问不推测。
-
-   **明确意图的识别规则**：用户消息中包含以下**动作关键词 + 阶段名**的直接组合之一时，才算明确意图：
-   
-   | 阶段 | 明确意图的关键词组合（任一命中即算） |
-   |------|-------------------------------------|
-   | open | "开题"/"创建 change"/"新建 change"/"起草 proposal" |
-   | design | "设计"/"写设计文档"/"brainstorming"/"开始设计" |
-   | build | "实施"/"开始构建"/"执行计划"/"写代码"/"开始 build" |
-   | verify | "验证"/"检查实现"/"运行测试"/"开始 verify" |
-   | archive | "归档"/"完成收尾"/"合并 delta spec"/"开始 archive" |
-
-   **不算明确意图的情况**（这些都应自动探测，不询问）：
-   - 仅提及问题、需求、想法，无阶段动作词："修复这个 bug" / "优化性能" / "加个功能"
-   - 仅描述当前状态："设计做完了" / "代码写好了" / "测试通过了"
-   - 询问式："现在该做什么" / "下一步是什么" / "继续"
-   - 澄清式："刚才的设计有问题" / "build 阶段遇到错误"
-   - **决策答复**："worktree + TDD" / "选择方案 A" / "确认" / "继续构建"（这些应在步骤 2 被拦截）
-
-   **过滤结果**：
-   - **明确意图命中** → 直接跳到对应阶段的 skill（不运行后续步骤）
-   - **无明确意图** → 继续步骤 3.2
-
-   3.2. **活跃 change 匹配**（防止重复创建 change）：
-   
-   **前置条件**：有活跃 change 且用户输入无明确意图。
-   
-   **处理逻辑**：
-   
-   a. **用户输入仅为 `/comate` 无任何描述**：
-      - 恰好 1 个活跃 change → 已在步骤 2 选中，进入 Step 1
-      - 多个活跃 change → 列出所有 change 供用户选择，选中后进入 Step 1
-   
-   b. **用户输入包含任务描述但未指定 change 名称**（`/comate <描述>`）：
-      - **关键幂等检查**（防止重复创建 change）：
-        1. 遍历所有活跃 change
-        2. 对每个 change，读取 `proposal.md` 和 `specs/*/spec.md`
-        3. 检查用户描述是否与该 change 的需求高度匹配（关键词重叠、问题域相同、目标一致）
-        4. **若找到匹配的 change**：
-           - 自动选中该 change
-           - 说明「检测到您的描述与活跃 change <name> 的需求匹配，将继续该 change」
-           - 进入 Step 1（读取该 change 的状态）
-        5. **若所有 change 都不匹配**：
-           - **AskUserQuestion 询问**：「检测到 {N} 个活跃 change：{列表及简要描述}。您的任务是：继续某个已有 change，还是新建 change？」
-           - 选项 1：「继续已有 change」→ 让用户选择具体哪个 change，进入 Step 1
-           - 选项 2：「新建 change」→ 进入步骤 4（预设探测）
-
-4. **预设探测**（决定新 change 的入口）：
-
-   当确定需要新建 change 时（无活跃 change，或用户选择新建），按以下优先级探测：
-   
-   a. **fix 预设**：
-      - 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整
-      - 且满足 fix 条件（见 `/comate-fix` skill）
-      - → 直接调用 `/comate-fix`，不进入普通 open 分支
-   
-   b. **gate 预设**（原始 PRD 入口）：
-      - 用户输入指向一份原始 PRD（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」）
-      - 典型路径：`docs/knowledge-base/**/PRD-*.md`
-      - **且无对应活跃 change**
-      - → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）
-      - **不要直接调 `/comate-open`**——PRD 必须先过质量门禁
-   
-   c. **普通 open**（默认）：
-      - 无预设命中
-      - → 调用 `/comate-open`
-
-<IMPORTANT>
-用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
-`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
-直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
-</IMPORTANT>
-
-**Step 1：读取 `.comate.yaml` 状态元数据**（仅在 Step 0 未直接路由时执行）
-
-优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
-
-**关键字段**：
-- `phase`：当前阶段（`open` / `design` / `build` / `verify` / `archive`）
+      
+      说明没有未完成的决策点，继续步骤 3（意图过滤）。
+
+3. **意图快速过滤 + 幂等性匹配**：
+
+   3.1. **意图快速过滤**（仅当步骤 2 未命中时执行）：
+
+   先检查用户输入是否**明确表达了希望进入某个特定阶段**。如果用户没有明确指示，则无条件自动探测当前阶段，不询问不推测。
+
+   **明确意图的识别规则**：用户消息中包含以下**动作关键词 + 阶段名**的直接组合之一时，才算明确意图：
+   
+   | 阶段 | 明确意图的关键词组合（任一命中即算） |
+   |------|-------------------------------------|
+   | open | "开题"/"创建 change"/"新建 change"/"起草 proposal" |
+   | design | "设计"/"写设计文档"/"brainstorming"/"开始设计" |
+   | build | "实施"/"开始构建"/"执行计划"/"写代码"/"开始 build" |
+   | verify | "验证"/"检查实现"/"运行测试"/"开始 verify" |
+   | archive | "归档"/"完成收尾"/"合并 delta spec"/"开始 archive" |
+
+   **不算明确意图的情况**（这些都应自动探测，不询问）：
+   - 仅提及问题、需求、想法，无阶段动作词："修复这个 bug" / "优化性能" / "加个功能"
+   - 仅描述当前状态："设计做完了" / "代码写好了" / "测试通过了"
+   - 询问式："现在该做什么" / "下一步是什么" / "继续"
+   - 澄清式："刚才的设计有问题" / "build 阶段遇到错误"
+   - **决策答复**："worktree + TDD" / "选择方案 A" / "确认" / "继续构建"（这些应在步骤 2 被拦截）
+
+   **过滤结果**：
+   - **明确意图命中** → 直接跳到对应阶段的 skill（不运行后续步骤）
+   - **无明确意图** → 继续步骤 3.2
+
+   3.2. **活跃 change 匹配**（防止重复创建 change）：
+   
+   **前置条件**：有活跃 change 且用户输入无明确意图。
+   
+   **处理逻辑**：
+   
+   a. **用户输入仅为 `/comate` 无任何描述**：
+      - 恰好 1 个活跃 change → 已在步骤 2 选中，进入 Step 1
+      - 多个活跃 change → 列出所有 change 供用户选择，选中后进入 Step 1
+   
+   b. **用户输入包含任务描述但未指定 change 名称**（`/comate <描述>`）：
+      - **关键幂等检查**（防止重复创建 change）：
+        1. 遍历所有活跃 change
+        2. 对每个 change，读取 `proposal.md` 和 `specs/*/spec.md`
+        3. 检查用户描述是否与该 change 的需求高度匹配（关键词重叠、问题域相同、目标一致）
+        4. **若找到匹配的 change**：
+           - 自动选中该 change
+           - 说明「检测到您的描述与活跃 change <name> 的需求匹配，将继续该 change」
+           - 进入 Step 1（读取该 change 的状态）
+        5. **若所有 change 都不匹配**：
+           - **AskUserQuestion 询问**：「检测到 {N} 个活跃 change：{列表及简要描述}。您的任务是：继续某个已有 change，还是新建 change？」
+           - 选项 1：「继续已有 change」→ 让用户选择具体哪个 change，进入 Step 1
+           - 选项 2：「新建 change」→ 进入步骤 4（预设探测）
+
+4. **预设探测**（决定新 change 的入口）：
+
+   当确定需要新建 change 时（无活跃 change，或用户选择新建），按以下优先级探测：
+   
+   a. **fix 预设**：
+      - 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整
+      - 且满足 fix 条件（见 `/comate-fix` skill）
+      - → 直接调用 `/comate-fix`，不进入普通 open 分支
+   
+   b. **gate 预设**（原始 PRD 入口）：
+      - 用户输入指向一份原始 PRD（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」）
+      - 典型路径：`docs/knowledge-base/**/PRD-*.md`
+      - **且无对应活跃 change**
+      - → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）
+      - **不要直接调 `/comate-open`**——PRD 必须先过质量门禁
+   
+   c. **普通 open**（默认）：
+      - 无预设命中
+      - → 调用 `/comate-open`
+
+<IMPORTANT>
+用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
+`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
+直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
+</IMPORTANT>
+
+**Step 1：读取 `.comate.yaml` 状态元数据**（仅在 Step 0 未直接路由时执行）
+
+优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
+
+**关键字段**：
+- `phase`：当前阶段（`open` / `design` / `build` / `verify` / `archive`）
 - `phase_step`：当前阶段内的步骤标记（如 `design.approval-awaiting`、`build.options-confirmed`）
-- `workflow`：流程类型（`full` / `fix`）
-- `build_mode`、`isolation`、`tdd_mode`：build 阶段的决策字段
-- `verify_result`：验证结果（`pending` / `pass` / `fail`）
-
-**phase_step 语义说明**：
-
+- `workflow`：流程类型（`full` / `fix`）
+- `build_mode`、`isolation`、`tdd_mode`：build 阶段的决策字段
+- `verify_result`：验证结果（`pending` / `pass` / `fail`）
+
+**phase_step 语义说明**：
+
 `phase_step` 记录**当前阶段**内的步骤，用于断点恢复和幂等性检查：
 - 非空值表示"已完成到该步骤"，恢复时从**下一步**开始
 - `*-awaiting` 表示正在等待用户答复，只有这类值触发决策优先路由
 - `*-confirmed` 表示用户已确认的决策点
 - `build.blocked-by-<dependency>` 表示被依赖阻塞，但不是等待当前用户决策
 - 空值或 `null` 表示该阶段尚未开始或已完成所有步骤
-
-**断点恢复规则**：
-- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
-- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
-- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
-- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
+
+**断点恢复规则**：
+- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
+- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
+- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
+- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
 - 若 `phase: open` 但 proposal/design/tasks 已完成，按 `workflow` 恢复：`fix` 调 `/comate-fix`，`full` 调 `/comate-open`；对应 skill 立即运行 `bash "$COMATE" guard <name> open --apply` 修复状态，并在 guard 成功后同轮继续下一阶段。
-- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
-
+- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
+
 **phase_step 生命周期**：
 
 `phase_step` 严格属于当前阶段。所有 `state transition` 在切换 `phase` 时原子清空 `phase_step` 和 `phase_step_data`。禁止跨阶段保留或比较步骤编号；跨阶段事实必须记录在专用字段或落盘产物中。
-
-**Step 2：阶段判定**（按顺序检查，首个命中者生效）
-
-1. `archived: true` 或 change 已移入 archive → 流程完成
-2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
-3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
+
+**Step 2：阶段判定**（按顺序检查，首个命中者生效）
+
+1. `archived: true` 或 change 已移入 archive → 流程完成
+2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
+3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
 4. `phase: verify` → 调用 `/comate-verify`。`tasks.md` 全勾不能单独触发 verify；验证失败回退到 build 后，必须继续按 build 路由修复。
 5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
-6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
+6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
 7. `phase: open` → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-open`；有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
-8. 无活跃 change → 调用 `/comate-open`
-
-元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
-
-### 预设升级判定
-
-**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
-
-### 错误处理速查
-
-| 场景 | 处理 |
-|------|------|
-| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
-| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
-| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
-| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
-
-### 阶段流转
-
-<IMPORTANT>
-一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
-
-流转链：open → design → build → verify → archive
-
+8. 无活跃 change → 调用 `/comate-open`
+
+元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
+
+### 预设升级判定
+
+**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
+
+### 错误处理速查
+
+| 场景 | 处理 |
+|------|------|
+| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
+| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
+| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
+
+### 阶段流转
+
+<IMPORTANT>
+一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
+
+流转链：open → design → build → verify → archive
+
 **连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
 
 guard 成功、代码提交成功以及用户已经完成某个决策后的操作都不是新的暂停点。状态已满足下一阶段入口时，必须在当前调用内重新探测并继续；尤其是 fix 流程不得停在 `phase: open` 实现代码，也不得停在 build 提交之后等待用户发送“继续”。
-
-7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
-</IMPORTANT>
-
----
-
-## 子命令速查
-
-| 命令 | 阶段 | Owner | 产物 |
-|------|------|-------|------|
-| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
-| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
-| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
-| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
-| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
-| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
-| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
-| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
-
-```
-[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
-                  (Claude)        │
-/comate                           ▼
-  ↓ 自动探测
-/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
-  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
-```
-
-需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
-
----
-
-## 参考附录
-
-### 脚本定位（单一入口）
-
-comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
-
-```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
-```
-
-之后全程复用 `$COMATE`：
-
-```bash
-bash "$COMATE" state   <name> init <full|fix>
-bash "$COMATE" state   <name> transition <event>
-bash "$COMATE" state   <name> check <phase> [--json]
-bash "$COMATE" state   <name> recover <phase>
-bash "$COMATE" state   <name> scale
-bash "$COMATE" state   <name> validate
-bash "$COMATE" guard   <name> <phase> [--apply] [--json]
-bash "$COMATE" handoff <name> <design|build> --write [--full]
-bash "$COMATE" sources <name> track <file...> [--note <text>]
+
+7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | Owner | 产物 |
+|------|------|-------|------|
+| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
+| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
+| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
+| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
+| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
+| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
+| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
+| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
+
+```
+[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
+                  (Claude)        │
+/comate                           ▼
+  ↓ 自动探测
+/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
+  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
+```
+
+需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
+
+---
+
+## 参考附录
+
+### 脚本定位（单一入口）
+
+comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
+
+```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
+```
+
+之后全程复用 `$COMATE`：
+
+```bash
+bash "$COMATE" state   <name> init <full|fix>
+bash "$COMATE" state   <name> transition <event>
+bash "$COMATE" state   <name> check <phase> [--json]
+bash "$COMATE" state   <name> recover <phase>
+bash "$COMATE" state   <name> scale
+bash "$COMATE" state   <name> validate
+bash "$COMATE" guard   <name> <phase> [--apply] [--json]
+bash "$COMATE" handoff <name> <design|build> --write [--full]
+bash "$COMATE" sources <name> track <file...> [--note <text>]
 bash "$COMATE" sources <name> check | list
 bash "$COMATE" sources find <file>
 bash "$COMATE" dependency <name> archived
 bash "$COMATE" archive <name> [--dry-run]
-bash "$COMATE" status
-bash "$COMATE" doctor
-```
-
-`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
-
-### `.comate.yaml` 字段参考
-
-状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
-
-| 字段 | 含义 |
-|------|------|
-| `schema_version` | 状态文件格式版本（当前 1） |
-| `workflow` | `full` / `fix` |
-| `phase` | `open` / `design` / `build` / `verify` / `archive` |
-| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
-| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
-| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
-| `verify_mode` | `light` / `full`（由 scale 评估写入） |
-| `verify_result` | `pending` / `pass` / `fail` |
-| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
+bash "$COMATE" status
+bash "$COMATE" doctor
+```
+
+`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
+
+### `.comate.yaml` 字段参考
+
+状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
+
+| 字段 | 含义 |
+|------|------|
+| `schema_version` | 状态文件格式版本（当前 1） |
+| `workflow` | `full` / `fix` |
+| `phase` | `open` / `design` / `build` / `verify` / `archive` |
+| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
+| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
+| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
+| `verify_mode` | `light` / `full`（由 scale 评估写入） |
+| `verify_result` | `pending` / `pass` / `fail` |
+| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
 | `branch_status` | `pending` / `handled` / `discarded` |
-| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
-| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
-| `direct_override` | full 流程用 `direct` 需显式 `true` |
-| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
-| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
-| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
-
-状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
-- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
-- `build → verify` 前 `build_mode` 必须已选
-- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
-- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
-- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
-
-### 文件结构
-
-```
-openspec/                              # OpenSpec —— WHAT
-├── changes/<name>/
-│   ├── .comate.yaml                   # comate 状态机真相源
-│   ├── proposal.md / design.md / tasks.md
-│   ├── specs/<capability>/spec.md     # delta 能力规格
-│   └── .comate/handoff/               # 脚本生成的阶段交接包
-│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
-└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
-
-docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
-
-docs/superpowers/                      # Superpowers —— HOW
-├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
-├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
-└── reports/                           # 验证报告
-```
-
-### 最佳实践
-
-1. brainstorming 不可跳过（fix 除外）
-2. delta spec 是活文档，build 阶段随时改，归档时同步
-3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
-4. tasks.md 实时同步，每完成一个任务勾选并提交
-5. 验证通过才归档
-6. 预设有边界，命中升级条件及时转 full
+| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
+| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
+| `direct_override` | full 流程用 `direct` 需显式 `true` |
+| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
+| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
+| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
+
+状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
+- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
+- `build → verify` 前 `build_mode` 必须已选
+- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
+- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
+- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec —— WHAT
+├── changes/<name>/
+│   ├── .comate.yaml                   # comate 状态机真相源
+│   ├── proposal.md / design.md / tasks.md
+│   ├── specs/<capability>/spec.md     # delta 能力规格
+│   └── .comate/handoff/               # 脚本生成的阶段交接包
+│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
+└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
+
+docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
+
+docs/superpowers/                      # Superpowers —— HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
+├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
+└── reports/                           # 验证报告
+```
+
+### 最佳实践
+
+1. brainstorming 不可跳过（fix 除外）
+2. delta spec 是活文档，build 阶段随时改，归档时同步
+3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
+4. tasks.md 实时同步，每完成一个任务勾选并提交
+5. 验证通过才归档
+6. 预设有边界，命中升级条件及时转 full