@house365/comate 0.9.24 → 0.9.26

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,110 +1,110 @@
-<div align="center">
-  <img src="comate.png" alt="comate" width="600">
-</div>
-
-# comate
-
-**SDD (规约驱动开发)** 的 AI 开发编排器。
-
-comate 践行 **Specification-Driven Development (SDD)** 理念，通过五阶段工作流（gate → open → design → build → verify → archive）确保每个变更都有完整的规约与设计（fix 预设除外）。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
-
-## 五阶段
-
-```
-[原始 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/                          第三方对接档案生成工具(知识库配套)
+<div align="center">
+  <img src="comate.png" alt="comate" width="600">
+</div>
+
+# comate
+
+**SDD (规约驱动开发)** 的 AI 开发编排器。
+
+comate 践行 **Specification-Driven Development (SDD)** 理念，通过五阶段工作流（gate → open → design → build → verify → archive）确保每个变更都有完整的规约与设计（fix 预设除外）。底层集成 **OpenSpec**（提案、规约生命周期、归档）和 **Superpowers**（技术设计、规划、执行、收尾），并提供 PRD 门禁、决策澄清、知识库对接等编排能力。
+
+## 五阶段
+
+```
+[原始 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_BEGINNER_GUIDE.md  面向新手的安装与使用手册
   COMATE_MANUAL.md   完整操作手册
 ```
-
-## 文档
-
+
+## 文档
+
 文档：
 
 - [入门操作手册](docs/COMATE_BEGINNER_GUIDE.md)：面向第一次使用 comate 的同学，覆盖安装、`init`、目录、PRD、Skill 流程和常见问题。
 - [完整技术手册](docs/COMATE_MANUAL.md)：安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
-
-## License
-
-[MIT](LICENSE)
+
+## License
+
+[MIT](LICENSE)

package/bin/cleanup-duplicate-superpowers.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// 清理重复的 superpowers 安装（当 plugin 版本已存在时）
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+
+// 检查是否有 Claude Code plugin 安装
+function hasPluginInstall() {
+  const pluginRegistry = join(home, '.claude', 'plugins', 'installed_plugins.json');
+  if (!existsSync(pluginRegistry)) return false;
+
+  try {
+    const registry = JSON.parse(readFileSync(pluginRegistry, 'utf8'));
+    return Object.keys(registry.plugins || {}).some((key) =>
+      key.startsWith('superpowers@') &&
+      Array.isArray(registry.plugins[key]) &&
+      registry.plugins[key].length > 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+// 检查并清理 skills CLI 安装的 superpowers
+function cleanupSkillsCliInstall() {
+  const skillsRoots = [
+    join(home, '.agents', 'skills'),
+    join(home, '.claude', 'skills'),
+    join(home, '.config', 'skills'),
+    join(home, '.cursor', 'skills'),
+  ];
+
+  const superpowersSkills = ['using-superpowers', 'brainstorming'];
+  const removed = [];
+
+  for (const root of skillsRoots) {
+    for (const skill of superpowersSkills) {
+      const skillPath = join(root, skill);
+      if (existsSync(skillPath)) {
+        try {
+          rmSync(skillPath, { recursive: true, force: true });
+          removed.push(skillPath);
+        } catch (err) {
+          console.error(`✗ 删除失败: ${skillPath}`);
+          console.error(`  错误: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  return removed;
+}
+
+// 主函数
+export function cleanup() {
+  console.log('=== Superpowers 重复安装清理工具 ===\n');
+
+  // 1. 检查 plugin 安装
+  console.log('1. 检查 Claude Code plugin 安装...');
+  if (!hasPluginInstall()) {
+    console.log('   ✗ 未检测到 Claude Code plugin 版本的 superpowers');
+    console.log('   ⚠️  不建议清理 skills CLI 版本，因为没有其他可用版本\n');
+    return 1;
+  }
+  console.log('   ✓ 检测到 Claude Code plugin 版本\n');
+
+  // 2. 列出将要删除的目录
+  console.log('2. 扫描 skills CLI 安装...');
+  const skillsRoots = [
+    join(home, '.agents', 'skills'),
+    join(home, '.claude', 'skills'),
+    join(home, '.config', 'skills'),
+    join(home, '.cursor', 'skills'),
+  ];
+
+  const superpowersSkills = ['using-superpowers', 'brainstorming'];
+  const toRemove = [];
+
+  for (const root of skillsRoots) {
+    for (const skill of superpowersSkills) {
+      const skillPath = join(root, skill);
+      if (existsSync(skillPath)) {
+        toRemove.push(skillPath);
+        console.log(`   发现: ${skillPath}`);
+      }
+    }
+  }
+
+  if (toRemove.length === 0) {
+    console.log('   ✓ 未发现 skills CLI 版本的 superpowers\n');
+    console.log('无需清理，已经是最优状态！');
+    return 0;
+  }
+
+  console.log(`\n   共找到 ${toRemove.length} 个目录需要清理\n`);
+
+  // 3. 确认清理
+  console.log('3. 执行清理...');
+  const removed = cleanupSkillsCliInstall();
+
+  if (removed.length > 0) {
+    console.log(`   ✓ 已删除 ${removed.length} 个目录:`);
+    for (const path of removed) {
+      console.log(`     - ${path}`);
+    }
+  }
+
+  console.log('\n=== 清理完成 ===');
+  console.log('现在只使用 Claude Code plugin 版本的 superpowers');
+  console.log('相关 skill 在 Claude 中仍然可用\n');
+
+  return 0;
+}
+
+// 当作为脚本直接运行时
+if (import.meta.url === `file:///${process.argv[1].replace(/\\/g, '/')}`) {
+  process.exit(cleanup());
+}

