@house365/comate 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "skills": "^1.5.21"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
     "test": "node bin/init.test.mjs && bash skills/comate/tests/run.sh",
     "doctor": "cd skills && bash comate/scripts/comate.sh doctor",
     "prepublish-check": "node scripts/prepublish-check.mjs",

package/skills/comate/SKILL.md

@@ -6,7 +6,7 @@ description: "comate —— OpenSpec + Superpowers 规格驱动开发编排器
 # comate —— OpenSpec + Superpowers 规格驱动开发流
 
 
-**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
+**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
 
 ---
 
@@ -18,18 +18,17 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 **Step 0：活跃 change 发现 + 意图探测**
 
-1. 先探测预设；命中 hotfix/tweak 条件则直接调用对应预设 skill，不进入普通 open 分支。
+1. 先探测预设；命中 fix 条件则直接调用 `/comate-fix`，不进入普通 open 分支。
 2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
 
 **预设探测优先级最高**：
-- 用户明确描述 bug 修复/热修 + 满足 hotfix 条件 → 直接调用 `/comate-hotfix`
-- 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 `/comate-tweak`
-- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-intake`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
+- 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整 + 满足 fix 条件 → 直接调用 `/comate-fix`
+- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
 - 无预设命中 → 按下表处理
 
 | 活跃 change | 用户输入 | 行为 |
 |-------------|----------|------|
-| 无 | 指向原始 PRD | → 调用 `/comate-intake` |
+| 无 | 指向原始 PRD | → 调用 `/comate-gate` |
 | 无 | 非预设输入 | → 调用 `/comate-open` |
 | 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
 | 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
@@ -60,7 +59,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
 3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
 4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
-5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`hotfix`→`/comate-hotfix`，`tweak`→`/comate-tweak`，`full`→`/comate-build`
+5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
 6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
 7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
 8. 无活跃 change → 调用 `/comate-open`
@@ -69,9 +68,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 ### 预设升级判定
 
-**hotfix → full**（任一满足即升级）：改动 ≥ 3 文件 / 架构变更（新模块、新接口、新依赖）/ 数据库 schema 变更 / 引入新 public API / 范围超出单一函数模块。
-
-**tweak → full**（任一满足即升级）：改动 ≥ 5 文件 / 跨模块协调 / 需新增 ≥ 5 测试用例 / 配置项增删（非值修改）。
+**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
 
 ### 错误处理速查
 
@@ -101,17 +98,17 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 | 命令 | 阶段 | Owner | 产物 |
 |------|------|-------|------|
-| `/comate-intake` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
+| `/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-hotfix` | 预设 | 双方 | 快速修复（跳过 brainstorming） |
-| `/comate-tweak` | 预设 | 双方 | 小调整（跳过 brainstorming + 完整 plan） |
+| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
+| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
 
 ```
