@house365/comate 0.7.0 → 0.9.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jian Liang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jian Liang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,102 +1,102 @@
-# comate
-
-OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
-
-comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(fix 预设除外)。
-
-## 五阶段
-
-```
-[原始 PRD] ─→ /comate-gate ─┐  (阶段 0:门禁+拆分)
-                              ▼
-/comate  ──自动探测阶段──────→ open → design → build → verify → archive
-```
-
-| 阶段 | skill | 职责 |
-|------|-------|------|
-| gate | `/comate-gate` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
-| open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
-| design | `/comate-design` | 技术设计与方案 brainstorming |
-| build | `/comate-build` | 按任务实现并提交 |
-| verify | `/comate-verify` | 验证、出报告、处理分支 |
-| archive | `/comate-archive` | 同步增量规约并归档 |
-
-预设路径:`/comate-fix`(快速小改动,覆盖 bug 修复与文案/配置小调整两种模式)。
-
-工具 skill:
-- `/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-gate 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
-- `/comate-kb-integration`(第三方对接档案生成)——从官方文档 URL 抓取并按 `docs/knowledge-base/integrations/_TEMPLATE/` 规范产出对接档案(`<service-id>/README.md` + `api-snapshot.md`),自动追加根索引一行。是知识库 integrations scaffold 的配套建档工具;遇 JS 动态渲染文档站自动降级 Playwright 无头抓取。
-
-**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-gate`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
-
-## 安装
-
-```bash
-npm install -g @house365/comate
-```
-
-到项目目录初始化：
-
-```bash
-cd your-project
-comate init
-```
-
-`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-gate` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
-
-skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
-
-装完输入 `/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` 中,支持上下文压缩后断点恢复。
-
-## Token 用量:`comate usage`
-
-查看**当前项目**的 token 消耗与估算成本(封装 [ccusage](https://github.com/ryoppippi/ccusage),随 comate 一起装):
-
-```bash
-comate usage            # 本项目按会话(session)统计
-comate usage daily      # 本项目按天
-comate usage --global   # 全部项目(不做项目隔离)
-comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
-```
-
-默认只统计当前工作目录这一个项目:Claude Code 数据按 `~/.claude/projects/<项目>/` 隔离,Codex 数据按会话记录里的 `cwd` 过滤,两者都不会混入其它项目的用量。加 `--global` 看全量,或用 `comate usage codex ...` 单看某个 agent。
-
-> 粒度到项目/会话级;不做 open/design/build 阶段级归因(那需要在状态机打时间戳,属后续增强)。
-
-## 目录结构
-
-```
-skills/
-  comate/            主编排器:SKILL.md + 脚本 + 参考文档 + 测试
-    scripts/         comate.sh(CLI)、comate-lib.sh(共享库)
-    reference/       决策点、脏工作树协议、前置条件
-    tests/           bats 测试
-  comate-open/ design/ build/ verify/ archive/   各阶段 skill
-  comate-gate/                                    阶段 0:PRD 门禁与拆分
-  comate-fix/                                     预设路径 skill(bug + 小调整)
-  comate-grill/                                   决策点穷追式澄清工具
-  comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
-docs/
-  COMATE_MANUAL.md   完整操作手册
-```
-
-## 文档
-
-完整说明见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md):安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
-
-## License
-
-[MIT](LICENSE)
+# comate
+
+OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
+
+comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(fix 预设除外)。
+
+## 五阶段
+
+```
+[原始 PRD] ─→ /comate-gate ─┐  (阶段 0:门禁+拆分)
+                              ▼
+/comate  ──自动探测阶段──────→ open → design → build → verify → archive
+```
+
+| 阶段 | skill | 职责 |
+|------|-------|------|
+| gate | `/comate-gate` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
+| open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
+| design | `/comate-design` | 技术设计与方案 brainstorming |
+| build | `/comate-build` | 按任务实现并提交 |
+| verify | `/comate-verify` | 验证、出报告、处理分支 |
+| archive | `/comate-archive` | 同步增量规约并归档 |
+
+预设路径:`/comate-fix`(快速小改动,覆盖 bug 修复与文案/配置小调整两种模式)。
+
+工具 skill:
+- `/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-gate 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
+- `/comate-kb-integration`(第三方对接档案生成)——从官方文档 URL 抓取并按 `docs/knowledge-base/integrations/_TEMPLATE/` 规范产出对接档案(`<service-id>/README.md` + `api-snapshot.md`),自动追加根索引一行。是知识库 integrations scaffold 的配套建档工具;遇 JS 动态渲染文档站自动降级 Playwright 无头抓取。
+
+**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-gate`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
+
+## 安装
+
+```bash
+npm install -g @house365/comate
+```
+
+到项目目录初始化：
+
+```bash
+cd your-project
+comate init
+```
+
+`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-gate` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
+
+skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
+
+装完输入 `/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` 中,支持上下文压缩后断点恢复。
+
+## Token 用量:`comate usage`
+
+查看**当前项目**的 token 消耗与估算成本(封装 [ccusage](https://github.com/ryoppippi/ccusage),随 comate 一起装):
+
+```bash
+comate usage            # 本项目按会话(session)统计
+comate usage daily      # 本项目按天
+comate usage --global   # 全部项目(不做项目隔离)
+comate usage --json -s 2026-08-01   # 其余参数原样透传给 ccusage
+```
+
+默认只统计当前工作目录这一个项目:Claude Code 数据按 `~/.claude/projects/<项目>/` 隔离,Codex 数据按会话记录里的 `cwd` 过滤,两者都不会混入其它项目的用量。加 `--global` 看全量,或用 `comate usage codex ...` 单看某个 agent。
+
+> 粒度到项目/会话级;不做 open/design/build 阶段级归因(那需要在状态机打时间戳,属后续增强)。
+
+## 目录结构
+
+```
+skills/
+  comate/            主编排器:SKILL.md + 脚本 + 参考文档 + 测试
+    scripts/         comate.sh(CLI)、comate-lib.sh(共享库)
+    reference/       决策点、脏工作树协议、前置条件
+    tests/           bats 测试
+  comate-open/ design/ build/ verify/ archive/   各阶段 skill
+  comate-gate/                                    阶段 0:PRD 门禁与拆分
+  comate-fix/                                     预设路径 skill(bug + 小调整)
+  comate-grill/                                   决策点穷追式澄清工具
+  comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
+docs/
+  COMATE_MANUAL.md   完整操作手册
+```
+
+## 文档
+
+完整说明见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md):安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
+
+## License
+
+[MIT](LICENSE)

package/bin/init-run.mjs

@@ -11,10 +11,12 @@ import {
   SKILLS_TIMEOUT_MS,
   npmInvocation,
   openSpecState,
+  pruneDeprecatedSkills,
   run,
   scaffoldDocs,
   skillsInvocation,
   superpowersInstalled,
+  userSkillsRoot,
 } from './init.mjs';
 
 // `comate init` — no flags. Skills go user-level (~/.agents/skills), matching how
@@ -133,6 +135,13 @@ export async function init(pkgRoot) {
     results.push(['comate', r.ok ? 'installed' : 'failed', r.ok ? '' : r.reason, r.output]);
   }
 
+  // Prune comate skill dirs renamed/dropped in past releases. `skills add` above
+  // only adds/overwrites, so /comate-hotfix etc. would otherwise linger as dead
+  // slash commands. The postinstall hook does this too, but --ignore-scripts
+  // users never run it — init is their only path, so it must clean up here.
+  const pruned = pruneDeprecatedSkills(userSkillsRoot(home));
+  if (pruned.length) results.push(['清理废弃 skill', 'installed', pruned.join('、')]);
+
   // 4. openspec/ project structure. Not optional: comate's open and archive
   // phases read it, so an install without it cannot actually run. An existing
   // one is left alone, which covers projects that already keep it elsewhere.

package/bin/init.mjs

@@ -9,7 +9,7 @@
 // ponytail: no SKILLS_AGENT_MAP here. The skills CLI detects the running agent
 // on its own, so translating platform ids to agent names would be dead code.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync, lstatSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 
@@ -211,6 +211,83 @@ function scaffoldDocs(pkgRoot, cwd = process.cwd()) {
   return { ok: true, created, skipped };
 }
 
+// comate skill dirs that later releases renamed or dropped. `skills add` only
+// adds/overwrites, never removes, so without an explicit prune these linger in
+// ~/.agents/skills as dead slash commands (e.g. /comate-hotfix after it became
+// /comate-fix). ONLY these exact names are ever deleted: the dir also holds
+// unrelated third-party skills (lark-*, openspec-*), so a prefix sweep or a
+// diff-against-current strategy could wipe a user's own work. Add a line here
+// whenever a comate skill is renamed or removed.
+const DEPRECATED_SKILLS = ['comate-hotfix', 'comate-tweak', 'comate-intake'];
+
+function userSkillsRoot(home = process.env.HOME ?? process.env.USERPROFILE ?? '') {
+  return join(home, '.agents', 'skills');
+}
+
+// lstat, not stat: only a real directory is a comate-installed skill. A symlink
+// is a developer's deliberate dev setup pointing elsewhere — never remove it.
+function isRealDir(p) {
+  try {
+    return lstatSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Delete only the exact DEPRECATED_SKILLS dirs present under skillsRoot. Every
+// dependency is injectable so tests never touch a real ~/.agents/skills. Never
+// throws — a permission error or race on one dir must not abort an install.
+// Returns the names actually removed (for the caller to report).
+function pruneDeprecatedSkills(
+  skillsRoot,
+  {
+    names = DEPRECATED_SKILLS,
+    exists = existsSync,
+    isDir = isRealDir,
+    rm = (p) => rmSync(p, { recursive: true, force: true }),
+  } = {},
+) {
+  const removed = [];
+  for (const name of names) {
+    const dir = join(skillsRoot, name);
+    if (!exists(dir) || !isDir(dir)) continue;
+    try {
+      rm(dir);
+      removed.push(name);
+    } catch {
+      // A stuck dir (locked, permission) is not worth failing the install over.
+    }
+  }
+  return removed;
+}
+
+// True only when the pinned `skills` dependency resolves locally. A postinstall
+// must never reach the network, so this gates syncComateSkills: if resolution
+// fails we skip rather than let skillsInvocation fall back to `npx skills@latest`.
+function skillsResolvesLocally(pkgRoot) {
+  try {
+    createRequire(join(pkgRoot, 'package.json')).resolve('skills/package.json');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Copy comate's own skills into ~/.agents/skills via the bundled skills CLI —
+// the exact command `comate init` runs, so the layout is identical. Local-only:
+// skips (never goes to network) when the skills dep can't be resolved, leaving
+// `comate init` as the fallback. Returns { ok, skipped }.
+function syncComateSkills(pkgRoot, { home = process.env.HOME ?? process.env.USERPROFILE ?? '', runner = run } = {}) {
+  if (!skillsResolvesLocally(pkgRoot)) return { ok: false, skipped: 'no-local-cli' };
+  const r = runner(
+    skillsInvocation(pkgRoot, ['add', pkgRoot, '--skill', '*', '-g', '-y']),
+    SKILLS_TIMEOUT_MS,
+    { quiet: true },
+  );
+  const landed = existsSync(join(home, '.agents', 'skills', 'comate', 'SKILL.md'));
+  return { ok: r.ok && landed, skipped: null };
+}
+
 export {
   MIN_OPENSPEC,
   NPM_TIMEOUT_MS,
@@ -228,4 +305,8 @@ export {
   scaffoldSourceDir,
   copyTreeSkipExisting,
   scaffoldDocs,
+  DEPRECATED_SKILLS,
+  userSkillsRoot,
+  pruneDeprecatedSkills,
+  syncComateSkills,
 };

package/bin/postinstall.mjs

@@ -14,13 +14,33 @@ if (isCI() || isDevInstall()) {
 
 const { banner, pkgVersion } = await import('./init-run.mjs');
 
+// Best-effort: refresh the user-level skills so `npm i -g @latest` alone updates
+// them, and prune dirs renamed/dropped in past releases. All guarded — a failure
+// here must never break the npm install, and `comate init` remains the fallback
+// for --ignore-scripts users (who never reach this hook) and per-project setup.
+const sync = await syncSkillsQuietly();
+
 console.log(banner(pkgVersion(pkgRoot)));
 console.log(`  🎉 Congratulations! comate 已成功安装。\n`);
+if (sync.synced) console.log('  ✓ 已把 skills 同步到 ~/.agents/skills');
+if (sync.removed.length) console.log(`  ✓ 已清理废弃 skill：${sync.removed.join('、')}`);
 console.log('  下一步：');
-console.log('    在你的项目目录下运行  comate init  开始使用');
+console.log('    在你的项目目录下运行  comate init  完成项目初始化（openspec/、docs/）');
 console.log('    或运行                comate doctor  健康检查');
 console.log('    更多帮助              comate --help\n');
 
+async function syncSkillsQuietly() {
+  try {
+    const { syncComateSkills, pruneDeprecatedSkills, userSkillsRoot } = await import('./init.mjs');
+    const { ok } = syncComateSkills(pkgRoot);
+    const removed = pruneDeprecatedSkills(userSkillsRoot());
+    return { synced: ok, removed };
+  } catch {
+    // Any failure (no skills CLI resolvable, fs error) is silent: init covers it.
+    return { synced: false, removed: [] };
+  }
+}
+
 function isCI() {
   return Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
 }