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 起步。

安装

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

Token 用量:comate usage

查看当前项目的 token 消耗与估算成本(封装 ccusage,随 comate 一起装):

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   完整操作手册

文档

文档：

• 入门操作手册：面向第一次使用 comate 的同学，覆盖安装、init、目录、PRD、Skill 流程和常见问题。
• 完整技术手册：安装前置、命令参考、阶段详解、状态文件字段、决策阻塞点、故障排除。

License

MIT