@house365/comate 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,78 @@
+# comate
+
+OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
+
+comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(hotfix / tweak 预设除外)。
+
+## 五阶段
+
+```
+/comate  ──自动探测阶段──┐
+                         ▼
+open → design → build → verify → archive
+```
+
+| 阶段 | skill | 职责 |
+|------|-------|------|
+| open | `/comate-open` | 探索想法,创建 change 结构并初始化 `.comate.yaml` |
+| design | `/comate-design` | 技术设计与方案 brainstorming |
+| build | `/comate-build` | 按任务实现并提交 |
+| verify | `/comate-verify` | 验证、出报告、处理分支 |
+| archive | `/comate-archive` | 同步增量规约并归档 |
+
+预设路径:`/comate-hotfix`(热修)、`/comate-tweak`(文案/配置小调整)。
+
+## 安装
+
+```bash
+npx @house365/comate init     # 装 comate + 依赖到当前项目 ./.agents/skills/
+npx @house365/comate init -g  # 装到用户全局
+```
+
+`init` 会一并装齐两个依赖（OpenSpec CLI、Superpowers），已装的自动跳过，可重复执行。
+
+只装 comate 本身、不碰依赖：
+
+```bash
+npx @house365/comate          # 装到当前项目 ./.agents/skills/
+npx @house365/comate -g       # 装到用户全局
+npx @house365/comate --list   # 只看有哪些 skill，不安装
+```
+
+需要同时创建 `openspec/` 项目结构时加 `--openspec-init`。
+
+支持 Claude Code、Codex、Cursor 等 70+ agent（底层复用 [`skills`](https://www.npmjs.com/package/skills) CLI，自动探测当前 agent）。
+
+装完跑一次健康检查：
+
+```bash
+bash .agents/skills/comate/scripts/comate.sh doctor
+```
+
+依赖详情见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md) 第 2 节。
+
+## 用法
+
+输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。
+
+## 目录结构
+
+```
+skills/
+  comate/            主编排器:SKILL.md + 脚本 + 参考文档 + 测试
+    scripts/         comate.sh(CLI)、comate-lib.sh(共享库)
+    reference/       决策点、脏工作树协议、前置条件
+    tests/           bats 测试
+  comate-open/ design/ build/ verify/ archive/   各阶段 skill
+  comate-hotfix/ tweak/                           预设路径 skill
+docs/
+  COMATE_MANUAL.md   完整操作手册
+```
+
+## 文档
+
+完整说明见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md):安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// comate CLI. Two jobs:
+//   init  — install comate + its prerequisites (OpenSpec CLI, Superpowers)
+//   *     — everything else is forwarded to the `skills` CLI, which already
+//           handles agent detection, symlinking, update/remove for 70+ agents.
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+import { run, skillsInvocation, SKILLS_TIMEOUT_MS } from './init.mjs';
+
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+
+if (args[0] === 'init') {
+  const { init } = await import('./init-run.mjs');
+  process.exit(await init(pkgRoot, args.slice(1)));
+}
+
+if (args[0] === '--help' || args[0] === '-h') {
+  console.log(`comate — OpenSpec + Superpowers 规约驱动的开发编排器
+
+用法:
+  comate-skills init [-g] [--openspec-init]
+      安装 comate 及依赖 (OpenSpec CLI、Superpowers)。已装的自动跳过，可重复执行。
+        -g, --global      安装到用户全局目录 (默认: 当前项目)
+        --openspec-init   同时运行 openspec init 创建项目结构
+
+  comate-skills [add|list|remove|update ...]
+      直接透传给 skills CLI。不带子命令时安装本包全部 skill。
+
+安装后在 agent 中输入 /comate 开始使用。`);
+  process.exit(0);
+}
+
+// No args, or only flags (-g, --list, …) = install every comate skill from this
+// package, forwarding the flags. A leading subcommand passes straight through,
+// so remove/list/update all still work.
+const argv =
+  args.length && !args[0].startsWith('-') ? args : ['add', pkgRoot, '--skill', '*', ...args];
+
+const result = run(skillsInvocation(pkgRoot, argv), SKILLS_TIMEOUT_MS);
+if (!result.ok) {
+  console.error(`comate: skills CLI 执行失败 — ${result.reason}`);
+  process.exit(1);
+}

