@house365/comate 0.1.0 → 0.1.1

package/skills/comate-tweak/SKILL.md

@@ -1,109 +1,109 @@
----
-name: comate-tweak
-description: "comate 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → 轻量 build → 轻量 verify → archive。适用于文案、配置、文档或 prompt 的局部优化。"
----
-
-# comate 预设路径：Tweak
-
-Tweak 是 comate 五阶段能力的预设工作流，复用 open/build/verify/archive，仅跳过 brainstorming 和完整 plan。
-
-适用于非 bug 的小范围变更（文案、配置、文档、prompt 局部优化）。
-
-**适用条件**（必须全部满足）：
-1. 不新增 capability
-2. 不改变架构
-3. 不涉及接口变化
-4. 通常不超过 3 个 tasks、4 个文件
-
-**不适用**：发现需 capability、架构或接口调整时升级为完整 `/comate`。
-
----
-
-## 流程（4 阶段）
-
-执行链路：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 能力但用 tweak 默认值：不执行 `openspec-explore` 长探索。
-
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change`。创建精简产物：proposal.md（动机 + 目标 + 范围）、design.md（简短实现说明）、tasks.md（≤ 3 任务）。**无需 delta spec**（一旦需要 delta spec 即升级为完整 `/comate`）。
-
-```bash
-bash "$COMATE" state <name> init tweak
-bash "$COMATE" state <name> check open
-bash "$COMATE" guard <name> open --apply
-```
-
-### 2. 轻量构建（preset build）
-
-用 tweak 默认值 `build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
-
-继续或开始修改前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。归因后若超出 tweak，按「升级条件」处理。
-
-**立即执行：** 按 tasks.md 逐个执行：改目标文件 → 运行格式化命令 → 运行测试 → 勾选 `- [x]` → 提交（`tweak: <简述>`）。全部完成后显式运行测试和构建命令，然后流转：
-
-```bash
-bash "$COMATE" guard <name> build --apply
-```
-
-> tweak 默认无 plan，build guard 的 impl-context 检查可能要求 `handoff <name> build --write`。tweak 若未写 plan，仍应在全部任务完成后运行 `bash "$COMATE" handoff <name> build --write` 以记录 tasks 的 impl_hash，再跑 build guard。
-
-### 3. 轻量验证（preset verify）
-
-**立即执行：** 使用 Skill 工具加载 `comate-verify`。Tweak 必须保持轻量验证条件（≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability）。若规模评估进入完整验证路径，停止 tweak 按升级条件确认。验证通过后记录 `verify_result: pass`。
-
-### 4. 归档（preset archive）
-
-**立即执行：** 使用 Skill 工具加载 `comate-archive`。归档前必须 `verify_result: pass`。
-
----
-
-## 连续执行模式
-
-<IMPORTANT>
-Tweak 为**一次性连续执行**。调用后在自有步骤间自动推进，但以下必须暂停（决策点见 `comate/reference/decision-points.md`）：
-1. 命中升级条件（决策点 6）→ AskUserQuestion 确认升级
-2. comate-verify 的验证失败决策（决策点 4）和分支处理决策（决策点 5）
-
-执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成。
-</IMPORTANT>
-
----
-
-## 升级条件（决策阻塞点 6）
-
-满足**任一**即停止 tweak 升级为完整 `/comate`：
-
-| 条件 | 说明 |
-|------|------|
-| 改动 **5+ 文件** | 超出小改动 |
-| 多模块协调 | 跨组件协调 |
-| 需新增 **5+** 测试用例 | 复杂度上升 |
-| 配置项增删 | 非值修改的配置变更 |
-| 需新增 capability | 超出局部优化 |
-| 需 delta spec | 影响已有规格 |
-
-**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先更新 workflow** 再走完整流程：
-
-```bash
-bash "$COMATE" state <name> set workflow full
-```
-
-然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 tweak 并报告超出适用范围。
-
-## 退出条件
-
-- 小改动已完成，测试通过，change 已归档
-- 未新增 capability、架构调整或接口变化
-- **阶段守卫**：build → verify 前 `bash "$COMATE" guard <name> build --apply`，verify → archive 按 `/comate-verify` 规则运行
+---
+name: comate-tweak
+description: "comate 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → 轻量 build → 轻量 verify → archive。适用于文案、配置、文档或 prompt 的局部优化。"
+---
+
+# comate 预设路径：Tweak
+
+Tweak 是 comate 五阶段能力的预设工作流，复用 open/build/verify/archive，仅跳过 brainstorming 和完整 plan。
+
+适用于非 bug 的小范围变更（文案、配置、文档、prompt 局部优化）。
+
+**适用条件**（必须全部满足）：
+1. 不新增 capability
+2. 不改变架构
+3. 不涉及接口变化
+4. 通常不超过 3 个 tasks、4 个文件
+
+**不适用**：发现需 capability、架构或接口调整时升级为完整 `/comate`。
+
+---
+
+## 流程（4 阶段）
+
+执行链路：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 能力但用 tweak 默认值：不执行 `openspec-explore` 长探索。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change`。创建精简产物：proposal.md（动机 + 目标 + 范围）、design.md（简短实现说明）、tasks.md（≤ 3 任务）。**无需 delta spec**（一旦需要 delta spec 即升级为完整 `/comate`）。
+
+```bash
+bash "$COMATE" state <name> init tweak
+bash "$COMATE" state <name> check open
+bash "$COMATE" guard <name> open --apply
+```
+
+### 2. 轻量构建（preset build）
+
+用 tweak 默认值 `build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
+
+继续或开始修改前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。归因后若超出 tweak，按「升级条件」处理。
+
+**立即执行：** 按 tasks.md 逐个执行：改目标文件 → 运行格式化命令 → 运行测试 → 勾选 `- [x]` → 提交（`tweak: <简述>`）。全部完成后显式运行测试和构建命令，然后流转：
+
+```bash
+bash "$COMATE" guard <name> build --apply
+```
+
+> tweak 默认无 plan，build guard 的 impl-context 检查可能要求 `handoff <name> build --write`。tweak 若未写 plan，仍应在全部任务完成后运行 `bash "$COMATE" handoff <name> build --write` 以记录 tasks 的 impl_hash，再跑 build guard。
+
+### 3. 轻量验证（preset verify）
+
+**立即执行：** 使用 Skill 工具加载 `comate-verify`。Tweak 必须保持轻量验证条件（≤ 3 tasks、≤ 4 files、无 delta spec、无新 capability）。若规模评估进入完整验证路径，停止 tweak 按升级条件确认。验证通过后记录 `verify_result: pass`。
+
+### 4. 归档（preset archive）
+
+**立即执行：** 使用 Skill 工具加载 `comate-archive`。归档前必须 `verify_result: pass`。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Tweak 为**一次性连续执行**。调用后在自有步骤间自动推进，但以下必须暂停（决策点见 `comate/reference/decision-points.md`）：
+1. 命中升级条件（决策点 6）→ AskUserQuestion 确认升级
+2. comate-verify 的验证失败决策（决策点 4）和分支处理决策（决策点 5）
+
+执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成。
+</IMPORTANT>
+
+---
+
+## 升级条件（决策阻塞点 6）
+
+满足**任一**即停止 tweak 升级为完整 `/comate`：
+
+| 条件 | 说明 |
+|------|------|
+| 改动 **5+ 文件** | 超出小改动 |
+| 多模块协调 | 跨组件协调 |
+| 需新增 **5+** 测试用例 | 复杂度上升 |
+| 配置项增删 | 非值修改的配置变更 |
+| 需新增 capability | 超出局部优化 |
+| 需 delta spec | 影响已有规格 |
+
+**必须使用 AskUserQuestion 工具暂停确认升级**。用户确认后**先更新 workflow** 再走完整流程：
+
+```bash
+bash "$COMATE" state <name> set workflow full
+```
+
+然后**立即加载 `comate-design` skill** 补 Design Doc。用户不确认则停止 tweak 并报告超出适用范围。
+
+## 退出条件
+
+- 小改动已完成，测试通过，change 已归档
+- 未新增 capability、架构调整或接口变化
+- **阶段守卫**：build → verify 前 `bash "$COMATE" guard <name> build --apply`，verify → archive 按 `/comate-verify` 规则运行