-[原始 PRD] ──→ /comate-intake ──┐  (门禁+拆分，扇出 N 个 change)
+[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
                   (Claude)        │
 /comate                           ▼
   ↓ 自动探测
@@ -119,7 +116,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
   (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
 ```
 
-需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-intake` 门禁再拆分。
+需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
 
 ---
 
@@ -142,7 +139,7 @@ fi
 之后全程复用 `$COMATE`：
 
 ```bash
-bash "$COMATE" state   <name> init <full|hotfix|tweak>
+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>
@@ -167,10 +164,10 @@ bash "$COMATE" doctor
 | 字段 | 含义 |
 |------|------|
 | `schema_version` | 状态文件格式版本（当前 1） |
-| `workflow` | `full` / `hotfix` / `tweak` |
+| `workflow` | `full` / `fix` |
 | `phase` | `open` / `design` / `build` / `verify` / `archive` |
 | `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
-| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；hotfix/tweak 默认 `direct`） |
+| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
 | `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
 | `verify_mode` | `light` / `full`（由 scale 评估写入） |
 | `verify_result` | `pending` / `pass` / `fail` |
@@ -187,7 +184,7 @@ bash "$COMATE" doctor
 - `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
 - `build → verify` 前 `build_mode` 必须已选
 - `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
-- `build_mode: direct` 默认仅 hotfix/tweak；full 流程需 `direct_override: true`
+- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
 - `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
 
 ### 文件结构
@@ -212,7 +209,7 @@ docs/superpowers/                      # Superpowers —— HOW
 
 ### 最佳实践
 
-1. brainstorming 不可跳过（hotfix/tweak 除外）
+1. brainstorming 不可跳过（fix 除外）
 2. delta spec 是活文档，build 阶段随时改，归档时同步
 3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
 4. tasks.md 实时同步，每完成一个任务勾选并提交

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

@@ -55,9 +55,9 @@
    暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
    引用：`comate-verify` Step 3。
 
-6. **预设升级确认**（hotfix / tweak → full）
-   命中升级条件（见各 preset SKILL 的「升级条件」表）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
-   引用：`comate-hotfix` / `comate-tweak`「升级条件」。
+6. **预设升级确认**（fix → full）
+   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
+   引用：`comate-fix`「升级条件」。
 
 7. **构建期范围扩张**（build）
    实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。

package/skills/comate/reference/prerequisites.md

@@ -81,8 +81,7 @@ skills/
 ├── comate-build/SKILL.md   # 阶段 3
 ├── comate-verify/SKILL.md  # 阶段 4
 ├── comate-archive/SKILL.md # 阶段 5
-├── comate-hotfix/SKILL.md  # 预设
-└── comate-tweak/SKILL.md   # 预设
+├── comate-fix/SKILL.md     # 预设(bug + 调整)
 ```
 
 各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。

package/skills/comate/scripts/comate-lib.sh

@@ -4,7 +4,7 @@
 # Single source of truth for: YAML flat read/write, field-order template + enums,
 # hashing, logging, exit-code contract. Other scripts `source` this file.
 #
-# - all YAML logic lives here (Comet duplicated it across 4 scripts).
+# - all YAML logic lives here
 # - .comate.yaml is a declared flat `key: value` subset; validate_flat_yaml enforces it.
 # - yaml_set does full-rewrite + atomic mv + write-back verification.
 # - stable exit codes — 0 OK | 1 BLOCK | 2 USAGE | 3 ENV | 4 CORRUPT.
@@ -81,7 +81,7 @@ readonly COMATE_SCHEMA_VERSION=1
 # --- Enum table: key -> space-separated legal values ---
 declare -A ENUMS=(
   [schema_version]="1"
-  [workflow]="full hotfix tweak"
+  [workflow]="full fix"
   [phase]="open design build verify archive"
   [build_mode]="subagent-driven-development executing-plans direct"
   [tdd_mode]="tdd direct"

package/skills/comate/scripts/comate.sh

@@ -57,7 +57,7 @@ usage_top() {
   cat >&2 <<'EOF'
 Usage: comate.sh <command> ...
 
-  state   <name> init <workflow>            full | hotfix | tweak
+  state   <name> init <workflow>            full | fix
   state   <name> get <field>
   state   <name> set <field> <value>
   state   <name> transition <event>         open-complete|design-complete|build-complete|verify-pass|verify-fail|archived
@@ -102,7 +102,7 @@ state_init() {
   local name="$1" workflow="${2:-}"
   validate_change_name "$name"
   validate_enum workflow "$workflow"
-  [ -n "$workflow" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> init <full|hotfix|tweak>"
+  [ -n "$workflow" ] || die "$COMATE_USAGE" "Usage: comate.sh state <name> init <full|fix>"
 
   local dir yaml
   dir=$(comate_change_dir "$name")
@@ -128,7 +128,7 @@ state_init() {
   # Workflow defaults: full leaves decisions null; presets prefill.
   local build_mode="null" tdd_mode="null" isolation="null" verify_mode="null"
   case "$workflow" in
-    hotfix|tweak)
+    fix)
       build_mode="direct"; tdd_mode="direct"; isolation="branch"; verify_mode="light" ;;
   esac
 
@@ -212,8 +212,8 @@ _require_build_decisions() {
     subagent-driven-development|executing-plans|direct) ;;
     *) die "$COMATE_BLOCK" "ERROR: build_mode must be selected, got '${build_mode:-null}'" ;;
   esac
-  if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ] && [ "$direct_override" != "true" ]; then
-    die "$COMATE_BLOCK" "ERROR: build_mode=direct is only allowed for hotfix/tweak unless direct_override=true"
+  if [ "$build_mode" = "direct" ] && [ "$workflow" != "fix" ] && [ "$direct_override" != "true" ]; then
+    die "$COMATE_BLOCK" "ERROR: build_mode=direct is only allowed for fix unless direct_override=true"
   fi
   case "$tdd_mode" in
     tdd|direct) ;;
@@ -561,7 +561,7 @@ state_recover() {
       _field_status "isolation" "$isolation"
       _field_status "build_mode" "$build_mode"
       _field_status "tdd_mode" "$tdd_mode"
-      if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ]; then
+      if [ "$build_mode" = "direct" ] && [ "$workflow" != "fix" ]; then
         _field_status "direct_override" "$direct_override"
       fi
       echo ""
@@ -790,9 +790,9 @@ _g_build_mode_allowed() {
   build_mode=$(yaml_get "$G_YAML" build_mode)
   direct_override=$(yaml_get "$G_YAML" direct_override)
   [ "$build_mode" != "direct" ] && return 0
-  case "$workflow" in hotfix|tweak) return 0 ;; esac
+  case "$workflow" in fix) return 0 ;; esac
   [ "$direct_override" = "true" ] && return 0
-  echo "build_mode=direct only allowed for hotfix/tweak unless direct_override=true"
+  echo "build_mode=direct only allowed for fix unless direct_override=true"
   return 1
 }
 _g_tdd_mode_selected() {
@@ -1508,7 +1508,7 @@ gate_check() {
   local prd; prd=$(require_prd "$1")
   local gate; gate=$(gate_path_for "$prd")
   if [ ! -f "$gate" ]; then
-    die "$COMATE_BLOCK" "BLOCK: no gate for $prd — run /comate-intake to review the PRD before creating a change"
+    die "$COMATE_BLOCK" "BLOCK: no gate for $prd — run /comate-gate to review the PRD before creating a change"
   fi
   local st; st=$(yaml_get "$gate" gate_status)
   case "$st" in
@@ -1516,7 +1516,7 @@ gate_check() {
     *) die "$COMATE_BLOCK" "BLOCK: gate_status='$st' (not passed) — a change cannot be spawned until the PRD gate passes" ;;
   esac
   if _gate_is_stale "$gate" "$prd"; then
-    die "$COMATE_BLOCK" "BLOCK: PRD changed since it passed the gate (hash mismatch) — re-run /comate-intake to re-gate before spawning a change"
+    die "$COMATE_BLOCK" "BLOCK: PRD changed since it passed the gate (hash mismatch) — re-run /comate-gate to re-gate before spawning a change"
   fi
   log_pass "[GATE] check PASS ($st) — $prd"
   return "$COMATE_OK"

package/skills/comate/tests/comate.bats

@@ -50,21 +50,14 @@ seed_open() {
   [ "$(comate state demo get isolation)" = "null" ]
 }
 
-@test "init hotfix prefills preset defaults" {
-  comate state demo init hotfix
+@test "init fix prefills preset defaults" {
+  comate state demo init fix
   [ "$(comate state demo get build_mode)" = "direct" ]
   [ "$(comate state demo get tdd_mode)" = "direct" ]
   [ "$(comate state demo get isolation)" = "branch" ]
   [ "$(comate state demo get verify_mode)" = "light" ]
 }
 
-@test "init tweak prefills tdd direct" {
-  comate state demo init tweak
-  [ "$(comate state demo get build_mode)" = "direct" ]
-  [ "$(comate state demo get tdd_mode)" = "direct" ]
-  [ "$(comate state demo get isolation)" = "branch" ]
-}
-
 @test "init records base_ref and base_branch" {
   comate state demo init full
   run comate state demo get base_ref
@@ -155,14 +148,14 @@ seed_open() {
   [ "$(comate state demo get phase)" = "design" ]
 }
 
-@test "open-complete routes hotfix to build" {
-  comate state demo init hotfix
+@test "open-complete routes fix to build" {
+  comate state demo init fix
   comate state demo transition open-complete
   [ "$(comate state demo get phase)" = "build" ]
 }
 
 @test "build-complete blocked without isolation" {
-  comate state demo init hotfix
+  comate state demo init fix
   comate state demo transition open-complete
   comate state demo set isolation null >/dev/null
   run comate state demo transition build-complete
@@ -248,7 +241,7 @@ seed_open() {
 # --- build->verify drift ---
 
 @test "verify guard blocks when tasks change after build handoff" {
-  comate state demo init hotfix
+  comate state demo init fix
   local d="openspec/changes/demo"
   printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
   comate guard demo open --apply >/dev/null 2>&1
@@ -422,7 +415,7 @@ SH
 }
 
 @test "build guard blocks when tracked source drifts" {
-  comate state demo init hotfix
+  comate state demo init fix
   local d="openspec/changes/demo"
   printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
   mkdir -p docs/knowledge-base/cb

package/skills/comate-build/SKILL.md

@@ -82,7 +82,7 @@ bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.m
 对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
 
 - **工作区隔离**：`branch` 新建分支（简单快速，≤3 文件推荐）/ `worktree` 独立工作区（需并行或当前分支有未提交工作时推荐）。
-- **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 hotfix）。
+- **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 fix 预设）。
 - **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
 
 用户选择后（连同 3b 已自动应用的维度）写入：
@@ -95,7 +95,7 @@ bash "$COMATE" state <name> set tdd_mode <tdd|direct>
 
 `isolation` 是脚本级硬约束，保持 `null` 时 `build → verify` 的 guard 和 `state transition build-complete` 都会失败。
 
-`build_mode: direct` 默认仅 hotfix/tweak 预设使用。full 流程只有用户明确要求跳过计划执行技能、且已记录显式 override 时才允许：
+`build_mode: direct` 默认仅 fix 预设使用。full 流程只有用户明确要求跳过计划执行技能、且已记录显式 override 时才允许：
 
 ```bash
 bash "$COMATE" state <name> set direct_override true
@@ -109,7 +109,7 @@ bash "$COMATE" state <name> set build_mode direct
 | 选项 | 含义 | 适用场景 |
 |------|------|---------|
 | `tdd` | 每个任务先写失败测试再实现 | 推荐。涉及业务逻辑、新功能、API 的改动 |
-| `direct` | 直接实现，不强制 TDD 流程 | 不需要测试覆盖的改动，或用户选择跳过测试直接写代码。hotfix/tweak 预设默认 `direct` |
+| `direct` | 直接实现，不强制 TDD 流程 | 不需要测试覆盖的改动，或用户选择跳过测试直接写代码。fix 预设默认 `direct` |
 
 `tdd_mode` 是脚本级硬约束，full 流程在离开 build 阶段前必须选择 `tdd` 或 `direct`，否则 guard 和 `state transition build-complete` 都会失败。
 

package/skills/comate-fix/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: comate-fix
+description: "comate 预设路径：快速小改动。跳过 brainstorming 和完整 plan，直接 open → build → verify → archive。覆盖两类：bug 修复（行为修复，不新增 capability）与非 bug 小调整（文案、配置、文档、prompt 局部优化）。"
+---
+
+# comate 预设路径：Fix
+
+快速小改动工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan。
+
+覆盖两种模式，调用时先判定：
+
+| 模式 | 触发 | 独有步骤 | commit 前缀 | 升级阈值 |
+|------|------|----------|-------------|----------|
+| **bug 模式** | 修复已有功能的错误行为 | 根因消除检查（Step 3） | `fix:` | 改动 **3+ 文件** |
+| **调整模式** | 非 bug 的局部优化（文案/配置/文档/prompt） | 无 | `chore:` | 改动 **5+ 文件** |
+
+**模式判定**：改动是为了纠正「跑错了/结果不对」→ bug 模式；只是让已有正确的东西「更好/更新」→ 调整模式。判定影响 Step 3 是否执行、commit 前缀、以及升级阈值，其余流程一致。
+
+**适用条件**（两种模式都必须满足）：
+1. 不新增 capability
+2. 不涉及接口变更或架构调整
+3. 改动范围可预估（bug 模式通常 ≤ 2 文件；调整模式通常 ≤ 3 tasks、≤ 4 文件）
+
+**不适用**：过程中发现需 capability、架构或接口调整时，升级为完整 `/comate`。
+
+---
+
+## 流程（5 阶段）
+
+执行链路：open → build → verify → archive。先定位脚本：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/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
+```
+
+### 1. 快速开启（preset open）
+
+复用 open 能力但用 fix 默认值：不执行 `openspec-explore` 长探索，直接精简创建。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change`。创建精简产物：
+- **bug 模式** — proposal.md（问题 + 根因 + 修复目标）、design.md（1 个修复方案）、tasks.md（修复任务）
+- **调整模式** — proposal.md（动机 + 目标 + 范围）、design.md（简短实现说明）、tasks.md（≤ 3 任务）
+
+**无需 delta spec**（bug 模式除非修复改变已有 spec 验收场景；调整模式一旦需要 delta spec 即升级为完整 `/comate`）。
+
+```bash
+bash "$COMATE" state <name> init fix
+bash "$COMATE" state <name> check open
+bash "$COMATE" guard <name> open --apply
+```
+
+### 2. 直接构建（preset build）
+
+用 fix 默认值 `build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3，则转入 `/comate-build` 的计划与执行方式选择）。
+
+继续或开始修改前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。归因后若发现超出 fix，按「升级条件」处理。
+
+**立即执行：** 按 tasks.md 逐个执行：读未完成任务 → 改代码 → 运行格式化命令 → 运行测试 → 勾选 `- [x]` → 提交。全部完成后显式运行测试和构建命令。
+
+**commit 前缀**：
+- **bug 模式** — `fix: <简述>`
+- **调整模式** — `chore: <简述>`
+
+**delta spec**（仅 bug 模式）：修复影响已有 spec 验收场景时，在 `specs/<capability>/spec.md` 创建仅含 `## MODIFIED Requirements` 的 delta spec。
+
+> 调整模式若未写 plan，仍应在全部任务完成后运行 `bash "$COMATE" handoff <name> build --write` 以记录 tasks 的 impl_hash，再跑 build guard。
+
+### 3. 根因消除检查（仅 bug 模式）
+
+**在运行 build guard 之前**：读 proposal.md 的 bug 与根因，搜索验证问题代码不再存在。根因未消除则回 Step 2 继续（仍在 build，无需状态回退）。
+
+升级条件命中（深层架构问题 / 需额外接口变更）→ 停止 fix，按升级条件阻塞确认。
+
+根因确认消除后，生成 build 交接包并流转：
+
+```bash
+bash "$COMATE" handoff <name> build --write
+bash "$COMATE" guard <name> build --apply
+```
+
+**调整模式跳过此步**，tasks 完成后直接运行上述命令流转。
+
+### 4. 验证（preset verify）
+
+**立即执行：** 使用 Skill 工具加载 `comate-verify`。由其规模评估决定轻量或完整验证。
+- **bug 模式** — 无 delta spec 的小 fix 通常走轻量验证
+- **调整模式** — 必须保持轻量验证条件（≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability）。若规模评估进入完整验证路径，停止并按升级条件确认
+
+验证通过后按其规则记录 `verify_result: pass`。
+
+### 5. 归档（preset archive）
+
+**立即执行：** 使用 Skill 工具加载 `comate-archive`。归档前必须 `verify_result: pass`。有 delta spec（仅 bug 模式可能）则同步到 main spec。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Fix 为**一次性连续执行**。调用后在自有步骤间自动推进，但以下必须暂停（决策点见 `comate/reference/decision-points.md`）：
+1. 命中升级条件（决策点 6）→ AskUserQuestion 确认升级
+2. 任务 > 3 转入 `/comate-build` 时的隔离和执行方式选择（决策点 3）
+3. comate-verify 的验证失败决策（决策点 4）和分支处理决策（决策点 5）
+
+执行顺序：快速开启 → 直接构建 → [bug 模式：根因消除检查] → 验证 → 归档 → 完成。
+</IMPORTANT>
+
+---
+
+## 升级条件（决策阻塞点 6）
+
+满足**任一**即停止 fix 升级为完整 `/comate`：
+
+**bug 模式**：
+
+| 条件 | 说明 |
+|------|------|
+| 改动 **3+ 文件** | 超出单点修复 |
+| 架构变更 | 新模块、新接口、新依赖 |
+| 数据库 schema 变更 | 结构性调整 |
+| 引入新 public API | 修复产生新对外接口 |
+| 范围超出单一函数/模块 | 需多处协调 |
+
+**调整模式**：
+
+| 条件 | 说明 |
+|------|------|
+| 改动 **5+ 文件** | 超出小改动 |
+| 多模块协调 | 跨组件协调 |
+| 需新增 **5+** 测试用例 | 复杂度上升 |
+| 配置项增删 | 非值修改的配置变更 |
+| 需新增 capability | 超出局部优化 |
+| 需 delta spec | 影响已有规格 |
+
+**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先更新 workflow** 再走完整流程：
+
+```bash
+bash "$COMATE" state <name> set workflow full
+```
+
+然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 fix 并报告超出适用范围。
+
+## 退出条件
+
+- **bug 模式** — bug 已修复，测试通过，change 已归档；如有 spec 变更已同步到 main spec
+- **调整模式** — 小改动已完成，测试通过，change 已归档；未新增 capability、架构调整或接口变化
+- **阶段守卫**：build → verify 前 `bash "$COMATE" guard <name> build --apply`，verify → archive 按 `/comate-verify` 规则运行

package/skills/{comate-intake → comate-gate}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: comate-intake
-description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-intake 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
+name: comate-gate
+description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml，门禁未通过禁止建 change。"
 ---
 
-# comate 阶段 0：PRD 门禁与拆分（Intake）
+# comate 阶段 0：PRD 门禁与拆分（Gate）
 
 **定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
 
@@ -172,7 +172,7 @@ bash "$COMATE" gate <prd> pass          # 阻断已清零
 bash "$COMATE" gate <prd> pass --tbd
 ```
 
-`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-intake`。
+`pass` 会硬校验 `blocking_open=0` 且报告非空，并重钉 PRD 哈希——之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-gate`。
 
 ### 6. 逐 Change 初始化（调 comate-open）
 

package/skills/{comate-intake → comate-gate}/scaffold/docs/README.md

@@ -9,7 +9,7 @@
 
 ## architecture/
 
-工程约束的唯一来源,是 `/comate-intake` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
+工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
 
 **占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
 
@@ -24,7 +24,7 @@
 
 需求与第三方对接的长期文档,是 comate 变更流程的上游:
 
-- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-intake` 门禁与拆分后,扇出为 N 个 comate change。
+- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
 - `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
 
 完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。

package/skills/{comate-intake → comate-gate}/scaffold/docs/architecture/README.md

@@ -2,13 +2,13 @@
 
 > ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
 
-本目录是工程约束的**唯一来源**,也是 `/comate-intake` PRD 门禁审阅中「契约对齐架构文档」的事实源。
+本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
 
 ## 为什么需要架构文档
 
 PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
 
-`/comate-intake` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
+`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
 
 ## 建议包含的架构文档
 

package/skills/{comate-intake → comate-gate}/scaffold/docs/knowledge-base/README.md

@@ -12,19 +12,19 @@ docs/knowledge-base/requirements/
        ├─ PRD-001-<功能名>.gate.yaml    门禁状态(机器真相源)          │
        ├─ PRD-REVIEW-PRD-001-<功能名>.md 门禁评审报告(人类可读)       │
        └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
-                                                                    ├─→ /comate-intake (门禁+拆分)
+                                                                    ├─→ /comate-gate (门禁+拆分)
 docs/knowledge-base/integrations/                                   │         ↓
   第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
 ```
 
 ## PRD → comate 流程
 
-comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-intake` 做两件事:
+comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-gate` 做两件事:
 
 1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
 2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
 
-PRD 门禁状态钉在同级 `<PRD名>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-REVIEW-<PRD名>.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 intake。
+PRD 门禁状态钉在同级 `<PRD名>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-REVIEW-<PRD名>.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
 
 扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容——**不再产独立 FRD 文档**,PRD 直接作为 change 的源文档被 `sources track` 钉住。
 

package/skills/comate-gate/scaffold/docs/knowledge-base/integrations/README.md

@@ -0,0 +1,31 @@
+# 第三方服务索引
+
+本文件维护项目正在使用、调研或已下线的第三方服务总览。新增或变更第三方对接时,先更新本索引,再补充对应目录下的对接档案。
+
+> 对接档案由 `/comate-kb-integration` 从官方文档地址自动生成:产出 `<service-id>/README.md` + `api-snapshot.md`,并在本索引追加一行。模板见 `_TEMPLATE/`。
+
+## 状态定义
+
+| 状态 | 含义 |
+|------|------|
+| 调研中 | 尚未进入正式开发,用于可行性、成本、权限、接口能力确认 |
+| 联调中 | 已有代码或环境配置,正在和对方接口联调 |
+| 使用中 | 已上线或被稳定功能依赖 |
+| 暂停使用 | 代码或配置可能仍存在,但当前业务不再主动调用 |
+| 待下线 | 已有替代方案或确定废弃,需要排期清理 |
+| 已下线 | 生产不再依赖,仅保留历史记录 |
+
+## 服务清单
+
+| 服务 | 目录 | 用途 | 状态 | 负责人 | 最近校验 | 关联代码/配置 |
+|------|------|------|------|--------|----------|--------------|
+| <示例:对象存储> | `<service-id>/` | <一句话用途> | 调研中 | <负责人> | <YYYY-MM-DD> | <代码路径/配置键,占位> |
+
+<!-- 每接入或调研一个第三方,追加一行。用 /comate-kb-integration 建档时会自动追加。 -->
+
+## 维护规则
+
+1. 只要 PRD/OpenSpec 变更引入第三方依赖,必须在这里增加或更新一行。
+2. 状态为 `使用中` 的服务,必须有对应的 `<service-id>/README.md`。
+3. 生产问题或第三方接口变化处理完成后,在对应档案的变更历史中追加记录。
+4. **每份档案文件(`README.md` 与 `api-snapshot.md`)的标题正下方必须有「作者 / 更新时间 / 原文档地址」元信息小表**:本目录下都是我方二开文档,须随时可追溯回官方原文。作者默认取建档/最近修改人(git 用户名),更新时间随每次改动刷新(YYYY-MM-DD),原文档地址填官方主 URL。模板见 `_TEMPLATE/`。

package/skills/{comate-intake → comate-gate}/scaffold/docs/knowledge-base/requirements/_templates/PRD.md

@@ -1,7 +1,7 @@
 # PRD-<序号>-<功能名>: <产品标题>
 
 > 复制本文件到对应功能目录 `requirements/<YYYYMMDD-功能名>/`,按命名约定重命名(如 `PRD-001-积分商城.md`,功能名用目录功能名),删除本行与所有 `<...>` 占位说明。
-> PRD = 产品需求文档,回答「做成什么样」。**本 PRD 由 `/comate-intake` 直接读取**:先过质量门禁(审阅+评分+阻断),通过后按依赖/独立性拆成 1 或 N 个 comate change,由 comate 实现——无需再写 FRD。
+> PRD = 产品需求文档,回答「做成什么样」。**本 PRD 由 `/comate-gate` 直接读取**:先过质量门禁(审阅+评分+阻断),通过后按依赖/独立性拆成 1 或 N 个 comate change,由 comate 实现——无需再写 FRD。
 
 | 字段 | 内容 |
 |------|------|
@@ -39,7 +39,7 @@
 
 ### 功能清单
 
-> `/comate-intake` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
+> `/comate-gate` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
 
 | 功能 | 说明 | 优先级 (P0/P1/P2) |
 |------|------|------------------|