<img src="https://github.com/rpamis/comet/blob/master/img/title-log.png" alt="Comet logo">

@rpamis/comet

 ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
██║     ██║   ██║██╔████╔██║█████╗     ██║
██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
 ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝

English version: README.md Bilibili video 抖音

OpenSpec + Superpowers 双星开发工作流 — 从创意到归档，一条命令。

OpenSpec 处理 WHAT（大纲、提案、spec 生命周期、归档）。

Superpowers 处理 HOW（技术设计、规划、执行、收尾）。

Comet 将二者串联为五阶段自动化流水线。

[!IMPORTANT] 0.3.9 — review_mode: off|standard|thorough 控制 Build/Verify 自动代码审查并支持项目级默认；init/update 改为可选依赖安装，补齐 CLI 国际化、阶段守护加固和 macOS 可执行权限。

0.3.8 — 新增 Kimi Code 支持、安全的多平台 comet uninstall、子代理调度扩展、按需加载共享参考、版本更新检查和 pre-commit 格式化。

0.3.7 — 新增 CodeGraph 语义索引、Beta 上下文压缩、主动式上下文压缩、Token 优化、auto_transition、阶段守护、可选 TDD 和更稳的归档/验证流程。

详见 NEWS.md。

为什么需要 Comet

OpenSpec 擅长管理需求、做提案、管理 Spec 生命周期和归档，但使用过程中 OpenSpec 的提案和 Task 没有像 Superpowers 头脑风暴那样细致。

Superpowers 在头脑风暴后会产出 Spec 文档，但这个文档通常没有进行状态化设计——做完需求之后 Spec 仅在文档上对 Task 打勾，甚至 Agent 还会忘记打勾，造成下一次断点开始时，Agent 需要重新查看文档和项目代码来核验，产生较多 Token 浪费。

Comet 合并了两者的强项，将核心流程整合为 5 个阶段

主入口 /comet 支持当前 Spec 状态检测，适用于长任务——中途关闭当前 AI 编码会话后，回来只需 /comet，Comet 会自动读取活跃的 Spec（多个则列出选择），动态识别当前执行到哪个阶段，继续往下执行。

同时，Comet具备Spec全生命周期管理能力，运行过程中能够将 OpenSpec 的 change/spec 制品与 Superpowers 的设计、计划文档进行关联，并自动完成交接、状态更新、校验和归档同步，把原本需要用户频繁提醒 Agent 维护文档同步和关联关系的操作自动化。

你能学到什么

现有的 Skill 市场中有很多优秀的 Skill 项目，但普遍存在偏好性问题——用户可能只喜欢部分功能。比如同时使用 OpenSpec 和 Superpowers 时，可能只用 OpenSpec 的 Spec 管理能力，而编码上更喜欢 Superpowers 的 TDD 驱动。

长期使用 Skill 的人都知道，这些能力是可以自由组合的，但具体怎么做依然需要真正的实践。Comet 项目可以作为参考：

• 如何稳定触发嵌套 Skill — 不是让 Agent 依靠文档描述做了“看起来像触发了 Skill”的操作（比如根据 Skill 描述写了文件），而是真正触发 Skill（核心特征：CC 上有 Skill 触发的打印）。Comet 中会触发大量来自 OpenSpec 和 Superpowers 的能力，这段 Prompt 是怎么写的？

• 如何让组合 Skill 多阶段自动流转 — 不是靠人工介入。Comet 的 5 阶段流程，除必要的用户选择项外，核心流程能够自动进行 Skill 触发，同时状态机机制也能保障状态扭转的可靠性。

• 如何把 Spec 生命周期做成可恢复流程 — Comet 会把 OpenSpec 的 change/spec 制品与 Superpowers 的设计、计划文档关联起来，并通过 .comet.yaml 记录阶段、执行模式、验证结果和归档状态，让 Agent 中断后能够继续，而不是重新翻文档猜进度。

• 如何把文档同步从“用户提醒”变成自动化 — Comet 将 handoff、状态更新、校验和归档同步放进脚本化流程，减少“记得更新 design doc”“记得同步 spec”“记得归档 change”这类反复提示。

• 如何设计 Agent 可执行的守护条件 — Comet 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 comet-guard.sh、 comet-yaml-validate.sh、comet-state.sh 等脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。

• 如何做跨平台 Skill 分发和安装 — Comet 支持多种 AI 编码平台、项目级/全局安装、中文/英文 Skill 选择，以及平台差异化目录（例如 Antigravity 的项目级和全局路径不同），可以作为 CLI 安装器和 Skill 打包结构的参考。

• 如何把 shell 脚本写成 Agent 工作流基础设施 — Comet 的脚本需要兼容 macOS、Linux、Windows Git Bash，处理 hash、YAML 字段、状态机和归档流程。它展示了如何把原本容易写散在 Prompt 里的流程控制，沉淀成可测试、可复用的工具。

安装

前置要求：

• Node.js 20+
• npm/npx
• Git
• 可运行 bash 的 shell 环境（Windows 用户建议使用 Git Bash 或等价环境）

npm install -g @rpamis/comet

快速开始

cd your-project
comet init

comet init 会：

