@house365/comate 0.2.6 → 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/bin/init-run.mjs

@@ -1,4 +1,5 @@
 // The `init` flow: install whatever the current project is missing.
+import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
@@ -54,19 +55,13 @@ export async function init(pkgRoot) {
     return 1;
   }
 
-  // ponytail: printed steps, not a \r spinner. npm's Windows global install
-  // routes `comate` through a comate.ps1 shim that makes stdout a pipe, where
-  // \r does not overwrite — every frame would stay on screen. A line per step
-  // shows progress in both a terminal and a pipe.
-  console.log('\nInitializing…');
-  const step = (name) => process.stdout.write(`  ${name}\n`);
+  const stopSpinner = startSpinner('Initializing…');
 
   // 1. OpenSpec CLI — a PATH command, so always global.
   const os = openSpecState();
   if (os.status === 'ready') {
     results.push(['OpenSpec CLI', 'skipped', `已安装 ${os.version}`]);
   } else {
-    step('OpenSpec CLI');
     const r = run(
       npmInvocation(['install', '-g', '@fission-ai/openspec@latest']),
       NPM_TIMEOUT_MS,
@@ -89,7 +84,6 @@ export async function init(pkgRoot) {
   if (superpowersInstalled('global') || superpowersInstalled('project')) {
     results.push(['Superpowers', 'skipped', '已安装']);
   } else {
-    step('Superpowers');
     const r = run(
       skillsInvocation(pkgRoot, ['add', 'obra/superpowers', '-g', '-y']),
       SKILLS_TIMEOUT_MS,
@@ -106,7 +100,6 @@ export async function init(pkgRoot) {
   // 3. comate itself. The skills CLI reports per-agent failures without ever
   // setting a non-zero exit code, and we swallow its output — so a zero status
   // is not evidence the skill landed. Check the file.
-  step('comate skills');
   const comateArgs = ['add', pkgRoot, '--skill', '*', '-g', '-y'];
   const r = run(skillsInvocation(pkgRoot, comateArgs), SKILLS_TIMEOUT_MS, { quiet: true });
   const landed = existsSync(join(home, '.agents', 'skills', 'comate', 'SKILL.md'));
@@ -122,7 +115,6 @@ export async function init(pkgRoot) {
   if (existsSync('openspec')) {
     results.push(['openspec/', 'skipped', '已存在']);
   } else {
-    step('openspec/ structure');
     // --tools is not optional in practice: openspec derives the tool list by
     // sniffing existing agent config dirs, so a fresh project (no .claude etc.)
     // aborts with "No tools detected and no --tools flag provided". comate's
@@ -140,13 +132,39 @@ export async function init(pkgRoot) {
     results.push(['openspec/', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason, r2.output]);
   }
 
-  return report(results, { home, cwd });
+  stopSpinner();
+  return report(results);
+}
+
+// The spinner runs in its own process because every step above is a synchronous
+// spawnSync — an interval on this thread would never fire. In a pipe \r does not
+// overwrite, so animating there would leave every frame on screen; print one
+// static line instead.
+function startSpinner(label) {
+  if (!process.stdout.isTTY) {
+    console.log(`\n${label}`);
+    return () => {};
+  }
+
+  const child = spawn(process.execPath, [join(import.meta.dirname, 'spinner.mjs'), label], {
+    stdio: ['ignore', 'inherit', 'ignore'],
+  });
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    child.kill();
+    // The parent erases the line, not the child: on Windows SIGTERM is not a
+    // real signal — Node terminates the process outright, so a handler in the
+    // child never runs and its last frame would sit under the logo.
+    process.stdout.write(`\r${' '.repeat(label.length + 6)}\r`);
+  };
 }
 
 // Success is one screen: the wordmark and where things landed. The per-item
 // breakdown only earns its space when something failed, and then it carries the
 // reason — a bare "失败" would leave the user with nowhere to go.
-function report(results, { home, cwd }) {
+function report(results) {
   const failed = results.filter(([, s]) => s === 'failed');
   if (failed.length > 0) {
     console.error('\n安装失败\n');
@@ -164,9 +182,7 @@ function report(results, { home, cwd }) {
   }
 
   console.log(banner(pkgVersion()));
-  console.log(`  skills      ${join(home, '.agents', 'skills')}`);
-  console.log(`  openspec    ${join(cwd, 'openspec')}`);
-  console.log('\n  输入 /comate 开始使用，comate doctor 可自检\n');
+  console.log('  Type /comate in your agent to start, or run comate doctor\n');
   return 0;
 }
 
@@ -204,13 +220,16 @@ export function banner(version, { ci = isCI() } = {}) {
     '╚██████╗╚██████╔╝██║ ╚═╝ ██║██║  ██║   ██║   ███████╗',
     ' ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝',
   ];
-  const cyan = (s) => (process.env.NO_COLOR ? s : `\x1B[36m${s}\x1B[0m`);
+  // #ed6d00 as a 24-bit SGR sequence. Truecolor is not universal, but the two
+  // terminals that matter here (Windows Terminal, VS Code) both support it, and
+  // one that doesn't degrades to its nearest palette entry rather than breaking.
+  const brand = (s) => (process.env.NO_COLOR ? s : `\x1B[38;2;237;109;0m${s}\x1B[0m`);
   const dim = (s) => (process.env.NO_COLOR ? s : `\x1B[2m${s}\x1B[0m`);
   return [
     '',
     // Trailing padding keeps the source rows aligned; strip it so the colour
     // reset doesn't sit behind spaces the terminal may highlight on select.
-    ...art.map((line) => `  ${cyan(line.replace(/\s+$/, ''))}`),
+    ...art.map((line) => `  ${brand(line.replace(/\s+$/, ''))}`),
     '',
     `  ${dim(`${tag} - AI coding almost there!`)}`,
     '',

package/bin/spinner.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// The init spinner, as its own process.
+//
+// It cannot run on init's main thread: every install step is a synchronous
+// spawnSync, which blocks the event loop, so an interval would not fire and the
+// frame would sit frozen for the whole install — worse than plain text.
+//
+// Animating means redrawing with \r, which only overwrites on a real terminal.
+// In a pipe every frame would stay on screen, so there the parent prints a
+// static line instead and never starts this process.
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const INTERVAL_MS = 80;
+
+const label = process.argv[2] ?? 'Initializing…';
+let i = 0;
+
+process.stdout.write('\n');
+const timer = setInterval(() => {
+  process.stdout.write(`\r  ${FRAMES[i++ % FRAMES.length]} ${label}`);
+}, INTERVAL_MS);
+
+// No cleanup handler here on purpose: on Windows SIGTERM is not a real signal,
+// Node terminates the process outright and a handler would never run. The parent
+// erases the line after killing us, which works on every platform.
+//
+// timer is the only thing holding the loop open, so nothing else is needed to
+// keep animating until that kill arrives.
+void timer;

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.6",
+  "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/