@house365/comate 0.4.0 → 0.6.0

package/README.md

@@ -2,30 +2,32 @@
 
 OpenSpec + Superpowers 规约驱动的 AI 开发编排器。
 
-comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(hotfix / tweak 预设除外)。
+comate 把 **OpenSpec**(WHAT:提案、规约生命周期、归档)和 **Superpowers**(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(fix 预设除外)。
 
 ## 五阶段
 
 ```
-[原始 PRD] ─→ /comate-intake ─┐  (阶段 0:门禁+拆分)
+[原始 PRD] ─→ /comate-gate ─┐  (阶段 0:门禁+拆分)
                               ▼
 /comate  ──自动探测阶段──────→ open → design → build → verify → archive
 ```
 
 | 阶段 | skill | 职责 |
 |------|-------|------|
-| intake | `/comate-intake` | (阶段 0,可选)对原始 PRD 做质量门禁 + 拆分成 N 个 change |
+| 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-hotfix`(热修)、`/comate-tweak`(文案/配置小调整)。
+预设路径:`/comate-fix`(快速小改动,覆盖 bug 修复与文案/配置小调整两种模式)。
 
-工具 skill:`/comate-grill`(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-intake 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 `/comate-grill <话题>` 挑战自己的计划草稿。
+工具 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-intake`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
+**阶段 0(PRD 门禁与拆分)**:需求若来自一份**原始 PRD**,先过 `/comate-gate`——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 `/comate-open`。门禁状态钉在 PRD 同级 `<PRD>.gate.yaml`,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。
 
 ## 安装
 
@@ -40,7 +42,7 @@ cd your-project
 comate init
 ```
 
-`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），创建 `openspec/` 项目结构，并铺出 `docs/` 知识库骨架（`docs/knowledge-base/requirements/` 放 PRD + PRD 模板、`docs/architecture/` 架构规范占位、integrations 对接模板）——`/comate-intake` 从这里读 PRD。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过，已有的 docs 文件不覆盖。
+`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` 需要在项目目录下运行。
 
@@ -68,9 +70,10 @@ skills/
     reference/       决策点、脏工作树协议、前置条件
     tests/           bats 测试
   comate-open/ design/ build/ verify/ archive/   各阶段 skill
-  comate-intake/                                  阶段 0:PRD 门禁与拆分
-  comate-hotfix/ tweak/                           预设路径 skill
+  comate-gate/                                    阶段 0:PRD 门禁与拆分
+  comate-fix/                                     预设路径 skill(bug + 小调整)
   comate-grill/                                   决策点穷追式澄清工具
+  comate-kb-integration/                          第三方对接档案生成工具(知识库配套)
 docs/
   COMATE_MANUAL.md   完整操作手册
 ```

package/bin/init-run.mjs

@@ -2,6 +2,7 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
 
 import { findBash } from './doctor.mjs';
 import {
@@ -50,12 +51,19 @@ export async function init(pkgRoot) {
 
   const target = inspectTarget(cwd, home);
   if (target.kind !== 'project') {
-    console.error(
-      target.kind === 'home'
-        ? '\n这是主目录，请在项目目录下运行 comate init。'
-        : '\n当前目录不像项目（无 .git / package.json 等），请在项目目录下运行 comate init。',
-    );
-    return 1;
+    // Home directory is always refused
+    if (target.kind === 'home') {
+      console.error('\n这是主目录，请在项目目录下运行 comate init。');
+      return 1;
+    }
+
+    // Bare directory: ask user if they want to create a project here
+    console.log('\n当前目录不像项目（无 .git / package.json 等）。');
+    const confirmed = await askConfirm('要在这里初始化新项目吗？');
+    if (!confirmed) {
+      console.log('已取消。');
+      return 1;
+    }
   }
 
   // comate's skills are bash scripts needing associative arrays (bash 4+), and
@@ -148,7 +156,7 @@ export async function init(pkgRoot) {
     results.push(['openspec/', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason, r2.output]);
   }
 
-  // 5. docs/ knowledge-base scaffold. /comate-intake reads PRDs from
+  // 5. docs/ knowledge-base scaffold. /comate-gate reads PRDs from
   // docs/knowledge-base/requirements/ (comate_kb_root is hardcoded there), so a
   // fresh project has nowhere to put a PRD. Idempotent — existing files are left
   // alone, only missing pieces are filled in, so re-running never clobbers a
@@ -167,6 +175,21 @@ export async function init(pkgRoot) {
   return report(results);
 }
 
+// A yes/no prompt. Defaults to "no" so a piped/non-interactive run (CI, an
+// unattended npx) never silently scaffolds a project into whatever directory it
+// happened to land in — those callers should point at a real project instead.
+// [y/N]: empty input, EOF (Ctrl-D / closed stdin), or anything but y/yes = no.
+export function askConfirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return Promise.resolve(false);
+  const rl = createInterface({ input, output });
+  return new Promise((done) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      done(/^\s*y(es)?\s*$/i.test(answer));
+    });
+  });
+}
+
 // 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

package/bin/init.mjs

@@ -176,7 +176,7 @@ function superpowersInstalled(scope) {
 // (repo checkout) and after `skills add` copies the skill to ~/.agents/skills.
 // Locating it relative to pkgRoot means init reads the same tree it packed.
 function scaffoldSourceDir(pkgRoot) {
-  return join(pkgRoot, 'skills', 'comate-intake', 'scaffold', 'docs');
+  return join(pkgRoot, 'skills', 'comate-gate', 'scaffold', 'docs');
 }
 
 // copyTreeSkipExisting — recursively copy src→dst, never overwriting a file that
@@ -201,7 +201,7 @@ function copyTreeSkipExisting(src, dst, acc = { created: 0, skipped: 0 }) {
 }
 
 // scaffoldDocs — lay down docs/ (knowledge-base + architecture placeholder + PRD
-// template) so /comate-intake has somewhere to read PRDs from. comate_kb_root in
+// template) so /comate-gate has somewhere to read PRDs from. comate_kb_root in
 // comate-lib.sh is hardcoded to docs/knowledge-base, so this path is not
 // configurable — it must match. Idempotent: existing files are never clobbered.
 function scaffoldDocs(pkgRoot, cwd = process.cwd()) {

package/bin/postinstall.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Postinstall hook: show the wordmark and next steps after npm install finishes.
+// Skipped in CI (where the logo wouldn't render anyway) and local dev installs
+// (where the developer already knows what they installed).
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Skip in CI, or when installing the package's own dependencies during dev.
+if (isCI() || isDevInstall()) {
+  process.exit(0);
+}
+
+const { banner, pkgVersion } = await import('./init-run.mjs');
+
+console.log(banner(pkgVersion(pkgRoot)));
+console.log(`  🎉 Congratulations! comate 已成功安装。\n`);
+console.log('  下一步：');
+console.log('    在你的项目目录下运行  comate init  开始使用');
+console.log('    或运行                comate doctor  健康检查');
+console.log('    更多帮助              comate --help\n');
+
+function isCI() {
+  return Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+}
+
+// When npm installs a package's own dependencies (npm i in the repo itself),
+// INIT_CWD points to the package root. A user installing comate globally or as
+// a dependency has INIT_CWD pointing elsewhere.
+function isDevInstall() {
+  const initCwd = process.env.INIT_CWD;
+  if (!initCwd) return false;
+  const normalise = (p) => resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+  return normalise(initCwd) === normalise(pkgRoot);
+}