@house365/comate 0.8.0 → 0.9.1

package/README.md

@@ -1,8 +1,8 @@
 # comate
 
-OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
+**SDD (规约驱动开发)** 的 AI 开发编排器。
 
-comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(fix 预设除外)。
+comate 践行 **Specification-Driven Development (SDD)** 理念，通过五阶段工作流（gate → open → design → build → verify → archive）确保每个变更都有完整的规约与设计（fix 预设除外）。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
 
 ## 五阶段
 

package/bin/cli.mjs

@@ -27,7 +27,7 @@ if (args[0] === 'usage') {
 }
 
 if (args[0] === '--help' || args[0] === '-h') {
-  console.log(`comate — OpenSpec + Superpowers 规约驱动的开发编排器
+  console.log(`comate — SDD (规约驱动开发) 的 AI 开发编排器
 
 用法:
   comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/

package/docs/COMATE_MANUAL.md

@@ -1,8 +1,8 @@
-# comate - OpenSpec + Superpowers - 操作手册
+# comate - 操作手册
 
-> OpenSpec + Superpowers - 规约驱动的开发编排器
+> SDD (规约驱动开发) 的 AI 开发编排器
 > 版本：schema_version 1，五阶段工作流
-> 最后更新：2026-08-14
+> 最后更新：2026-08-17
 
 ---
 
@@ -25,7 +25,7 @@
 
 ## 1. 概述与核心概念
 
-comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**（WHAT：启动、提案、规约生命周期、归档）和 **Superpowers**（HOW：技术设计、规划、执行、收尾）整合为一个统一的五阶段工作流。
+comate 是一个 **Specification-Driven Development (SDD，规约驱动开发)** 的 AI 开发编排器，通过五阶段工作流确保每个变更都有完整的规约与设计。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
 ### 1.1 核心原则
 
 **头脑风暴是强制性的。每个变更都必须经过深度设计（fix 预设除外）。**
@@ -321,7 +321,7 @@ bash "$COMATE" doctor
 2. **探索现有能力**：调用 `openspec-explore` 探索现有能力和规约状态。
 3. **创建变更目录**：调用 `openspec-new-change`（内部 `/opsx:new`）生成 proposal.md、design.md、tasks.md 骨架，**并立即写入 `.comate.yaml`**。
 4. **提案审核**：调用 `openspec-propose` 充实 proposal、design、tasks。
-5. **产出物审核确认（决策点 1）**：当 proposal/design/tasks 完成且内容全面后，暂停等待用户确认或调整请求。
+5. **产出物审核（决策点 1，按来源分类）**：proposal/design/tasks 完成且内容全面后先按来源分类——**PRD 扇出且范围与 gate 映射一致**时属自动处理，完整性检查通过即自动流转并报告承接情况，不再暂停；**对话来源**或 **PRD 扇出但范围有偏差**时暂停等待用户确认或调整请求。详见 `comate/reference/decision-points.md` 第 1 条。
 6. **退出**：用户确认后，运行 `bash $COMATE guard <name> open --apply` 进行验证并自动推进到 design。
 
 ### 5.2 阶段 2：深度设计（/comate-design）

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@house365/comate",
-  "version": "0.8.0",
-  "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
+  "version": "0.9.1",
+  "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/skills/comate/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: comate
-description: "comate —— OpenSpec + Superpowers 规格驱动开发编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
+description: "comate —— SDD (规约驱动开发) 编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
 ---
 
-# comate —— OpenSpec + Superpowers 规格驱动开发流
+# comate —— SDD (规约驱动开发) 编排器
 
 
 **核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
@@ -89,7 +89,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 **连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
 
-7 个决策阻塞点 + Red Flags 表见 `comate/reference/decision-points.md`。到达任一决策点必须停下用 AskUserQuestion 等待用户选择；其他无歧义流转自动进行，不得中途退出。
+7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
 </IMPORTANT>
 
 ---
@@ -127,7 +127,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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

package/skills/comate/reference/decision-points.md

@@ -32,8 +32,11 @@
 ## 七个决策点
 
 1. **开题产物审视确认**（open）
-   proposal/design/tasks 三件套完成且内容完整后，暂停请用户确认或要求调整。
-   引用：`comate-open` 退出条件。
+   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
+   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
+   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
+   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
+   引用：`comate-open` Step 5。
 
 2. **设计方案确认**（design / brainstorming）
    brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。

package/skills/comate-archive/SKILL.md

@@ -15,7 +15,7 @@ description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 Ope
 ### 0. 入口状态验证
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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

package/skills/comate-build/SKILL.md

@@ -15,7 +15,7 @@ description: "comate 阶段 3：计划与构建。用 /comate-build 调用。制
 ### 0. 入口状态验证
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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

package/skills/comate-design/SKILL.md

@@ -15,7 +15,7 @@ description: "comate 阶段 2：深度设计。用 /comate-design 调用。通
 ### 0. 入口状态验证
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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

package/skills/comate-fix/SKILL.md

@@ -30,7 +30,7 @@ description: "comate 预设路径：快速小改动。跳过 brainstorming 和
 执行链路：open → build → verify → archive。先定位脚本：
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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

package/skills/comate-gate/SKILL.md

@@ -28,7 +28,7 @@ description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。
 ## 脚本定位（单一入口）
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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
@@ -55,7 +55,10 @@ bash "$COMATE" gate <prd> check                # comate-open 建 change 前的
 ### 1. 定位 PRD
 
 - 用户给了路径/编号 → 直接读该文件。
-- 未给 → 用 Glob 列出候选（默认约定 `docs/knowledge-base/requirements/**/PRD-*.md`，若项目无此结构，探测 `docs/**/*.md` 中文件名含 `PRD`/`需求` 的），用 **AskUserQuestion** 让用户选一个。
+- 未给 → 用 Glob 列出候选（默认约定 `docs/knowledge-base/requirements/**/PRD-*.md`，若项目无此结构，探测 `docs/**/*.md` 中文件名含 `PRD`/`需求` 的），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
+  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
+  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
+  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
 - 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。
 - 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
 

package/skills/comate-open/SKILL.md

@@ -34,7 +34,7 @@ openspec/changes/<name>/
 定位 comate 脚本并初始化 `.comate.yaml`：
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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
@@ -97,13 +97,29 @@ bash "$COMATE" state <name> check open
 
 任一文件缺失或为空时，不得进入 Step 5 或执行守卫，必须回创建步骤补充。
 
-### 5. 用户审视确认（决策阻塞点 1）
+### 5. 产物审视（决策阻塞点 1，按来源分类）
 
-三件套完成且完整性检查通过后，**必须使用 AskUserQuestion 工具暂停等待用户确认**。规则见 `comate/reference/decision-points.md` 第 1 条。
+三件套完成且 Step 4 完整性检查通过后，**先按来源分类，再决定是否需要用户输入**。规则见 `comate/reference/decision-points.md` 第 1 条。
 
-以单选题呈现摘要（proposal 问题/目标/范围、design 架构决策/选型、tasks 数量与关键任务）和选项：
+#### 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 条不成立**（范围与映射有偏差）：分歧重新出现。
+
+以上任一情形，**必须使用 AskUserQuestion 工具暂停等待用户确认**。以单选题呈现摘要（proposal 问题/目标/范围、design 架构决策/选型、tasks 数量与关键任务；PRD 偏差场景额外列出偏差点）和选项：
 - 「确认，继续下一阶段」— 执行守卫流转
-- 「需要调整」— 附调整说明，修改后重新请求确认
+- 「需要调整」— 附调整说明（PRD 偏差场景默认建议按映射修正），修改后重新请求确认
 
 ## 退出条件
 

package/skills/comate-verify/SKILL.md

@@ -15,7 +15,7 @@ description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。
 ### 0. 入口状态验证
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+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