@house365/comate 0.10.2 → 1.0.2-next.0

package/skills/comate-fix/SKILL.md

@@ -1,195 +0,0 @@
----
-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 . ./.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
-```
-
-### 0. 入口状态与断点恢复
-
-`comate-fix` 必须以 `.comate.yaml` 为进度真相源，并且可以从任一已完成步骤继续。已有 fix change 时，**禁止重新创建 change**；先读取：
-
-```bash
-bash "$COMATE" state <name> get workflow
-bash "$COMATE" state <name> get phase
-bash "$COMATE" state <name> get phase_step
-```
-
-- `workflow` 不是 `fix` → 退出本预设，交回 `/comate` 按完整流程路由
-- `phase: open` → 恢复 Step 1；产物齐全时立即执行 open guard，不重新创建产物
-- `phase: build` → 恢复 Step 2，从 tasks.md 第一个未完成任务继续；全部完成时直接执行 build 交接与 guard
-- `phase: verify` → 立即加载 `comate-verify`，不得回跑 open/build
-- `phase: archive` → 立即加载 `comate-archive`
-- `phase_step: fix.upgrade-awaiting` → 恢复升级决策，不执行普通 open/build
-
-每次 guard 使用 `--apply` 成功后，**在同一次调用内**重新读取 `phase`，并立即执行新阶段；除明确的用户决策、guard 失败或停止条件外，不得把“请用户再说继续”作为阶段边界。
-
-### 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
-```
-
-**Step 1 硬出口**：open guard 成功后必须立即确认状态已经进入 build：
-
-```bash
-test "$(bash "$COMATE" state <name> get phase)" = "build"
-```
-
-只有该检查通过才能开始 Step 2 的源码修改。不得在 `phase: open` 时实现或提交代码；guard 失败则修复 open 产物并重跑，不能绕过状态流转。
-
-### 2. 直接构建（preset build）
-
-用 fix 默认值 `build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3，则转入 `/comate-build` 的计划与执行方式选择）。
-
-继续或开始修改前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。归因后若发现超出 fix，按「升级条件」处理。
-
-**立即执行：** 按 tasks.md 逐个执行：读未完成任务 → 改代码 → 运行格式化命令 → 运行测试 → 勾选 `- [x]` → 提交。全部完成后显式运行测试和构建命令。
-
-提交代码不是 Step 2 的结束点。最后一次提交完成后，当前调用必须继续生成 build 交接包、运行 build guard，并确认进入 verify；不得在提交成功处停下或只向用户报告“代码已提交”。
-
-**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
-test "$(bash "$COMATE" state <name> get phase)" = "verify"
-```
-
-**调整模式跳过根因检查，但不跳过交接与流转**；tasks 完成后同样连续运行上述三个命令。
-
-build guard 成功后，必须在**同一次 `/comate-fix` 调用**中立即进入 Step 4。只有 guard 返回非 0 时才停留在 build，并报告具体失败检查。
-
-### 4. 验证（preset verify）
-
-**立即执行：** 使用 Skill 工具加载 `comate-verify`。由其规模评估决定轻量或完整验证。
-- **bug 模式** — 无 delta spec 的小 fix 通常走轻量验证
-- **调整模式** — 必须保持轻量验证条件（≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability）。若规模评估进入完整验证路径，停止并按升级条件确认
-
-验证通过后按其规则记录 `verify_result: pass`。
-
-`comate-verify` 的分支处理属于合法用户决策点；等待用户选择是暂停。用户完成分支处理后，必须立即继续 verify guard，并在 guard 流转到 archive 后同轮加载 `comate-archive`，不得再要求用户发送“继续”。
-
-### 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 模式：根因消除检查] → 验证 → 归档 → 完成。
-
-其中“提交代码”“guard 成功”“用户已完成分支处理”都不是可停点；它们分别触发交接、下一阶段和 verify 收尾。每次恢复也必须按 Step 0 从持久化状态继续，而不是依赖对话中的上一条说明。
-</IMPORTANT>
-
----
-
-## 升级条件（决策阻塞点 6）
-
-满足**任一**即停止 fix 升级为完整 `/comate`：
-
-**bug 模式**：
-
-| 条件 | 说明 |
-|------|------|
-| 改动 **3+ 文件** | 超出单点修复 |
-| 架构变更 | 新模块、新接口、新依赖 |
-| 数据库 schema 变更 | 结构性调整 |
-| 引入新 public API | 修复产生新对外接口 |
-| 范围超出单一函数/模块 | 需多处协调 |
-
-**调整模式**：
-
-| 条件 | 说明 |
-|------|------|
-| 改动 **5+ 文件** | 超出小改动 |
-| 多模块协调 | 跨组件协调 |
-| 需新增 **5+** 测试用例 | 复杂度上升 |
-| 配置项增删 | 非值修改的配置变更 |
-| 需新增 capability | 超出局部优化 |
-| 需 delta spec | 影响已有规格 |
-
-**必须使用 AskUserQuestion 工具暂停确认升级**。提问前记录：
-
-```bash
-bash "$COMATE" state <name> set phase_step fix.upgrade-awaiting
-```
-
-用户确认后使用原子状态转换进入完整流程：
-
-```bash
-bash "$COMATE" state <name> transition fix-upgrade
-```
-
-该转换会原子设置 `workflow: full`、进入 `phase: design`，并清空 fix 预置的 `build_mode` / `tdd_mode` / `isolation` / `verify_mode` 及阶段进度，避免 full build 误沿用 `direct`。然后**立即加载 `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-gate/SKILL.md

@@ -1,316 +0,0 @@
----
-name: comate-gate
-description: "comate 阶段 0：PRD 门禁与拆分。用 /comate-gate 调用。对原始 PRD 做质量审阅+评分+阻断闸门，通过后按依赖/独立性判定拆成 1 或 N 个 change，逐个交给 comate-open。门禁状态钉在 PRD 同级 gate 文件，门禁未通过禁止建 change。"
----
-
-# comate 阶段 0：PRD 门禁与拆分（Gate）
-
-**定位**：comate 五阶段（open→design→build→verify→archive）之前的上游入口。输入一份**原始 PRD**，产出「已过门禁、已拆分」的 N 个 change，各自进入 open 阶段。
-
-**两件事，缺一不可**：
-1. **门禁**：审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零，**禁止建任何 change**。
-2. **拆分**：按依赖/整体性/独立性/规模判定该 PRD 变成几个 change，粒度由用户拍板（AI 只给建议）。
-
----
-
-## 核心铁律
-
-- **门禁状态是可验证的文件真相源**：钉在 PRD 同级的 gate 文件。评审报告是给人看的派生物，**不是**状态源。PRD 命名按本 skill 的前置规范执行，派生文件名由脚本确定性生成。
-- **AskUserQuestion 是真阻塞点**：文字提示、推荐方案、默认值、历史偏好、用户未反对，都**不能**替代明确回答。
-- **只审不改**：门禁只暴露 PRD 问题，不替 PRD 补内容、不替产品拍板。
-- **门禁未通过禁止建 change**：`gate_status ∈ {passed, passed-with-tbd}` 且 PRD 哈希未漂移，才允许 comate-open 建 change（由 `gate check` 硬强制）。
-- **拆分粒度由人定**：AI 给「功能项→change」映射建议，用户确认或改，AI 不拍板。
-- **先发散、后收敛**：门禁不只检查已写出的句子，还要主动扫描 PRD 的隐含假设、替代方向与未覆盖场景；只有涉及产品取舍的项才进入 AskUserQuestion，仓库事实优先查证。
-
----
-
-## 脚本定位（单一入口）
-
-```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
-```
-
-gate 命令族（退出码：`0` 通过 / `1` 阻塞 / `2` 用法 / `3` 环境 / `4` 状态损坏）：
-
-```bash
-bash "$COMATE" gate <prd> review              # 建/刷新 gate.yaml，钉 PRD 哈希，回报告路径
-bash "$COMATE" gate <prd> set <field> <value> # 写 score | blocking_open | gate_status
-bash "$COMATE" gate <prd> pass [--tbd]         # 普通通过要求 0 阻断；--tbd 要求有已授权的未解决阻断
-bash "$COMATE" gate <prd> spawned <change>     # 记录据此 PRD 扇出的 change
-bash "$COMATE" gate <prd> fanout-status [--json] # 查看映射/已创建/待创建进度
-bash "$COMATE" gate <prd> status [--json]      # 查状态（哈希漂移自动判 stale）
-bash "$COMATE" gate <prd> check                # comate-open 建 change 前的前置守卫
-```
-
----
-
-## 步骤
-
-### 1. 定位 PRD
-
-- 用户给了路径/编号 → 直接读该文件。
-- 未给 → 用 Glob 列出候选（默认搜索 `docs/knowledge-base/requirements/**/*.md`，若项目无此结构再探测 `docs/**/*.md`），按命中数分类（对齐 `comate/reference/decision-points.md` 首节三类框架）：
-  - **恰好 1 个候选** → 无 ≥2 有效选项，属"自动处理"：直接选中该 PRD 并**报告选了哪份**，不 AskUserQuestion。
-  - **多个候选** → 属"用户决策"：用 **AskUserQuestion** 让用户选一个。
-  - **0 个候选** → 属"停止条件"：报告在约定路径下未找到 PRD，请用户提供路径或确认 PRD 位置，不发明选项。
-- 读取后重点提取：**功能清单**（各功能项 + 优先级 P0/P1/P2）、**范围（In/Out）**、**第三方依赖**、**验收标准**、文档状态。检查内容是否可审阅即可，不要求 Markdown 标题、表格或模板字段完全一致。
-- 若 PRD 明显未定稿（状态字段非「已定稿」等），用 **AskUserQuestion** 提示可能未冻结并暂停确认；确认前只审阅，不建 gate。
-
-### 1.5 命名规范化（必要前置检查）
-
-PRD 的路径和文件名需要稳定、可追踪，以便 gate 状态和评审报告确定性派生。进入门禁前检查：
-
-| 对象 | 规范 |
-|------|------|
-| 功能目录 | `<YYYYMMDD-功能名>/` |
-| PRD 文件 | 目录内 `PRD-<三位序号>-<功能名>.md` |
-
-发现不规范时，先列出旧名和建议新名，等待用户确认后再用 `git mv` 改名，并同步修正引用。命名规范是流程前置条件；PRD 的正文格式不要求完全套用模板，只需能被审阅并包含可判断的需求内容。
-
-### 1.8 需求澄清扫描（内建 brainstorming，不另建 skill）
-
-命名检查通过后，先初始化 gate 并取得报告路径，再做一次**发散→收敛**扫描：
-
-```bash
-bash "$COMATE" gate <prd> review
-```
-
-该命令只初始化状态、钉 PRD 哈希并返回 `review_report`，不代替语义审阅。扫描目标是发现“PRD 没写但会改变实现或验收”的决策，而不是替用户写 PRD。
-
-若 `review_report` 指向的文件尚不存在，立即按该路径创建 Markdown 文件并写入标题、PRD 路径/哈希和本节扫描表；后续步骤持续追加到同一文件。不得假定 `gate review` 会替 agent 创建报告。
-
-**发散清单（逐项给结论）**：
-
-| 视角 | 至少检查 |
-|------|----------|
-| 问题与价值 | 要解决的用户问题、背景假设、成功/失败的业务结果；区分「交付功能」与「期望结果」 |
-| 用户与场景 | 角色/画像、主次优先级、触发场景、频率、跨角色冲突；匿名/未登录及无权限用户 |
-| 方案与取舍 | 枚举 PRD 中所有实质互斥方向（如同步/异步、客户端/服务端、SQL/NoSQL 等架构级选择）；检查可逆/不可逆决策、明确不做的替代方案及选择理由；若 PRD 未列举至少 2 种候选方案，AI 应主动识别技术路径并要求补充决策依据 |
-| 架构与边界 | 功能模块是否职责单一；模块间接口/契约是否明确；各模块能否不读内部实现就理解用途；是否可独立测试、部署或替换 |
-| 旅程与状态 | 主流程、分支、状态机、重复提交/回退/撤销、跨端或跨会话行为 |
-| 数据与规则 | 输入输出、来源、口径、生命周期、幂等/一致性、隐私分级、保留与删除 |
-| 非功能约束 | 性能（延迟/吞吐）、容量、可用性/SLA、可靠性、扩展性、成本、可观测性、无障碍/国际化（按场景适用） |
-| 依赖与交付 | 第三方/内部依赖、版本兼容、迁移、灰度/回滚、运营与支持责任 |
-| 风险与反例 | 误用、滥用、对抗输入、极值、空值、并发、网络/依赖失败、灾备与合规 |
-
-对每个视角标记 `已证实`、`需查证`、`需产品决策` 或 `不适用（说明理由）`，并记录原文/仓库证据。**不适用也要有理由**，不能用空白跳过。
-
-**收敛规则**：
-
-1. `需查证` 先用 Read/Glob/rg/LSP 核实；找到事实就引用来源，不向用户提问事实。判定门槛是：问题答案若可由仓库/架构/接口等既有事实唯一确定，才属”需查证”。
-2. `需产品决策` 转为阻断问题，必须包含：`ID`、触发假设、至少一个反例/替代方向、影响（范围/行为/数据/验收）及 2–3 个互斥选项。若 PRD 已列 A/B/C 等方向，必须逐一枚举并纳入取舍，不能只挑其中两项。
-   若答案涉及期望行为、阈值、范围、优先级或取舍，或仓库没有唯一事实而存在多个合理答案，一律属”需产品决策”；反例/替代方向须来自 PRD、仓库证据，或明确标注为假设，不得伪造事实。
-3. 每轮最多问 1–3 个高影响决策；**优先设计为多选题**；问题按依赖顺序排列，前一答案会改变后续选项时不得并行提问。**每个问题必须包含 AI 的推荐选项及理由**，便于用户快速决策。
-4. NFR 不按术语逐条机械提问，而按决策包合并：服务目标（性能/容量/SLA/可靠性）、数据保护（安全/隐私/合规）、可运营性（可观测性/成本/灰度/回滚）；仅询问会改变实现或验收的阈值与取舍。
-5. 若发现 4 个以上相互依赖的决策，进入步骤 3 的复杂场景分流，可由用户选择调用 `comate-grill`；否则在本 skill 内用 AskUserQuestion 收敛。步骤 1.8 负责发散发现和生成决策清单，**不会自动调用** `comate-grill`；后者只负责用户选择后的逐项深挖收敛。
-
-**NFR 适用性判定**：生产发布默认检查安全/隐私、可用性/恢复、可观测性和灰度/回滚；用户实时交互检查延迟，批处理/增长场景检查吞吐与容量，处理身份/敏感数据/资金时检查安全隐私合规，对外或多地区产品检查无障碍/国际化及地域合规，依赖外部系统时检查超时/重试/降级。只有存在明确证据表明该能力不进入本次范围或不会改变实现、发布、运营、验收时，才可标 `不适用`，并引用证据；不能用“PRD 未提及”作为不适用理由。**能力适用后，目标/阈值缺失仍是阻断**；不能把“适用但尚未定阈值”标为 N/A。阈值可以在用户明确授权后作为有限 TBD，但必须记录影响与补齐时点。
-
-将扫描结论写入评审报告的“澄清扫描”小节（视角 / 结论 / 证据或假设 / 是否阻断 / 用户决策 ID），并与问题台账保持同一 ID。扫描不会修改 PRD；用户确认的答案只更新报告和 gate 字段，除非用户另行要求补写 PRD。
-
-### 2. 门禁：质量审阅 + 评分（不可跳过）
-
-使用步骤 1.8 已初始化的 gate 和 `review_report`；不要在 PRD 未变化时重复执行 `gate review`。若 PRD 在澄清期间被修改，重新运行该命令以重钉哈希并从本步骤重新审阅。
-
-**逐维度排查**（先完成步骤 1.8 的澄清扫描，再对下表逐条审阅；每条既看「有没有」，也看「清不清楚、能不能落地」）：
-
-| 维度 | 查什么 |
-|------|--------|
-| 逻辑自洽 | 需求前后是否矛盾；流程有无断链；条件/分支是否闭合；功能项间是否冲突或重复 |
-| 架构与边界 | 功能模块是否职责单一；模块间接口是否明确；各模块能否不读内部实现就理解用途；是否可独立测试和部署 |
-| 数据与来源 | 用到的数据是否交代来源（哪张表/哪个接口/哪方提供）；口径/单位/时间范围是否明确 |
-| 边界与范围 | In/Out 是否清晰；极值、空值、并发、权限、异常路径是否覆盖；第三方失败/降级是否提及 |
-| 表述清晰 | 术语是否一致且有定义；有无「尽快/大量/若干」等模糊量词；验收是否可度量 |
-| 完整性 | 目标/背景、功能清单、优先级、验收标准、第三方依赖是否齐全；**有无 TBD/TODO/待定/占位符；是否存在「后续补充」「详见 XX」等延迟决策** |
-| 价值与指标 | 是否定义目标结果、基线、目标值、观测窗口、护栏指标、指标 owner；功能验收通过不等于业务成功 |
-| 用户与场景 | 角色是否完整且有主次；关键场景、未登录/无权限、跨角色协作是否覆盖 |
-| 方案取舍 | 并列方案是否已选定；至少 2 种候选技术路径是否已枚举；选择理由、非目标方案、不可逆决策和回滚边界是否明确 |
-| 非功能与运营 | 性能/容量/SLA/可靠性/安全隐私/合规/可观测性/成本/无障碍国际化及上线回滚责任是否按场景覆盖 |
-
-**每个问题标严重程度三档：**
-- **严重**（扣 15 分）：阻断开发或导致做错方向（逻辑矛盾、关键数据无来源、核心边界缺失、需求自相冲突）。
-- **中**（扣 7 分）：影响实现质量或需返工（口径不清、部分异常路径未覆盖、验收不可度量）。
-- **低**（扣 2 分）：表述瑕疵、术语不统一、可读性问题，不影响方向。
-
-新增澄清项沿用同一扣分规则：未选目标方向、核心角色/优先级或成功判据通常为严重；缺少会改变发布架构或验收的 NFR 为严重，缺少局部阈值/运营细节为中；纯改进建议为低且非阻断。评分与阻断分别表达文档质量和能否安全推进，允许出现“分数较高但仍有阻断”，不得用分数覆盖阻断状态。
-
-**评分**（百分制，从 100 扣，扣到 0 为止）：≥85 优（可拆）、70–84 良（可拆，受影响处标待确认）、<70 待补（建议先补 PRD）。
-
-**先分流再提问**：
-- **仓库事实**（已有架构约定、字段、接口、对接档案）：先用 Read/Glob/rg 核实并引用来源，不丢给用户决定。
-- **产品决策**（目标方向、范围、角色及优先级、成功指标、用户可见行为、状态流转、权限、数据口径、失败处理、NFR 目标、验收规则）：必须用 **AskUserQuestion** 问用户，不得用推荐方案/历史偏好/「待确认」代替确认。
-
-步骤 1.8 发现的 `需产品决策` 与本节审阅发现的问题合并去重；即使 PRD 没有显式错误，只要存在未选定的产品方向、关键角色优先级、成功指标或适用的非功能目标，也要登记为阻断并提问。
-
-**写评审报告（必生成）** 到 `gate review` 回显的 `review_report` 路径（与 PRD 同级，由脚本确定性命名）。内容含：评分 + 评级 + 一句话总评、问题台账表（`ID` / 维度 / 严重程度 / 原文依据 / 影响章节 / 是否阻断 / 建议 / 产品回填列）、逐条问题。若无问题，明确写「审阅通过，未发现阻断项」。
-
-**阻断规则**：影响目标方向、目标用户/角色优先级、成功判据、范围、用户行为、状态流转、数据契约、权限、异常处理、适用的非功能目标或验收标准的问题标「阻断」。泛化改进建议只有在“不确认也不会改变实现、发布或验收”时才可记为非阻断。把当前未关闭的阻断问题数写入 gate：
-
-```bash
-bash "$COMATE" gate <prd> set score <分数>
-bash "$COMATE" gate <prd> set blocking_open <未关闭阻断数>
-```
-
-### 3. 阻断闸门（AskUserQuestion）
-
-**若 `blocking_open > 0`**，先判定复杂度（阻断既包括传统审阅问题，也包括步骤 1.8 发现的未决策项）：
-
-- **阻断数 ≤ 3 且无明显依赖链** → 默认模式（批量+分轮处理）
-- **阻断数 > 3 或存在决策依赖链** → 提供深度澄清选项
-
-#### 默认模式（阻断数 ≤ 3）
-
-用 **AskUserQuestion** 暂停，给三选项（文字提示不能替代工具等待）：
-1. **先补 PRD** — 让用户/产品补齐，补后回步骤 2 重新审阅（`gate review` 会因 PRD 改动重钉哈希、状态回 reviewing）。
-2. **授权带 TBD 继续** — 用户显式授权。此时后续 change 的 proposal/design 受影响处必须标 **「⚠ 待确认」** 并引用评审报告。
-3. **暂停** — 停在此，不建 change。
-
-对每轮最多 1–3 个高影响决策提问；每个问题给 `ID`、原文依据、影响、2–3 个互斥选项、推荐项及后果，允许自定义答案。用户回答后更新报告台账、重算 `blocking_open`，直到清零或用户选 2。**清零或授权后，立即继续执行步骤 4（拆分判定）。**
-
-`passed-with-tbd` 不是默认的“先做再说”：目标方向、核心角色/优先级、业务成功判据等不可逆或会导致做错方向的阻断，默认应先补齐或深度澄清；只有用户针对这些 ID 明确接受风险、指定补齐责任人与时点，才可授权带 TBD。性能等可后置阈值也必须标注影响、验证方式和截止时点。
-
-#### 复杂场景模式（阻断数 > 3 或有依赖链）
-
-用 **AskUserQuestion** 暂停，给四选项：
-1. **先补 PRD** — 同上。
-2. **授权带 TBD 继续** — 同上。
-3. **深度澄清模式** — 调用 `comate-grill` skill 逐决策点穷追式澄清。适合复杂 PRD，更彻底但耗时更长。
-4. **暂停** — 停在此，不建 change。
-
-**若用户选 3（深度澄清）**：
-
-1. **立即执行**：使用 Skill 工具加载 `comate-grill`，传入话题和阻断问题清单：
-
-   ```markdown
-   话题：PRD 门禁阻断问题清单
-   问题列表：
-   [逐条列出所有 blocking_open > 0 的问题，每条含：ID、问题描述、原文依据、影响范围、当前歧义]
-   ```
-
-2. `comate-grill` 会逐个决策点深挖，每个问题附推荐答案，等用户确认后进入下一个，直到所有分支清晰。
-
-3. `comate-grill` 完成后，**立即**更新评审报告中的“澄清扫描”和问题台账，重算 `blocking_open`。若依然未清零，回到本步骤 3 再次判定（通常经过深度澄清后会清零）。
-
-4. **`blocking_open` 清零后，立即继续执行步骤 4（拆分判定）。**
-
-#### 步骤 3 出口条件（自动流转到步骤 4）
-
-**只有满足以下条件之一，才自动进入步骤 4**：
-- `blocking_open` 已清零（默认模式或深度澄清模式完成后）
-- 用户选择"授权带 TBD 继续"（选项 2）
-
-**满足条件后，必须立即继续执行步骤 4-7，不得停在步骤 3。** 用户选"先补 PRD"（选项 1）时回步骤 2；选"暂停"（选项 3/4）时停止整个 skill。
-
-### 4. 拆分判定（必须 AskUserQuestion 问人）
-
-列出 PRD 功能清单各功能项及优先级，AI 按下列维度**给拆分建议**（不拍板）：
-
-- **依赖关系**：前后依赖的功能项归**同一** change。
-- **整体性**：共同构成一个完整用户价值的功能簇归**同一** change。
-- **独立性**：互不依赖、可并行实现的功能项拆成**独立** change。
-- **规模**：功能点少（≤3）且简单 → **1 个** change 即可；复杂多点（>5）且可切分 → **多个** change。
-
-产出「功能项 → change」映射建议，例如：
-
-```
-建议拆分：
-- Change A「核心登录流」：功能项 1、2、3（有依赖链，整体交付）
-- Change B「运营配置」：功能项 4、5（独立，可与 A 并行）
-- Change C「数据报表」：功能项 6（独立后置）
-```
-
-用 **AskUserQuestion**（可多选/自定义）让用户确认：
-- 哪些功能项归哪个 change（显示建议映射）；
-- 是一功能项一 change 还是合并；
-- 各 change 命名（默认取主功能项名，用户可改）。
-
-**映射确认前不得建任何 change。** 确认后：
-
-1. **立即持久化映射到 gate.yaml**，使其成为机器可验证事实：
-
-```bash
-# changes_map 格式：changeA:功能项1,2,3;changeB:功能项4,5
-bash "$COMATE" gate <prd> set changes_map "changeA:功能项1,2,3;changeB:功能项4,5"
-```
-
-2. 用 **TaskCreate** 把每个待建 change 建成任务项。
-
-3. 多 change 时，在 PRD 同目录建 `CHANGES-MAP.md` 作为人类可读备份，内容与 `changes_map` 字段一致。
-
-### 5. 通过门禁
-
-映射与 `blocking_open` 都就绪后，置门禁通过：
-
-```bash
-bash "$COMATE" gate <prd> pass          # 阻断已清零
-# 或用户授权带 TBD：
-bash "$COMATE" gate <prd> pass --tbd
-```
-
-`pass` 会硬校验评分为 0–100、`changes_map` 非空、报告非空；普通 pass 要求 `blocking_open=0`，`--tbd` 则要求存在至少 1 个已记录且经用户明确接受的未解决阻断项。之后 PRD 再被改，哈希漂移会使门禁 `stale`，须重跑 `/comate-gate`。
-
-### 6. 逐 Change 初始化（调 comate-open）
-
-这是一个可恢复的扇出循环，不是一次性只执行首项的提示。每次进入本步骤先运行：
-
-```bash
-bash "$COMATE" gate <prd路径> fanout-status --json
-```
-
-只处理返回 JSON 中 `missing` 列出的 change；不要重新处理 `spawned` 中已有的 change。每创建一个 change 后立即运行 `gate spawned`，再重新运行 `fanout-status`，直到 `complete: true`。如果本轮因上下文、用户决策或子 skill 中断，下一轮必须从 `fanout-status` 恢复，不能根据对话记忆猜测剩余项。
-
-对 `missing` 里的每个 change，逐个调用 comate-open。**每次都在 change 描述里点明**：本 change 承接 PRD 的哪些功能项、范围边界、以及（多 change 时）相邻职责归哪个 change（In/Out 显式互引，防重复防遗漏）。若同名目录或 `.comate.yaml` 已存在，视为中断恢复：让 comate-open 复用现有状态、补齐缺失产物和源追踪后登记，不得重复执行 `state init`。
-
-**立即执行**：用 Skill 工具加载 `comate-open`，传入 change 名与来源 PRD，并明确使用“gate 扇出骨架模式”。该模式创建/补齐并校验当前 change 的 `.openspec.yaml`、open 三件套、`.comate.yaml` 和 PRD 源追踪，最后登记 `gate spawned` 并保持 `phase: open` 返回本 gate 循环；不得在同一次 gate 调用中自动进入该 change 的 design/build。
-
-comate-open 内部会：
-- 先跑 `gate check <prd>` 前置守卫（未通过则阻断）；
-- 生成 proposal.md（范围/目标/非目标承接该 change 的功能项，不脱离 PRD 另起炉灶）；
-- `sources track <prd>` 钉住 PRD 为源（`source_kind=file`）；
-- design.md / tasks.md 由后续 comate-design 细化。
-
-每建成一个，记录到门禁（目录已存在后才能登记）：
-
-```bash
-bash "$COMATE" gate <prd> spawned <change-name>
-```
-
-登记后继续处理 `fanout-status` 的 `missing` 列表。只有 `complete: true` 才能进入步骤 7，并且收尾报告中的“已创建 N 个 change”必须等于映射项数量；部分完成必须明确报告剩余项，不能宣称扇出完成。
-
-若门禁是 `passed-with-tbd`，在该 change 的 proposal/design 受影响处标 **「⚠ 待确认」** 并引用评审报告。
-
-### 7. 收尾
-
-展示：
-- PRD 审阅评分 + 评级、阻断问题关闭情况；
-- 评审报告路径、gate.yaml 路径与最终 `gate_status`；
-- 拆分映射（功能项 → N 个 change）；
-- 已建的 change 列表（名称 + 承接功能项 + 是否带 ⚠ TBD）；
-- 扇出完整性（`fanout-status` 的 expected/spawned/missing/invalid）；
-- 待用户补的字段（如技术负责人）。
-
-提示：「已过门禁并创建 N 个 change。对每个 change 调用 `/comate` 继续 design→build→verify→archive。」
-
----
-
-## Guardrails
-
-- 生成 change 前必先过门禁并评分（步骤 2），不可跳过；审阅只暴露问题、不替 PRD 补内容。
-- 评审报告**必生成**，不再询问是否生成。
-- 门禁状态以 `<PRD>.gate.yaml` 为唯一真相源；报告是人类可读派生物，二者冲突以 gate.yaml 为准。
-- 影响目标方向、目标用户/角色优先级、成功判据、范围、用户行为、状态流转、数据契约、权限、异常处理、适用的非功能目标或验收标准的歧义必须逐项确认；未清零只能停在 reviewing/blocked，或经用户授权走 passed-with-tbd（带 ⚠ 标记）。
-- 必须完成步骤 1.8 的全部视角并在报告中留下结论；不能因为 PRD 文字自洽就跳过隐含假设、替代方向、角色、成功指标或适用的非功能约束。
-- AskUserQuestion 是真实阻塞点：文字输出/推荐/默认值/历史选择/用户未反对都不能替代明确回答。
-- 拆分粒度（1 PRD → 几个 change）由用户定，AI 只给建议不拍板。
-- 每个 change 承接 PRD 对应功能项，不另起炉灶；范围/依赖/验收与 PRD 对齐。
-- 多 change 时在各 change 的 In/Out Scope 显式互引边界职责归属。
-- 扇出必须以 `gate fanout-status` 为持久化进度真相；`TaskCreate` 仅作展示，不得替代 gate.yaml 状态。
-- 门禁通过后 PRD 若被改（哈希漂移），gate 转 stale，禁止再扇出 change，须重跑本 skill。
-- 契约以项目架构文档（如 `docs/architecture/`，若存在）为事实源，change 里点名遵循了哪条，不硬编码具体值、不自造。
-- 不写应用代码——本 skill 止于「过门禁 + 拆分 + 建 change 骨架」，实现由后续 comate 阶段驱动。

package/skills/comate-gate/scaffold/docs/README.md

@@ -1,36 +0,0 @@
-# docs 文档目录说明
-
-本目录承载项目的长期文档,与代码同仓库、同评审、同版本管理。按用途分为以下几类:
-
-| 子目录 | 定位 | 说明 |
-|--------|------|------|
-| `architecture/` | 架构规范 | 前后端分层、依赖规则、命名、错误码等工程铁律,以仓库**当前实现**为准 |
-| `knowledge-base/` | 知识库 | 上游需求(PRD)与横向(第三方对接)的长期文档,详见其内 `README.md` |
-
-## architecture/
-
-工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
-
-**占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
-
-- 后端分层 / 依赖 / DTO / 错误码 / 命名。
-- 前端分层 / API / store / 路由 / 命名。
-- 工程原则与铁律。
-
-> 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下,也不参与 `openspec validate --strict`。
-> 调整架构相关代码时,必须同步更新对应文档。
-
-## knowledge-base/
-
-需求与第三方对接的长期文档,是 comate 变更流程的上游:
-
-- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
-- `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
-
-完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。
-
-## 与 openspec/ 的边界
-
-- `docs/` 放**长期文档**(架构规范、需求、对接档案)。
-- `openspec/` 放**变更驱动的规格**:`changes/`(一次性变更)与 `specs/`(能力沉淀)。
-- 两者通过 PRD 门禁状态(`<PRD>.gate.yaml`)与 change 的 `sources.manifest` 打通。

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

@@ -1,47 +0,0 @@
-# 知识库 (Knowledge Base)
-
-本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
-
-## 文档体系与交接
-
-```
-docs/knowledge-base/requirements/
-  ├─ _templates/              PRD 模板
-  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
-       ├─ PRD-001-<功能名>.md          产品需求文档                  │
-       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
-       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
-       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
-                                                                    ├─→ /comate-gate (门禁+拆分)
-docs/knowledge-base/integrations/                                   │         ↓
-  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
-```
-
-## PRD → comate 流程
-
-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.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
-
-扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容，PRD 直接作为 change 的源文档被 `sources track` 钉住。
-
-## 命名约定
-
-- 功能目录：`<YYYYMMDD-功能名>/`
-- PRD：目录内 `PRD-<三位序号>-<功能名>.md`
-- gate 和评审报告：由脚本根据 PRD 路径自动生成，不手工命名。
-
-## 横向 (integrations/)
-
-- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
-- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
-- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
-
-## 溯源与可追溯
-
-- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
-- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
-- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。