@house365/comate 0.2.7 → 0.2.8

package/README.md

@@ -41,6 +41,15 @@ skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`
 
 装完输入 `/comate` 开始使用，`comate doctor` 可自检。
 
+## 更新
+
+```bash
+npm install -g @house365/comate@latest
+cd your-project && comate init
+```
+
+两步都要跑：`npm` 只换 CLI 本身，skills 是 `comate init` 铺到 `~/.agents/skills` 的，npm 不管。这里的 `@latest` 不能省——本地已装时，不带 tag 的 `npm install -g` 可能认为已满足而不去 registry 取新版。
+
 ## 用法
 
 输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。

package/docs/COMATE_MANUAL.md

@@ -64,6 +64,13 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 
 ## 2. 安装与前置条件
 
+```bash
+npm install -g @house365/comate
+cd your-project && comate init
+```
+
+`init` 会装好下面 2.2–2.4 的全部内容。本节余下部分用于排查：init 报某项失败时，对照确认要装什么、怎么自查。
+
 ### 2.1 运行环境
 
 | 依赖 | 要求 | 检查方式 |
@@ -79,7 +86,9 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 
 ```bash
 npm install -g @fission-ai/openspec@latest
-cd <project-root> && openspec init
+# --tools 必填：openspec 靠探测已有 agent 配置目录决定写哪些 tool 文件，
+# 干净项目里探测不到会直接报 No tools detected 退出
+cd <project-root> && openspec init . --tools none
 openspec list --json  # 验证安装
 ```
 
@@ -89,7 +98,7 @@ comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explo
 
 处理技术设计/规划/执行/收尾。comate 的 design、build 和 verify 阶段依赖它。
 
-Superpowers 是一个技能集。按你的平台约定安装。确认以下技能可加载：
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。确认以下技能可加载：
 
 - `superpowers:brainstorming`
 - `superpowers:writing-plans`
@@ -102,7 +111,9 @@ Superpowers 是一个技能集。按你的平台约定安装。确认以下技
 
 ### 2.4 comate 本身
 
-分发方式 = 将完整的 comate 技能目录复制到你的平台技能目录。本项目（Claude Code 插件）使用扁平布局：
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
 
 ```
 skills/
@@ -183,8 +194,8 @@ skills/
 
 | 场景 | 处理方式 |
 |----------|----------|
-| `openspec list --json` 失败 | 检查 openspec 安装，提示 `openspec init` |
-| 子技能不可用 | 停止流程，提示安装/启用该技能 |
+| `openspec list --json` 失败 | 检查 openspec 安装，提示 `openspec init . --tools none` |
+| 子技能不可用 | 停止流程，提示运行 `comate init` 补装 |
 | `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `state set` 修复后继续 |
 | 构建/测试失败 | 回到 build 阶段修复，不要进入 verify |
 | 变更目录结构不完整 | 按 comate-open 产出物要求补全缺失文件 |
@@ -542,8 +553,8 @@ bash comate/scripts/comate.sh status       # 所有活动变更状态
 | Guard 持续报告 isolation/build_mode 未设置 | 断点恢复时未填写 | 返回 build 阶段完成设置 |
 | 验证失败后无法推进 | verify_result: fail | 用户先选择修复方案，智能体执行 `state transition <name> verify-fail` 后返回 build |
 | 变更目录结构不完整 | 流程中断 | 按 comate-open 产出物要求补全 |
-| `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `openspec init` |
-| 子技能不可用 | Superpowers 未安装 | 按平台文档安装 |
+| `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `comate init`，或 `openspec init . --tools none` |
+| 子技能不可用 | Superpowers 未安装 | 运行 `comate init` 补装 |
 | bash 版本过低 | bash < 4（无关联数组） | Windows：Git Bash/WSL；macOS：`brew install bash` |
 | .sh 文件包含 CRLF | git 配置问题 | 仓库有 `.gitattributes` 强制 `eol=lf`；如已损坏，使用 `dos2unix` |
 | 脏工作树无法推进 | 未遵循 dirty-worktree 协议 | 按协议归属，暂停并询问用户 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/SKILL.md

@@ -75,7 +75,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 | 场景 | 处理 |
 |------|------|
-| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `openspec init` |
+| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
 | `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
 | 构建/测试失败 | 回 build 阶段修复，不进入 verify |

package/skills/comate/reference/prerequisites.md

@@ -2,9 +2,9 @@
 
 规范路径：`comate/reference/prerequisites.md`
 
-comate 不附带安装器：OpenSpec 与 Superpowers 需要**手动安装**，comate 本身的分发方式就是「复制 `comate/` 文件夹」。本清单说明需要装什么、怎么自查、怎么补。
+`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
 
-> 一键自查：运行 `bash comate/scripts/comate.sh doctor`。它会检查下列大部分项目并给出可执行提示。
+> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
 
 ## 1. 运行环境
 
@@ -25,10 +25,10 @@ comate 不附带安装器：OpenSpec 与 Superpowers 需要**手动安装**，co
 npm install -g @fission-ai/openspec@latest
 ```
 
-初始化（在项目根目录）：
+初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
 
 ```bash
-openspec init
+openspec init . --tools none
 ```
 
 自查：
@@ -44,7 +44,7 @@ comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore
 
 负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
 
-Superpowers 是一组 skill，按你所用平台的约定安装到 skills 目录（如 `.claude/skills/`、`.cursor/skills/`、`~/.config/skills/` 等）。安装后确认下列 skill 可加载：
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
 
 - `superpowers:brainstorming`
 - `superpowers:writing-plans`
@@ -58,7 +58,9 @@ Superpowers 是一组 skill，按你所用平台的约定安装到 skills 目录
 
 ## 4. comate 自身
 
-分发 = 复制 comate 的全部 skill 目录到目标平台的 skills 目录。本项目（Claude Code 插件）采用**平铺布局**，因为 Claude Code 只发现顶层 skill 目录：
+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/