comate

OpenSpec + Superpowers 规约驱动的 AI 开发编排器。

comate 把 OpenSpec(WHAT:提案、规约生命周期、归档)和 Superpowers(HOW:设计、规划、执行、收尾)整合成统一的五阶段工作流。核心原则:每个变更都要经过深度设计(hotfix / tweak 预设除外)。

五阶段

[原始 PRD] ─→ /comate-intake ─┐  (阶段 0:门禁+拆分)
                              ▼
/comate  ──自动探测阶段──────→ open → design → build → verify → archive

| 阶段 | skill | 职责 | |------|-------|------| | intake | /comate-intake | (阶段 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(文案/配置小调整)。

工具 skill:/comate-grill(决策点穷追式澄清)——对计划/设计/PRD 的模糊点逐个深挖,每问附推荐答案、一次一问,直到歧义清零。comate-intake 在阻断问题多、有依赖链时会自动提供「深度澄清」选项调用它;也可单独 /comate-grill <话题> 挑战自己的计划草稿。

阶段 0(PRD 门禁与拆分):需求若来自一份原始 PRD,先过 /comate-intake——它审阅 PRD 质量、百分制评分、建阻断台账,门禁通过前禁止建任何 change;通过后按依赖/独立性判定把 PRD 拆成 1 或 N 个 change(粒度由用户定),逐个交给 /comate-open。门禁状态钉在 PRD 同级 <PRD>.gate.yaml,PRD 通过后被改会自动失效需重跑。需求来自对话时无需此阶段,直接从 open 起步。

安装

npm install -g @house365/comate

到项目目录初始化：

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 文件不覆盖。

skills 装到用户级（~/.agents/skills），装一次所有项目共用；openspec/ 是项目自己的规约，建在当前目录，所以 init 需要在项目目录下运行。

装完输入 /comate 开始使用，comate doctor 可自检。

更新

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 中,支持上下文压缩后断点恢复。

目录结构

skills/
  comate/            主编排器:SKILL.md + 脚本 + 参考文档 + 测试
    scripts/         comate.sh(CLI)、comate-lib.sh(共享库)
    reference/       决策点、脏工作树协议、前置条件
    tests/           bats 测试
  comate-open/ design/ build/ verify/ archive/   各阶段 skill
  comate-intake/                                  阶段 0:PRD 门禁与拆分
  comate-hotfix/ tweak/                           预设路径 skill
  comate-grill/                                   决策点穷追式澄清工具
docs/
  COMATE_MANUAL.md   完整操作手册

文档

完整说明见 docs/COMATE_MANUAL.md:安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。

License

MIT