Comet 使用指南：OpenSpec + Superpowers 双星开发工作流 — 从创意到归档，一条命令

Comet 使用指南

Comet：从想法到归档的阶段守护式 Agent Skill 编排框架 把 OpenSpec（管需求 WHAT）和 Superpowers（管执行 HOW）串成一条 5 阶段自动化流水线。 官方仓库:https://github.com/rpamis/comet https://github.com/rpamis/comet

目录

• 一、Comet 是什么
• 二、核心概念与三者关系
• 三、环境要求
• 四、安装与初始化
• 五、命令行（CLI）完整参考
• 六、Skill 命令完整参考
• 七、实际开发：完整使用流程
• 八、5 阶段工作流详解
• 九、状态管理
• 十、配置项
• 十一、可靠性与守卫机制
• 十二、支持的平台
• 十三、Windows 用户注意事项
• 十四、常见问题
• 十五、目录结构参考
• 附录：快速上手 Checklist

一、Comet 是什么

Comet 是一个 Agent Skill Harness（智能体技能编排框架），核心价值是：

• 把分散的 AI 编程 skills（OpenSpec + Superpowers）编排成一条受状态机守护的流水线
• 每个阶段进入前都有守卫检查（guard），防止跳步、漏步骤
• 从一个想法（idea）一路自动推进到归档（archive），全程可追溯
• 支持断点恢复：中途关闭 AI 会话，重新打开后输入 /comet 即可自动识别当前阶段并继续

解决的核心痛点：AI 编程时经常"自由发挥"（vibe coding），跳过需求确认、漏掉测试、忘了归档。Comet 用阶段守卫强制把流程管起来。

二、核心概念与三者关系

一句话理解：装了 Comet，OpenSpec 和 Superpowers 会自动一起装好，不需要单独安装那两个。

数据流

/comet
  ↓ 自动检测当前阶段
/comet-open  -->  /comet-design  -->  /comet-build  -->  /comet-verify  -->  /comet-archive
(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)

三、环境要求

⚠️ Windows 用户必读：Comet 的核心守卫脚本（如 comet-guard.sh）是 bash 脚本，cmd.exe 和 PowerShell 无法运行。必须安装并使用 Git Bash。

四、安装与初始化

4.1 全局安装 NPM 包（只需一次）

打开 Git Bash（Windows）或终端（macOS/Linux）：

npm install -g @rpamis/comet

4.2 进入项目并初始化

cd your-project
comet init

comet init 会依次询问：

1. 选择 AI 平台（多选，空格勾选）— 自动检测你电脑上已安装的平台
2. 选择安装范围（scope）： scope安装位置生效范围适合场景project当前项目目录（如 .claude/skills/）仅当前项目想让 skills 进 Git、团队共享global用户主目录（如 ~/.claude/skills/）本机所有项目个人偏好，所有项目通用
3. 选择语言：English 或 中文

随后自动完成：装 OpenSpec skills → 装 Superpowers skills → 部署 Comet skills → 创建工作目录。

4.3 非交互式（自动化/复现）

# 项目级，自动选用检测到的平台
comet init --scope project --yes

# 全局级
comet init --scope global --yes

4.4 更新到最新版

comet update
# 或
npm install -g @rpamis/comet@latest

五、命令行（CLI）完整参考

COMET INIT [PATH] — 初始化 COMET 工作流

COMET STATUS [PATH] — 查看当前活跃 CHANGE 和下一步命令

显示当前活跃的 change、任务进度、以及推荐的下一个 Comet 工作流命令。

COMET DOCTOR [PATH] — 诊断安装健康

检查项目/全局安装健康度、工作目录、已安装 skills、脚本、Comet 状态文件。

COMET UPDATE [PATH] — 更新 COMET 包和 SKILLS

COMET UNINSTALL [PATH] — 卸载 COMET SKILLS/RULES/HOOKS

安全移除所有检测到的平台上的 Comet 组件，保留用户自定义配置。

comet uninstall                  # 交互式，显示目标并确认
comet uninstall --force          # 非交互，立即移除
comet uninstall --scope project  # 只移除项目级