package/bin/cli.mjs

@@ -52,7 +52,7 @@ async function checkForUpdates(currentVersion) {
 }
 
 // comate 自身的子命令（在下方被先取处理，不会透传给 skills CLI）。
-const COMATE_COMMANDS = ['init', 'doctor', 'update', 'usage'];
+const COMATE_COMMANDS = ['init', 'doctor', 'update', 'usage', 'cleanup'];
 
 // 允许透传给 skills CLI 的子命令（含别名）。留在这里的都是 skills CLI 真实存在
 // 的命令，未列入的一律视为未知命令并命中 --help。init/update 已被 comate 先取，
@@ -93,6 +93,7 @@ const HELP_TEXT = `comate — SDD (规约驱动开发) 的 AI 开发编排器
   comate doctor         健康检查
   comate update         更新 comate 到最新版本
   comate usage          查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
+  comate cleanup        清理重复的 superpowers 安装（当 plugin 版本已存在时）
   comate --help, -h     显示本帮助
   comate --version, -v  显示版本号
 
@@ -144,6 +145,11 @@ if (args[0] === 'usage') {
   process.exit(await usage(args.slice(1), { pkgRoot }));
 }
 
+if (args[0] === 'cleanup') {
+  const { cleanup } = await import('./cleanup-duplicate-superpowers.mjs');
+  process.exit(cleanup());
+}
+
 if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
   printHelp();
   process.exit(0);

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, lstatSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync, lstatSync, rmSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 
@@ -149,9 +149,8 @@ function openSpecState() {
   return { status: atLeast(version, MIN_OPENSPEC) ? 'ready' : 'outdated', version };
 }
 
-// Only detect skills CLI installation (flattens obra/superpowers into one dir
-// per skill). Claude Code plugin cache (plugins/{cache,data}/) is not a real
-// user-level install and should not count.
+// Detect skills CLI installation (flattens obra/superpowers into one dir per
+// skill) and Claude Code plugin installation (installed_plugins.json registry).
 const SUPERPOWERS_MARKERS = [
   ['using-superpowers'],
   ['brainstorming'],
@@ -164,7 +163,28 @@ function superpowersInstalled(scope) {
       ? ['.agents/skills', '.claude/skills', '.config/skills', '.cursor/skills']
           .map((r) => join(home, r))
       : ['.agents/skills', '.claude/skills', '.cursor/skills', '.codex/skills'];
-  return roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))));
+
+  // Check skills CLI installation
+  if (roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))))) {
+    return true;
+  }
+
+  // Check Claude Code plugin installation (only for global scope - plugins are user-level)
+  if (scope === 'global') {
+    const pluginRegistry = join(home, '.claude', 'plugins', 'installed_plugins.json');
+    try {
+      const registry = JSON.parse(readFileSync(pluginRegistry, 'utf8'));
+      // Check if superpowers plugin is installed (any marketplace)
+      return Object.keys(registry.plugins || {}).some((key) =>
+        key.startsWith('superpowers@') && Array.isArray(registry.plugins[key]) && registry.plugins[key].length > 0
+      );
+    } catch {
+      // File doesn't exist or parse failed - not a plugin install
+      return false;
+    }
+  }
+
+  return false;
 }
 
 // The docs scaffold ships inside the comate skill, so it is present both in dev

package/bin/update.mjs

@@ -2,6 +2,8 @@
 import { get } from 'node:https';
 import { spawn } from 'node:child_process';
 
+import { npmInvocation } from './init.mjs';
+
 // Fetch the latest version from npm registry
 function fetchLatestVersion() {
   return new Promise((resolve, reject) => {
@@ -30,16 +32,15 @@ function fetchLatestVersion() {
 }
 
 // Run npm install -g with live output
-function runNpmInstall(packageName) {
+export function runNpmInstall(packageName, { spawnFn = spawn, invocation = npmInvocation } = {}) {
   return new Promise((resolve) => {
     console.log(`\n正在更新 ${packageName}...\n`);
 
-    const isWindows = process.platform === 'win32';
-    const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+    const { command, args, shell } = invocation(['install', '-g', packageName]);
 
-    const child = spawn(npmCmd, ['install', '-g', packageName], {
+    const child = spawnFn(command, args, {
       stdio: 'inherit',
-      shell: isWindows,
+      ...(shell ? { shell: true } : {}),
     });
 
     child.on('close', (code) => {