package/bin/init-run.mjs

@@ -0,0 +1,99 @@
+// The `init` flow: pick a scope, then install what's missing.
+import { existsSync } from 'node:fs';
+
+import {
+  MIN_OPENSPEC,
+  NPM_TIMEOUT_MS,
+  SKILLS_TIMEOUT_MS,
+  npmInvocation,
+  openSpecState,
+  run,
+  skillsInvocation,
+  superpowersInstalled,
+} from './init.mjs';
+
+// Same convention as the bare `comate-skills` command: no flag means project,
+// -g means global. No prompt — the flag already says it.
+export function resolveScope(argv) {
+  return argv.includes('-g') || argv.includes('--global') ? 'global' : 'project';
+}
+
+export async function init(pkgRoot, argv) {
+  const scope = resolveScope(argv);
+  const withOpenSpecInit = argv.includes('--openspec-init');
+  const results = [];
+
+  console.log(`\n安装范围: ${scope === 'global' ? '全局' : '项目'}\n`);
+
+  // 1. OpenSpec CLI — a PATH command, so global regardless of skill scope.
+  const os = openSpecState();
+  if (os.status === 'ready') {
+    results.push(['OpenSpec CLI', 'skipped', `已安装 ${os.version}`]);
+  } else {
+    const label = os.status === 'outdated' ? `升级 (${os.version} < ${MIN_OPENSPEC})` : '安装';
+    console.log(`→ ${label} OpenSpec CLI (npm install -g)`);
+    const r = run(npmInvocation(['install', '-g', '@fission-ai/openspec@latest']), NPM_TIMEOUT_MS);
+    if (!r.ok) {
+      // An outdated-but-usable CLI is better than a hard failure.
+      const usable = os.status === 'outdated';
+      results.push(['OpenSpec CLI', usable ? 'skipped' : 'failed', usable ? `升级失败，沿用 ${os.version}` : r.reason]);
+    } else if (openSpecState().status === 'missing') {
+      results.push(['OpenSpec CLI', 'failed', 'npm 安装完成但 PATH 中仍找不到 openspec，请重启终端']);
+    } else {
+      results.push(['OpenSpec CLI', 'installed', '']);
+    }
+  }
+
+  // 2. Superpowers — the skills CLI detects the agent itself.
+  if (superpowersInstalled(scope)) {
+    results.push(['Superpowers', 'skipped', '已安装']);
+  } else {
+    console.log('\n→ 安装 Superpowers (skills add obra/superpowers)');
+    const args = ['add', 'obra/superpowers', '-y', ...(scope === 'global' ? ['-g'] : [])];
+    const r = run(skillsInvocation(pkgRoot, args), SKILLS_TIMEOUT_MS);
+    // It clones from GitHub, so a bare exit code hides the usual cause: no
+    // network. Say so rather than leaving the user with "exit code 1".
+    const note = r.ok
+      ? ''
+      : `${r.reason} — 需要访问 github.com，检查网络/代理后重试`;
+    results.push(['Superpowers', r.ok ? 'installed' : 'failed', note]);
+  }
+
+  // 3. comate itself.
+  console.log('\n→ 安装 comate skills');
+  const comateArgs = ['add', pkgRoot, '--skill', '*', '-y', ...(scope === 'global' ? ['-g'] : [])];
+  const r = run(skillsInvocation(pkgRoot, comateArgs), SKILLS_TIMEOUT_MS);
+  results.push(['comate', r.ok ? 'installed' : 'failed', r.ok ? '' : r.reason]);
+
+  // 4. openspec init — opt-in: it writes openspec/ into the user's project and
+  // edits agent config files, a bigger side effect than the installs above.
+  if (withOpenSpecInit) {
+    console.log('\n→ 初始化 OpenSpec 项目结构 (openspec init)');
+    const r2 = run({ command: 'openspec', args: ['init', '.'], shell: process.platform === 'win32' }, NPM_TIMEOUT_MS);
+    results.push(['openspec init', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason]);
+  } else if (!existsSync('openspec')) {
+    results.push(['openspec init', 'skipped', '未初始化项目结构，需要时加 --openspec-init']);
+  }
+
+  return report(results, scope);
+}
+
+function report(results, scope) {
+  const mark = { installed: '✓', skipped: '·', failed: '✗' };
+  console.log('\n' + '─'.repeat(58));
+  for (const [name, status, note] of results) {
+    console.log(`  ${mark[status]} ${name.padEnd(16)} ${status.padEnd(10)} ${note}`);
+  }
+  console.log('─'.repeat(58));
+
+  const failed = results.filter(([, s]) => s === 'failed');
+  if (failed.length > 0) {
+    console.error(`\n${failed.length} 项失败。修复后可重跑 comate-skills init（已安装的会自动跳过）。`);
+    return 1;
+  }
+  const doctorPath =
+    scope === 'global' ? '~/.claude/skills/comate/scripts/comate.sh' : '.agents/skills/comate/scripts/comate.sh';
+  console.log(`\n完成。健康检查: bash ${doctorPath} doctor`);
+  console.log('在 agent 中输入 /comate 开始使用。');
+  return 0;
+}