其他

六、Skill 命令完整参考

初始化后，三类 skills 会安装到所选平台的 skills/ 目录。这些 /comet-* 命令是在你的 AI 编程工具（如 Claude Code）里输入的，不是终端命令。

COMET SKILLS（核心流程命令）

预设路径（轻量流程）

/comet-hotfix（跳过 brainstorming）
  open  -->  build  -->  verify  -->  archive

/comet-tweak（跳过 brainstorming 和完整 plan）
  open  -->  轻量 build  -->  轻量 verify  -->  archive

OPENSPEC SKILLS

负责 Spec 生命周期：propose、explore、sync、verify、archive 等。

SUPERPOWERS SKILLS

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

七、实际开发：完整使用流程

以一个新功能开发为例（例如"给项目加一个用户登录功能"），完整走一遍：

场景一：完整功能开发（FULL WORKFLOW）

步骤 0：前提准备

# 用 Git Bash 进入项目
cd your-project

# 确认已初始化（首次执行）
comet init   # 勾选 Claude Code，scope 选 project，语言选 中文

# 检查健康
comet doctor

步骤 1：开启 change（在 AI 工具里）

打开 Claude Code（或 Qoder / Trae），输入：

/comet-open

然后用自然语言描述你要做什么：

我要给项目加一个用户登录功能，支持邮箱+密码登录，需要 JWT token。

AI 会帮你生成（放在 openspec/changes/<change-name>/）：

• proposal.md — 提案（为什么做、做什么）
• design.md — 初步设计
• tasks.md — 任务拆解清单

步骤 2：深度设计

/comet-design

AI 会：

• 进行 brainstorming（头脑风暴），探索技术方案
• 生成 Design Doc（放 docs/superpowers/specs/）
• 生成 delta spec（差异规范）

💡 如果 auto_transition: true，阶段 1 完成后会自动进入阶段 2，无需手动输入。

步骤 3：计划与构建

/comet-build

AI 会：

• 生成实现计划（放 docs/superpowers/plans/）
• 关键选择：选 isolation（branch 分支 / worktree 工作树）和 build_mode（执行模式）
• 按 TDD 流程写代码：写测试 → 实现 → 测试通过
• 每个任务一次 commit，commit message 反映设计意图

步骤 4：验证收尾

/comet-verify

AI 会：

• 跑全部测试
• 生成验证报告（verification_report）
• 处理分支（branch_status）
• 守卫会强制要求：verification_report 必须存在 + branch_status: handled 才能通过

步骤 5：归档

/comet-archive

AI 会：

• 把 delta spec 合并进主 spec（通过 OpenSpec）
• 标注 design doc 和 plan 的 frontmatter
• 把 change 移到 archive 目录
• 更新 archived: true

场景二：快速修 BUG（HOTFIX）

/comet-hotfix

跳过 brainstorming，走精简流程：

open  -->  build  -->  verify  -->  archive

适合：线上 bug、明显错误、不需要深度设计的小修复。

场景三：小改动（TWEAK）

/comet-tweak

跳过 brainstorming 和完整 plan，走最轻量流程：

open  -->  轻量 build  -->  轻量 verify  -->  archive

适合：改文案、调样式、改配置值等。

场景四：断点恢复（核心特性）

关闭会话后重新继续，无需记忆进度，直接在 AI 工具里输入：

/comet

Comet 会：

1. 自动读取 .comet.yaml 状态
2. 识别当前正在执行的 change（多个则列出供你选）
3. 动态判断当前处于哪个阶段
4. 从断点继续执行

八、5 阶段工作流详解

核心原则

• Brainstorming 不可跳过 — 每个 change 必须经过深度设计（hotfix/tweak 除外）
• Delta spec 是活文档 — 阶段 3 期间可自由编辑，归档时同步
• 保持 tasks.md 同步 — 每完成一个任务就勾选
• 频繁提交 — 一个任务一次 commit，message 反映设计意图
• 归档前必验证 — /comet-verify 必须通过才能 /comet-archive

九、状态管理

