@house365/comate 0.7.0 → 0.9.0

package/skills/comate/reference/dirty-worktree.md

@@ -1,58 +1,58 @@
-# Dirty Worktree 协议
-
-规范路径：`comate/reference/dirty-worktree.md`
-
-本协议由所有涉及代码修改的 comate 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。
-
-## 1. 检查步骤
-
-继续或开始修改前，必须先运行以下命令：
-
-```bash
-git status --short
-git diff --stat
-git diff --cached --stat
-git ls-files --others --exclude-standard
-```
-
-必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
-
-## 2. 核心规则
-
-- 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源。
-- dirty worktree 只代表代码事实，不会自动推进 `.comate.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 comate 状态。
-
-## 3. 归因分类
-
-将 dirty diff 分为三类：
-
-1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。纳入当前任务继续，不重复改同一处。
-2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃。
-3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段。
-
-## 4. 常见处理模式
-
-### 已实现但 tasks.md 未勾选
-
-先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。
-
-### 暗示计划或范围已变化
-
-按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。
-
-### 模糊恢复意图
-
-用户说“继续”“接着跑”“我改了一点”“刚才不满意”“重新弄”“代码动过”“先按现在的来”等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。
-
-### open/design 阶段出现代码改动
-
-若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段：
-
-- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard。
-- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃。
-- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify。
-
-## 5. 禁令
-
-- 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动。
-- 禁止在 dirty diff 未解释清楚时判定验证通过。
+# Dirty Worktree 协议
+
+规范路径：`comate/reference/dirty-worktree.md`
+
+本协议由所有涉及代码修改的 comate 子 skill 共享。当 agent 恢复上下文或继续执行时，必须按本协议处理未提交的工作区改动。
+
+## 1. 检查步骤
+
+继续或开始修改前，必须先运行以下命令：
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
+
+## 2. 核心规则
+
+- 用户可能不会说明自己改了哪里。只要存在 dirty worktree（包括 Git 状态里显示为 `??` 的新建文件），就先假设改动可能来自用户或混合来源。
+- dirty worktree 只代表代码事实，不会自动推进 `.comate.yaml` 的 `phase` 或勾选 `tasks.md`；只有完成归因、验证、同步必要文档，并通过对应阶段 guard 后，才允许推进 comate 状态。
+
+## 3. 归因分类
+
+将 dirty diff 分为三类：
+
+1. **属于当前 change**：文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。纳入当前任务继续，不重复改同一处。
+2. **不属于当前 change**：文件或内容与当前目标无关。暂停并询问用户：并入当前 change、拆成新 change、保留不处理，或明确授权丢弃。
+3. **来源不确定**：无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据，不继续推进阶段。
+
+## 4. 常见处理模式
+
+### 已实现但 tasks.md 未勾选
+
+先验证实现（运行构建和测试），通过后补勾任务。不要因为任务未勾选就重做一遍，也不要因为状态文件滞后而忽略代码事实。若当前子 skill 定义了阶段特例，以子 skill 为准。
+
+### 暗示计划或范围已变化
+
+按当前子 skill 的升级、增量更新或回退规则处理，本协议不重复阶段特例。
+
+### 模糊恢复意图
+
+用户说“继续”“接着跑”“我改了一点”“刚才不满意”“重新弄”“代码动过”“先按现在的来”等模糊恢复意图时，按本协议处理。不要要求用户先回忆具体改了哪里。
+
+### open/design 阶段出现代码改动
+
+若当前仍处于 `open` 或 `design`，但 dirty worktree 已经包含代码改动，先按本协议归因，不要直接推进阶段：
+
+- 属于当前 change 的改动：作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中；进入 build 前仍需完成对应阶段 guard。
+- 不属于当前 change 或来源不确定：暂停询问用户是并入当前 change、拆成新 change、保留不处理，还是明确授权丢弃。
+- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify。
+
+## 5. 禁令
+
+- 禁止在未理解 dirty diff 来源时覆盖、回滚、格式化重写或忽略用户改动。
+- 禁止在 dirty diff 未解释清楚时判定验证通过。

package/skills/comate/reference/prerequisites.md

@@ -1,89 +1,89 @@
-# 前置依赖检查清单（prerequisites）
-
-规范路径：`comate/reference/prerequisites.md`
-
-`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
-
-> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
-
-## 1. 运行环境
-
-| 依赖 | 要求 | 检查 | 缺失处理 |
-|------|------|------|----------|
-| bash | ≥ 4（需要关联数组） | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2，需 `brew install bash` |
-| git | 任意近代版本 | `git --version` | 安装 git |
-| sha256 工具 | `sha256sum` 或 `shasum` 至少其一 | `command -v sha256sum shasum` | Linux 装 coreutils；macOS 自带 `shasum`（perl） |
-| LF 换行 | 所有 `.sh` 必须是 LF | `doctor` 会检测 CRLF | 仓库已带 `.gitattributes` 强制 `eol=lf`；若被改坏，用 `dos2unix` 或重新 checkout |
-
-## 2. OpenSpec（WHAT 侧）
-
-负责 proposal / spec 生命周期 / 归档。comate 的 open / archive 阶段依赖它。
-
-安装：
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
-
-```bash
-openspec init . --tools none
-```
-
-自查：
-
-```bash
-openspec --version
-openspec list --json    # 列出活跃 change，应能正常返回
-```
-
-comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。确认这些 skill 在你的平台 skills 目录中可用。
-
-## 3. Superpowers（HOW 侧）
-
-负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
-
-`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
-
-- `superpowers:brainstorming`
-- `superpowers:writing-plans`
-- `superpowers:subagent-driven-development`
-- `superpowers:executing-plans`
-- `superpowers:test-driven-development`
-- `superpowers:using-git-worktrees`
-- `superpowers:finishing-a-development-branch`
-
-自查：在 agent 中尝试加载 `superpowers:brainstorming`。若不可用，按你平台的安装说明补装。**任一 Superpowers 步骤不可用时，对应阶段必须停止并提示安装，不得用普通对话替代该步骤。**
-
-## 4. comate 自身
-
-comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
-
-采用**平铺布局**——每个 phase 是顶层 skill 目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，平铺是共同可用的最小公倍数：
-
-```
-skills/
-├── comate/                 # 主入口 + 共享资源
-│   ├── SKILL.md            #   /comate：探测并分派
-│   ├── reference/
-│   │   ├── dirty-worktree.md
-│   │   ├── decision-points.md
-│   │   └── prerequisites.md
-│   ├── scripts/
-│   │   ├── comate-lib.sh
-│   │   └── comate.sh
-│   └── tests/
-│       ├── comate.bats
-│       └── run.sh
-├── comate-open/SKILL.md    # 阶段 1
-├── comate-design/SKILL.md  # 阶段 2
-├── comate-build/SKILL.md   # 阶段 3
-├── comate-verify/SKILL.md  # 阶段 4
-├── comate-archive/SKILL.md # 阶段 5
-├── comate-fix/SKILL.md     # 预设(bug + 调整)
-```
-
-各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。
-
-`doctor` 会校验 `comate/scripts/` 下文件齐全且为 LF。
+# 前置依赖检查清单（prerequisites）
+
+规范路径：`comate/reference/prerequisites.md`
+
+`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
+
+> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
+
+## 1. 运行环境
+
+| 依赖 | 要求 | 检查 | 缺失处理 |
+|------|------|------|----------|
+| bash | ≥ 4（需要关联数组） | `bash --version` | Windows 用 Git Bash / WSL；macOS 自带 3.2，需 `brew install bash` |
+| git | 任意近代版本 | `git --version` | 安装 git |
+| sha256 工具 | `sha256sum` 或 `shasum` 至少其一 | `command -v sha256sum shasum` | Linux 装 coreutils；macOS 自带 `shasum`（perl） |
+| LF 换行 | 所有 `.sh` 必须是 LF | `doctor` 会检测 CRLF | 仓库已带 `.gitattributes` 强制 `eol=lf`；若被改坏，用 `dos2unix` 或重新 checkout |
+
+## 2. OpenSpec（WHAT 侧）
+
+负责 proposal / spec 生命周期 / 归档。comate 的 open / archive 阶段依赖它。
+
+安装：
+
+```bash
+npm install -g @fission-ai/openspec@latest
+```
+
+初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
+
+```bash
+openspec init . --tools none
+```
+
+自查：
+
+```bash
+openspec --version
+openspec list --json    # 列出活跃 change，应能正常返回
+```
+
+comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore`、`openspec-new-change`、`openspec-propose`、`openspec-verify-change`。确认这些 skill 在你的平台 skills 目录中可用。
+
+## 3. Superpowers（HOW 侧）
+
+负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
+
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
+
+- `superpowers:brainstorming`
+- `superpowers:writing-plans`
+- `superpowers:subagent-driven-development`
+- `superpowers:executing-plans`
+- `superpowers:test-driven-development`
+- `superpowers:using-git-worktrees`
+- `superpowers:finishing-a-development-branch`
+
+自查：在 agent 中尝试加载 `superpowers:brainstorming`。若不可用，按你平台的安装说明补装。**任一 Superpowers 步骤不可用时，对应阶段必须停止并提示安装，不得用普通对话替代该步骤。**
+
+## 4. comate 自身
+
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+采用**平铺布局**——每个 phase 是顶层 skill 目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，平铺是共同可用的最小公倍数：
+
+```
+skills/
+├── comate/                 # 主入口 + 共享资源
+│   ├── SKILL.md            #   /comate：探测并分派
+│   ├── reference/
+│   │   ├── dirty-worktree.md
+│   │   ├── decision-points.md
+│   │   └── prerequisites.md
+│   ├── scripts/
+│   │   ├── comate-lib.sh
+│   │   └── comate.sh
+│   └── tests/
+│       ├── comate.bats
+│       └── run.sh
+├── comate-open/SKILL.md    # 阶段 1
+├── comate-design/SKILL.md  # 阶段 2
+├── comate-build/SKILL.md   # 阶段 3
+├── comate-verify/SKILL.md  # 阶段 4
+├── comate-archive/SKILL.md # 阶段 5
+├── comate-fix/SKILL.md     # 预设(bug + 调整)
+```
+
+各 phase skill 通过 `*/comate/scripts/comate.sh` glob 定位脚本，共享 `comate/reference/*` 和 `comate/scripts/*`。若目标平台支持嵌套 skill 发现，也可改回 `comate/<phase>/SKILL.md` 子目录布局，纯命名调整，不影响脚本。
+
+`doctor` 会校验 `comate/scripts/` 下文件齐全且为 LF。

package/skills/comate-archive/SKILL.md

@@ -1,63 +1,63 @@
----
-name: comate-archive
-description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
----
-
-# comate 阶段 5：归档（Archive）
-
-## 前置条件
-
-- 验证已通过（阶段 4 完成），分支已处理
-- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
-
-## 步骤
-
-### 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 archive
-```
-
-### 1. 执行归档
-
-```bash
-bash "$COMATE" archive "<name>"
-```
-
-脚本自动完成：
-1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
-2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
-3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
-4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
-5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
-6. 通过 `state transition <archive-name> archived` 设 `archived: true`
-7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
-
-非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
-
-需预览不实际执行：加 `--dry-run`。
-
-### 2. 生命周期闭环
-
-```
-brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
-```
-
-## 退出条件
-
-- 归档脚本退出码 0
-- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
-- 归档后 `.comate.yaml` 中 `archived: true`
-
-归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
-
-## 完成
-
-comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。
+---
+name: comate-archive
+description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
+---
+
+# comate 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成），分支已处理
+- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证
+
+```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
+bash "$COMATE" state <name> check archive
+```
+
+### 1. 执行归档
+
+```bash
+bash "$COMATE" archive "<name>"
+```
+
+脚本自动完成：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
+3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
+4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
+5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
+6. 通过 `state transition <archive-name> archived` 设 `archived: true`
+7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
+
+非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
+
+需预览不实际执行：加 `--dry-run`。
+
+### 2. 生命周期闭环
+
+```
+brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本退出码 0
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
+- 归档后 `.comate.yaml` 中 `archived: true`
+
+归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
+
+## 完成
+
+comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。