package/skills/comate-verify/SKILL.md

@@ -1,130 +1,130 @@
----
-name: comate-verify
-description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。验证实现符合设计，处理开发分支。"
----
-
-# comate 阶段 4：验证与收尾（Verify）
-
-## 前置条件
-
-- 代码已提交（阶段 3 完成）
-- tasks.md 全部任务已完成
-
-## 步骤
-
-### 0. 入口状态验证
-
-```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
-bash "$COMATE" state <name> check verify
-```
-
-**幂等性**：verify 阶段检查可安全重复。若 `verify_result` 已为 `pass` 且 `branch_status` 为 `handled`，直接执行 guard 流转；若为 `pending`，从头验证。
-
-### 1. 改动规模评估
-
-```bash
-bash "$COMATE" state <name> scale
-```
-
-脚本统计任务数、增量规格数、变更文件数，判断 light/full 验证模式并设 `verify_mode`。输出会标注用了哪个基线（plan base-ref / state base_ref / 工作树 diff）。
-
-验证开始前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。verify 阶段特例：
-1. dirty diff 属于当前 change 且涉及实现/测试/tasks/spec/design doc → 不在 verify 直接修复，报告失败项进入 Step 1b
-2. dirty diff 只是 verify 本阶段产物（验证报告草稿、分支处理记录）→ 可继续
-3. dirty diff 已实现但 tasks.md 未勾选 → 视为 build 滞后，报告失败项进入 Step 1b
-
-注意：build 阶段每任务都提交时，工作区 diff 可能低估规模。读 plan 文件头 `base-ref` 用提交区间复核：
-
-```bash
-PLAN=$(bash "$COMATE" state <name> get plan)
-BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref:[[:space:]]*//')
-git diff --stat "$BASE_REF"...HEAD
-```
-
-超轻量阈值（> 4 文件 / 跨模块 / delta spec > 1 capability）则手动设 `bash "$COMATE" state <name> set verify_mode full`。
-
-### 1b. 验证失败决策（决策阻塞点 4）
-
-验证不通过时**必须使用 AskUserQuestion 工具暂停等待用户决定修复或接受偏差**。规则见 `comate/reference/decision-points.md` 第 4 条。不得自动运行 `state transition verify-fail`，也不得自动调 `/comate-build`。
-
-暂停时列出：失败项、是否 CRITICAL（构建失败/测试失败/安全问题/核心验收场景失败）、推荐处理。**不确定性原则**：无法确定严重程度时降级（SUGGESTION > WARNING > CRITICAL）。
-
-用户选择后：
-- **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
-- **逐项处理**：CRITICAL 必须修复；非 CRITICAL 可接受偏差但须在报告记录原因和影响。有任何 CRITICAL 时不允许跳过修复全部接受。
-
-### 2a. 轻量验证（小改动）
-
-规模为「小」时跳过 `openspec-verify-change`，直接执行 5 项检查：
-1. tasks.md 全部 `[x]`
-2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照）
-3. 编译通过（项目构建命令）
-4. 相关测试通过
-5. 无明显安全问题（无硬编码密钥、无新增 unsafe）
-
-**通过标准**：5 项全 OK，无 CRITICAL。不通过 → 进入 Step 1b。
-
-### 2b. 完整验证（大改动）
-
-规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
-
-**Spec 漂移处理**（决策阻塞点 4 的一部分）：若发现 delta spec 与 design doc 矛盾，**必须以单选题 AskUserQuestion 暂停**：
-- A：在 design doc 追加 "Implementation Divergence" 节记录偏差（属 verify 阶段允许产物，写入后不再触发 Step 1b dirty 决策）
-- B：`state transition verify-fail` 然后调 `/comate-build` 由 Spec 增量更新规则更新
-- C：确认偏差可接受继续（归档时 design doc 标记 `superseded-by-main-spec`）
-
-### 3. 收尾（决策阻塞点 5）
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch`。不可用时停止并提示安装。
-
-分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。仅在用户选择且操作完成后才写 `branch_status: handled`。
-
-确认项：全部测试通过、无硬编码密钥或安全问题。
-
-### 4. 记录验证证据
-
-验证报告必须落盘并记录。不要手动设 `verify_result: pass`，通过 guard 自动流转。
-
-若本 change 有源文件追踪（`source_kind: file`），报告须声明本实现对照的知识库文档及其版本，并复核未漂移：
-
-```bash
-bash "$COMATE" sources <name> check          # 0=未漂移 / 1=漂移 / 4=manifest 损坏
-bash "$COMATE" sources <name> list           # 列出对照的文档路径/sha256/ref，贴入报告
-```
-
-`source_kind: conversation` 时跳过（check 为无操作通过）。
-
-```bash
-mkdir -p docs/superpowers/reports
-# 写报告到 docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
-bash "$COMATE" state <name> set verification_report docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
-bash "$COMATE" state <name> set branch_status handled
-```
-
-## 退出条件
-
-- 验证报告通过，分支已处理
-- `verification_report` 指向真实文件，`branch_status: handled`
-- `impl_hash` 与当前 plan+tasks 一致（guard 强制）
-- **阶段守卫**：`bash "$COMATE" guard <name> verify --apply` 全 PASS 后经 `verify-pass` 自动流转到 `phase: archive`
-
-```bash
-bash "$COMATE" guard <name> verify --apply
-```
-
-## 上下文压缩恢复
-
-```bash
-bash "$COMATE" state <name> recover verify
-```
-
-## 自动流转
-
-> **REQUIRED NEXT SKILL：** 调用 `comate-archive` skill 进入归档。
+---
+name: comate-verify
+description: "comate 阶段 4：验证与收尾。用 /comate-verify 调用。验证实现符合设计，处理开发分支。"
+---
+
+# comate 阶段 4：验证与收尾（Verify）
+
+## 前置条件
+
+- 代码已提交（阶段 3 完成）
+- tasks.md 全部任务已完成
+
+## 步骤
+
+### 0. 入口状态验证
+
+```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
+bash "$COMATE" state <name> check verify
+```
+
+**幂等性**：verify 阶段检查可安全重复。若 `verify_result` 已为 `pass` 且 `branch_status` 为 `handled`，直接执行 guard 流转；若为 `pending`，从头验证。
+
+### 1. 改动规模评估
+
+```bash
+bash "$COMATE" state <name> scale
+```
+
+脚本统计任务数、增量规格数、变更文件数，判断 light/full 验证模式并设 `verify_mode`。输出会标注用了哪个基线（plan base-ref / state base_ref / 工作树 diff）。
+
+验证开始前，按 `comate/reference/dirty-worktree.md` 处理未提交改动。verify 阶段特例：
+1. dirty diff 属于当前 change 且涉及实现/测试/tasks/spec/design doc → 不在 verify 直接修复，报告失败项进入 Step 1b
+2. dirty diff 只是 verify 本阶段产物（验证报告草稿、分支处理记录）→ 可继续
+3. dirty diff 已实现但 tasks.md 未勾选 → 视为 build 滞后，报告失败项进入 Step 1b
+
+注意：build 阶段每任务都提交时，工作区 diff 可能低估规模。读 plan 文件头 `base-ref` 用提交区间复核：
+
+```bash
+PLAN=$(bash "$COMATE" state <name> get plan)
+BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref:[[:space:]]*//')
+git diff --stat "$BASE_REF"...HEAD
+```
+
+超轻量阈值（> 4 文件 / 跨模块 / delta spec > 1 capability）则手动设 `bash "$COMATE" state <name> set verify_mode full`。
+
+### 1b. 验证失败决策（决策阻塞点 4）
+
+验证不通过时**必须使用 AskUserQuestion 工具暂停等待用户决定修复或接受偏差**。规则见 `comate/reference/decision-points.md` 第 4 条。不得自动运行 `state transition verify-fail`，也不得自动调 `/comate-build`。
+
+暂停时列出：失败项、是否 CRITICAL（构建失败/测试失败/安全问题/核心验收场景失败）、推荐处理。**不确定性原则**：无法确定严重程度时降级（SUGGESTION > WARNING > CRITICAL）。
+
+用户选择后：
+- **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
+- **逐项处理**：CRITICAL 必须修复；非 CRITICAL 可接受偏差但须在报告记录原因和影响。有任何 CRITICAL 时不允许跳过修复全部接受。
+
+### 2a. 轻量验证（小改动）
+
+规模为「小」时跳过 `openspec-verify-change`，直接执行 5 项检查：
+1. tasks.md 全部 `[x]`
+2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照）
+3. 编译通过（项目构建命令）
+4. 相关测试通过
+5. 无明显安全问题（无硬编码密钥、无新增 unsafe）
+
+**通过标准**：5 项全 OK，无 CRITICAL。不通过 → 进入 Step 1b。
+
+### 2b. 完整验证（大改动）
+
+规模为「大」时**立即使用 Skill 工具加载 `openspec-verify-change`**。检查项：tasks 全勾、实现符合 design.md 高层决策、符合 Design Doc、能力规格场景全通过、proposal 目标满足、delta spec 与 design doc 无矛盾、关联设计文档可定位。
+
+**Spec 漂移处理**（决策阻塞点 4 的一部分）：若发现 delta spec 与 design doc 矛盾，**必须以单选题 AskUserQuestion 暂停**：
+- A：在 design doc 追加 "Implementation Divergence" 节记录偏差（属 verify 阶段允许产物，写入后不再触发 Step 1b dirty 决策）
+- B：`state transition verify-fail` 然后调 `/comate-build` 由 Spec 增量更新规则更新
+- C：确认偏差可接受继续（归档时 design doc 标记 `superseded-by-main-spec`）
+
+### 3. 收尾（决策阻塞点 5）
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch`。不可用时停止并提示安装。
+
+分支处理选项：本地合并 / 推送建 PR / 保持分支 / 丢弃。**必须使用 AskUserQuestion 工具暂停等待用户选择**。规则见 `comate/reference/decision-points.md` 第 5 条。仅在用户选择且操作完成后才写 `branch_status: handled`。
+
+确认项：全部测试通过、无硬编码密钥或安全问题。
+
+### 4. 记录验证证据
+
+验证报告必须落盘并记录。不要手动设 `verify_result: pass`，通过 guard 自动流转。
+
+若本 change 有源文件追踪（`source_kind: file`），报告须声明本实现对照的知识库文档及其版本，并复核未漂移：
+
+```bash
+bash "$COMATE" sources <name> check          # 0=未漂移 / 1=漂移 / 4=manifest 损坏
+bash "$COMATE" sources <name> list           # 列出对照的文档路径/sha256/ref，贴入报告
+```
+
+`source_kind: conversation` 时跳过（check 为无操作通过）。
+
+```bash
+mkdir -p docs/superpowers/reports
+# 写报告到 docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
+bash "$COMATE" state <name> set verification_report docs/superpowers/reports/YYYY-MM-DD-<name>-verify.md
+bash "$COMATE" state <name> set branch_status handled
+```
+
+## 退出条件
+
+- 验证报告通过，分支已处理
+- `verification_report` 指向真实文件，`branch_status: handled`
+- `impl_hash` 与当前 plan+tasks 一致（guard 强制）
+- **阶段守卫**：`bash "$COMATE" guard <name> verify --apply` 全 PASS 后经 `verify-pass` 自动流转到 `phase: archive`
+
+```bash
+bash "$COMATE" guard <name> verify --apply
+```
+
+## 上下文压缩恢复
+
+```bash
+bash "$COMATE" state <name> recover verify
+```
+
+## 自动流转
+
+> **REQUIRED NEXT SKILL：** 调用 `comate-archive` skill 进入归档。