Comet 采用解耦的状态架构，用两个独立的 YAML 文件：

.COMET.YAML 关键字段

workflow: full# 工作流类型：full / hotfix / tweak
auto_transition: true# 阶段完成后是否自动进入下一阶段
phase: build# 当前阶段：open/design/build/verify/archive
build_mode: subagent-driven-development# 构建模式
build_pause: null# 构建暂停点（null 无暂停，plan-ready 计划已生成待选）
isolation: branch# 隔离方式：branch / worktree
verify_mode: null# 验证模式
tdd_mode: null# TDD 模式
subagent_dispatch: 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# 分支状态：handled 才能验证通过
verified_at: null# 验证时间
archived: false# 是否已归档
handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256># 上下文哈希

⚠️ 重要：build_pause: plan-ready 是计划生成后的可恢复暂停点，不是 build_mode 的值，不能写进 build_mode。

十、配置项

在 .comet/config.yaml（项目级）中配置：

CONTEXT_COMPRESSION（上下文压缩，BETA）

在 Design → Build 交接时压缩上下文，减少 Build 阶段输入 token。

context_compression: beta

基准测试结果：

• 测试通过率：100%（压缩不影响正确性）
• Spec 覆盖率：100%（off）vs 95%（beta）
• 大型任务绝对节省可达 15,000 tokens

AUTO_TRANSITION（自动阶段切换）

控制阶段完成后是否自动调用下一个 skill。

优先级：COMET_AUTO_TRANSITION 环境变量 > .comet/config.yaml（项目）> .comet.yaml（change）

十一、可靠性与守卫机制

Comet 通过自动化状态转换保证执行可靠性：

1. 入口验证

每个阶段执行前验证前置条件（文件存在、状态一致、阶段转换合法）。失败时输出 [HARD STOP] 并给出可操作建议。

2. 自动状态转换

comet-guard.sh --apply 自动更新 .comet.yaml，无需手动编辑状态，消除写错风险。

3. SCHEMA 校验

comet-yaml-validate.sh 校验：

• 必填和可选字段
• 枚举值（含 direct_override）
• design_doc、plan、handoff_context 路径是否存在
• handoff_hash 格式
• 检测未知/拼写错误字段

4. 构建决策强制

• isolation 必须是 branch 或 worktree
• build_mode 离开 build 阶段前必须选定
• full workflow 的 build_mode: direct 需要 direct_override: true

5. 验证证据

• verify-pass 转换要求 verification_report 指向真实存在的报告文件
• branch_status 必须为 handled 才能验证通过
• 防止跳过验证就推进阶段

6. 归档自动化

comet-archive.sh 一条命令完成全流程：校验状态 → 合并 delta spec → 标注文档 → 移到 archive → 更新状态。支持 --dry-run 预览。

守卫脚本一览

十二、支持的平台

Comet 官方支持 29 个 AI 编程平台：

部署机制：

• comet init 自动检测本机已安装的平台
• 一次 init 可多选批量部署到多个平台
• 每个平台得到独立的 skills 文件副本（放各自目录，互不共享）

通用 SKILLS CLI 平台

对于使用通用 skills CLI 的平台（OpenClaw、Hermes 等）：

npx skills add rpamis/comet

十三、Windows 用户注意事项

13.1 必须使用 GIT BASH

Comet 的守卫脚本是 bash 脚本：

• ❌ cmd.exe：无法运行
• ❌ PowerShell：无法运行
• ✅ Git Bash：正确选择

安装 Git Bash:https://git-scm.com/download/win

13.2 路径格式

13.3 换行符

建议在项目根目录加 .gitattributes，防止 sh 脚本换行符变 CRLF：

*.sh text eol=lf

十四、常见问题

Q1：装了 COMET，还要单独装 OPENSPEC 或 SUPERPOWERS 吗？

不用。 comet init 会自动把两者作为依赖 skills 一起装好。

Q2：全局 VS 项目级怎么选？

• 全局（global）：个人用、所有项目都想用 → 推荐
• 项目级（project）：想让 skills 进 Git、团队共享

Q3：多个平台要装多次吗？