package/bin/init.mjs

@@ -0,0 +1,159 @@
+// `comate-skills init` — install comate's prerequisites, then comate itself.
+//
+// Three dependencies, each already has an installer we can drive:
+//   OpenSpec CLI  -> npm install -g @fission-ai/openspec@latest  (PATH command,
+//                    so always global regardless of the chosen skill scope)
+//   Superpowers   -> npx skills add obra/superpowers             (scope-aware)
+//   comate        -> npx skills add <this package>               (scope-aware)
+//
+// 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 } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const MIN_OPENSPEC = '1.5.0';
+const NPM_TIMEOUT_MS = 180_000;
+const SKILLS_TIMEOUT_MS = 300_000;
+
+// Locate npm's own JS entry. Two layouts, and checking only the Windows one
+// silently sent every POSIX run down the shell fallback:
+//   Windows  <prefix>/node_modules/npm/...        (node.exe sits in <prefix>)
+//   POSIX    <prefix>/lib/node_modules/npm/...    (node sits in <prefix>/bin)
+function findNpmCli() {
+  const bin = dirname(process.execPath);
+  const candidates = [
+    join(bin, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    join(bin, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+// npm.cmd cannot be spawned directly since Node 20, and shell:true with args is
+// both deprecated (Node 24) and an injection surface. Run npm's own JS entry.
+function npmInvocation(args) {
+  const cli = findNpmCli();
+  return cli
+    ? { command: process.execPath, args: [cli, ...args] }
+    : { command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args, shell: true };
+}
+
+// Shared by the release scripts: the packed file list straight from npm, so no
+// reimplementation of its `files` glob rules.
+function packedFiles() {
+  const argv = ['pack', '--json', '--dry-run', '--ignore-scripts'];
+  const { command, args, shell } = npmInvocation(argv);
+  const { status, stdout, stderr } = spawnSync(command, args, {
+    encoding: 'utf8',
+    ...(shell ? { shell: true } : {}),
+  });
+  if (status !== 0) throw new Error(`npm pack failed:\n${stderr ?? '(no stderr)'}`);
+
+  // Lifecycle scripts can print ahead of npm's payload, so scan `[` positions
+  // left-to-right and take the first that parses as a whole array.
+  const clean = stdout.replace(/\[[0-9;]*m/g, '').trim();
+  for (let i = clean.indexOf('['); i !== -1; i = clean.indexOf('[', i + 1)) {
+    try {
+      const [packed] = JSON.parse(clean.slice(i));
+      if (Array.isArray(packed?.files)) return packed.files.map((f) => f.path.replace(/\\/g, '/'));
+    } catch {
+      // Not the payload's opening bracket (e.g. a nested array); keep looking.
+    }
+  }
+  throw new Error(`no usable file list in npm pack output:\n${stdout}`);
+}
+
+function run({ command, args, shell }, timeout) {
+  const { status, error } = spawnSync(command, args, {
+    stdio: 'inherit',
+    timeout,
+    ...(shell ? { shell: true } : {}),
+  });
+  if (error) return { ok: false, reason: error.message };
+  if (status !== 0) return { ok: false, reason: `exit code ${String(status)}` };
+  return { ok: true };
+}
+
+function capture(command, args) {
+  const { status, stdout: out } = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 15_000,
+    shell: process.platform === 'win32',
+  });
+  return status === 0 ? out.trim() : null;
+}
+
+// Numeric compare so 1.10.0 sorts above 1.5.0 (string compare gets this wrong).
+function atLeast(version, minimum) {
+  const parse = (v) => (v.match(/(\d+)\.(\d+)\.(\d+)/) ?? []).slice(1).map(Number);
+  const [a, b] = [parse(version), parse(minimum)];
+  if (a.length !== 3) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return true;
+}
+
+// Prefer the pinned `skills` dependency (offline, version-locked); fall back to
+// npx when resolution fails (e.g. a hoisting layout we can't see).
+function skillsInvocation(pkgRoot, args) {
+  try {
+    const require = createRequire(join(pkgRoot, 'package.json'));
+    const manifest = require('skills/package.json');
+    const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin.skills;
+    const entry = join(dirname(require.resolve('skills/package.json')), bin);
+    return { command: process.execPath, args: [entry, ...args] };
+  } catch {
+    return {
+      command: process.platform === 'win32' ? 'npx.cmd' : 'npx',
+      args: ['--yes', 'skills@latest', ...args],
+      shell: process.platform === 'win32',
+    };
+  }
+}
+
+function openSpecState() {
+  const version = capture('openspec', ['--version']);
+  if (version === null) return { status: 'missing' };
+  return { status: atLeast(version, MIN_OPENSPEC) ? 'ready' : 'outdated', version };
+}
+
+// Two install shapes to detect:
+//   skills CLI  — flattens obra/superpowers into one dir per skill, so nothing
+//                 is literally named "superpowers"; using-superpowers is the
+//                 entry skill and the stable marker.
+//   Claude Code — installs it as a plugin under plugins/{cache,data}/.
+const SUPERPOWERS_MARKERS = [
+  ['using-superpowers'],
+  ['brainstorming'],
+  ['superpowers'],
+  ['superpowers-claude-plugins-official'],
+  ['cache', 'claude-plugins-official', 'superpowers'],
+];
+
+function superpowersInstalled(scope) {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+  const roots =
+    scope === 'global'
+      ? ['.agents/skills', '.claude/skills', '.claude/plugins', '.config/skills', '.cursor/skills']
+          .map((r) => join(home, r))
+      : ['.agents/skills', '.claude/skills', '.claude/plugins', '.cursor/skills', '.codex/skills'];
+  return roots.some((root) => SUPERPOWERS_MARKERS.some((m) => existsSync(join(root, ...m))));
+}
+
+export {
+  MIN_OPENSPEC,
+  NPM_TIMEOUT_MS,
+  SKILLS_TIMEOUT_MS,
+  findNpmCli,
+  npmInvocation,
+  packedFiles,
+  skillsInvocation,
+  run,
+  capture,
+  atLeast,
+  openSpecState,
+  superpowersInstalled,
+};