1. 提示你选择 AI 平台（自动检测已有配置）
2. 选择安装范围：项目级（当前目录）或全局（用户主目录）
3. 选择 Comet 技能语言：English 或 中文
4. 选择要安装/升级的 npm 依赖 —— OpenSpec CLI、Superpowers（通过 npx skills add）、CodeGraph CLI。未检测到的依赖默认勾选；已存在的默认不勾，可自主选择是否升级。
5. 安装选中的依赖并部署对应技能
6. 将 Comet 技能（你选择的语言）部署到所选平台
7. 在项目级安装时创建 docs/superpowers/specs/ 和 docs/superpowers/plans/ 工作目录

[!TIP] 推荐安装 Superpowers v6.0.0+ —— 相比旧版速度快约 2 倍，节省约 50% token。 后续升级 Comet 本身：执行 comet update 或 npm install -g @rpamis/comet@latest。

对OpenClaw和Hermes、或其他AI平台的支持

对于直接使用通用 skills CLI 的平台，可以用下面的方式安装 Comet skill 包：

npx skills add rpamis/comet

运行截图

自动安装 OpenSpec、Superpowers，一键配置开发环境

多阶段 Skill 入口，自动识别当前 Spec 阶段，核心流程自动触发，关键节点人工审核

CLI命令

comet init [path] — 初始化 Comet 工作流

为选定的 AI 编码平台初始化 OpenSpec、Superpowers 和 Comet 技能。

当同一平台检测到多个已安装组件时，交互式 init 会先提供一次批量选择：全部覆盖、全部跳过，或逐项选择。

comet status [path] — 显示活跃更改和下一步命令

显示活跃更改、任务进度，以及推荐的下一步 Comet 工作流命令。

comet doctor [path] — 诊断 Comet 安装健康状态

检查项目级/全局安装、工作目录、已安装技能、脚本和 Comet 状态文件。

comet update [path] — 更新 Comet 包和技能

更新 npm 包，并刷新已检测到的项目级/全局 Comet 技能。

comet uninstall [path] — 卸载 Comet 技能、规则和钩子

安全移除 Comet 分发的技能、规则和钩子，保留用户自定义的钩子和非 Comet 配置。

comet uninstall              # 交互式 — 显示已安装目标，确认后卸载
comet uninstall --force      # 非交互式 — 直接移除所有内容
comet uninstall --scope project  # 仅移除项目级安装

支持平台

comet init 支持 29 个 AI 编码平台：

查看完整平台列表

部分平台的项目级目录和全局目录不同。例如 OpenCode 全局安装使用 .config/opencode，Lingma 全局安装使用 .lingma ，Antigravity 全局安装使用 .gemini/antigravity。

技能

comet init 完成后，三组技能将被安装到所选平台的 skills/ 目录：

Comet 技能

查看 Comet 技能列表

守护与自动化脚本

查看脚本列表

OpenSpec 技能

Spec 生命周期管理：propose、explore、sync、verify、archive 等。

Superpowers 技能

开发方法论：brainstorming、TDD、subagent-driven development、code review、plan writing 等。

工作流

/comet
  ↓ auto-detect
/comet-open  -->  /comet-design  -->  /comet-build  -->  /comet-verify  -->  /comet-archive
(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)

/comet-hotfix（快捷路径，跳过头脑风暴）
  open  -->  build  -->  verify  -->  archive

/comet-tweak（快捷路径，跳过头脑风暴和完整计划）
  open  -->  轻量构建  -->  轻量验证  -->  archive

五个阶段

核心原则

• 头脑风暴不可跳过 — 每个变更必须经过深度设计（hotfix/tweak 除外）
• Delta spec 是活文档 — 在阶段 3 中可自由编辑，归档时同步
• 保持 tasks.md 同步 — 每完成一个任务就勾选
• 频繁提交 — 每个任务一个 commit，message 体现设计意图
• 先验证再归档 — /comet-verify 必须通过才能执行 /comet-archive

状态管理

Comet 使用解耦状态架构，YAML 文件独立管理：

所有状态和运行阶段都通过脚本更新，并且会在每个阶段退出前校验任务是否真实完成。相比于将复杂状态管理写在 Skill 文本中，脚本化状态机能更稳定地保障阶段流转、YAML 正确性和断点恢复；Agent 只需要通过 Comet 内置命令读取状态，就能知道当前 Spec 处于哪个阶段。

查看 .comet.yaml 关键字段

.comet.yaml 关键字段：

workflow: full
auto_transition: true
phase: build
build_mode: subagent-driven-development
build_pause: null
isolation: branch
verify_mode: null
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
verify_result: pending
verification_report: null
branch_status: pending
verified_at: null
archived: false
direct_override: false
build_command: null
verify_command: null
handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256>
tdd_mode: null
subagent_dispatch: null

full workflow 初始化时 build_mode、build_pause、isolation、verify_mode、tdd_mode 和 subagent_dispatch 可以暂时为 null；进入 build → verify 前必须完成 build_mode 与 isolation 决策并写入合法值。auto_transition 控制阶段完成后是否自动触发下一个 Skill — 详见 AUTO-TRANSITION.md。build_pause 记录 build 阶段内部暂停点： null 表示无暂停，plan-ready 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 build_mode。 verification_report 在验证报告生成前保持 null，verify-pass 要求该报告文件存在且 branch_status: handled。示例中 archived 之后的字段是可选字段或脚本派生字段：direct_override 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在， handoff_context 和 handoff_hash 由 `comet-h