操作上不用。 一次 comet init 多选平台即可批量部署。物理上每个平台各得一份 skills。

Q4：为什么 WINDOWS 上验证失败？

99% 是没用 Git Bash。请用 Git Bash 重新执行。

Q5：可以跳过某些阶段吗？

可以。用 /comet-hotfix（跳过 brainstorming）或 /comet-tweak（跳过 brainstorming 和完整 plan）。

Q6：中途关了会话怎么办？

在 AI 工具里输入 /comet，它会自动读取 .comet.yaml、识别当前阶段、从断点继续。

Q7：COMET 会改我的源代码吗？

Comet 是 skill 编排框架，实际写代码的是你选的 AI 平台。Comet 只负责守卫流程、管理 spec 和归档。

Q8：如何查看当前进度？

comet status      # 终端查看

或在 AI 工具里输入 /comet 也能看到当前阶段。

Q9：如何卸载？

comet uninstall            # 交互式，会确认
comet uninstall --force    # 直接卸载

只移除 Comet 组件，保留你的自定义配置。

十五、目录结构参考

your-project/
├── .comet/
│   └── config.yaml                  # 项目级配置（context_compression, auto_transition 等）
├── .claude/skills/                  # 平台 skills 目录（Comet + OpenSpec + Superpowers）
│   ├── comet/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       ├── comet-guard.sh       # 阶段转换守卫
│   │       ├── comet-env.sh         # 脚本发现助手
│   │       ├── comet-handoff.sh     # 设计交接
│   │       ├── comet-archive.sh     # 归档自动化
│   │       ├── comet-yaml-validate.sh  # Schema 校验
│   │       ├── comet-hook-guard.sh  # 阶段写守卫
│   │       └── comet-state.sh       # 统一状态管理
│   ├── comet-*/SKILL.md             # 各阶段子命令
│   ├── openspec-*/SKILL.md          # OpenSpec skills
│   └── brainstorming/SKILL.md       # Superpowers skills
├── openspec/                        # OpenSpec — WHAT
│   ├── config.yaml
│   └── changes/
│       └── <change-name>/
│           ├── .openspec.yaml       # OpenSpec 状态
│           ├── .comet.yaml          # Comet 工作流状态
│           ├── proposal.md          # 提案
│           ├── design.md            # 设计
│           ├── specs/<capability>/spec.md  # 规范
│           └── tasks.md             # 任务清单
└── docs/superpowers/                # Superpowers — HOW
    ├── specs/                       # 设计文档
    └── plans/                       # 实现计划

附录：快速上手 Checklist

环境准备

• ⬜ 安装 Node.js 20+
• ⬜ 安装 Git for Windows（含 Git Bash）
• ⬜ 全局安装 Comet： 全局安装 Comet：`npm install -g @rpamis/comet`

初始化

• ⬜ 用 Git Bash 进入项目： 用 Git Bash 进入项目：`cd /c/Users/xxx/your-project`
• ⬜ 运行 comet init 运行 `comet init`，勾选平台（Claude Code / Qoder / Trae）、scope、语言
• ⬜ 运行 comet doctor 运行 `comet doctor` 验证健康

实际开发

• ⬜ 在 AI 工具里输入 /comet-open 在 AI 工具里输入 `/comet-open` 开始一个 change
• ⬜ （可选）输入 /comet （可选）输入 `/comet` 查看当前阶段
• ⬜ 按 open → design → build → verify → archive 推进
• ⬜ 中途关闭后，输入 /comet 中途关闭后，输入 `/comet` 即可断点恢复

进阶配置

• ⬜ 在 .comet/config.yaml 开启 context_compression: beta 在 `.comet/config.yaml` 开启 `context_compression: beta`（省 token）
• ⬜ 按需设置 auto_transition: false 按需设置 `auto_transition: false`（手动控制阶段切换）
• ⬜ 加 .gitattributes 加 `.gitattributes` 强制 sh 用 LF 换行

本指南基于 Comet 官方 README 整理，版本 0.3.7+（2025 年）。 官方仓库：https://github.com/rpamis/comet