前言

博客：http://blog.healerjean.com

官方文档：https://docs.comet.rpamis.com

一、认识 `Comet`

1、`Comet` 是什么

Comet 官方定位是 Agent Skill Harness——把想法变成可评估工作流的 Skill 骨架。

一句话概括：把 AI 编程从”一次会话搞定一切”拉回到”可恢复、可验收、可归档的工程流水线”上。

在没有 Comet 之前，用 Claude Code 之类的 AI Agent 干活常见的问题是：

上下文一断就丢：会话被压缩或换机器后，AI 不知道自己上次做到哪
AI 自己声明完成：写完就说”已完成”，但没跑测试、没查漏项，用户被迫二次验收
阶段之间随意漂移：本该在设计阶段的事，AI 直接跳到写代码；本该测试的时候直接归档
规格与实现脱节：OpenSpec 定义好的 spec 和 Superpowers 写出来的代码，缺少绑定机制

Comet 用三个东西把这些漏洞堵上：

机制	作用
`Workflow`（工作流）	强制五阶段（或四阶段）线性推进，每阶段有明确产物
`Guard` + `Hook`（阶段守卫）	拦截跨阶段写入，`AI` 不能自己跳步
`State`（状态机）	用 `YAML/JSON` 文件持久化阶段、handoff hash、验收结果，随时可恢复

2、`Comet`、`OpenSpec`、`Superpowers` 三者关系

简单一句话：Comet 是”骨架”，OpenSpec 管规格，Superpowers 管执行。三者不是竞争关系，而是分工合作。

┌─────────────────────────────────────────────┐
│                    Comet                    │
│   （阶段守卫 · 状态机 · Handoff · Skill 索引）│
├─────────────────────────────────────────────┤
│  OpenSpec               Superpowers         │
│  ───────                ───────────         │
│  · proposal.md          · brainstorming     │
│  · design.md            · writing-plans     │
│  · tasks.md             · TDD               │
│  · specs/*.md           · subagent-driven   │
│  · archive              · code-review       │
└─────────────────────────────────────────────┘

Comet 定义了两条独立的工作流：

Native 与 Classic 不是轻量版和重量版的关系，也不会互相升级——它们服务的是不同强度的模型和不同类型的任务

Native 工作流：只用 Comet Runtime，不加载 OpenSpec / Superpowers，靠模型自己调查、实现、自测
- 适用对象：能够自主完成复杂代码推理的强模型（如 GPT-5.6 等）。
- 核心逻辑：仅提供结构化 Brief 和目标规格，把具体的计划、实现、测试与审查方法完全交由模型自主判断。
- 产物目录：使用独立可配置的 comet/ 根目录，不依赖外部 Skill。
Classic 工作流：完整加载 OpenSpec + Superpowers，五阶段各自有明确归属方，HITL（Human-In-The-Loop）确认点密度高
- 适用对象：需要明确方法和强约束的复杂、长程任务。
- 核心逻辑：通过状态机、阶段检查与脚本串联五阶段流程（open → design → build → verify → archive）。
- 产物目录：结合 OpenSpec 和 Superpowers 技能集运作。 [1, 2, 3]

3、`Native` vs `Classic` 对比表

维度	`Native`	`Classic`
阶段	4 阶段：`Shape → Build → Verify → Archive`	5 阶段：`Open → Design → Build → Verify → Archive`
依赖	只依赖 `Comet Native Runtime`	依赖 `OpenSpec + Superpowers + CodeGraph`
适用模型	强模型：`Fable 5`、`GPT-5.6` 等	通用模型，或需要严格流程的大改动
决策归属	用户只管”用户可见结果、默认行为、兼容性、范围、风险、不可逆改动”	每阶段都有 HITL 确认点，用户参与更密集
完成判定	`Runtime` 派发独立 `Verifier`，模型不能自报通过	双方（`OpenSpec` + `Superpowers`）联合验证
产物根目录	默认 `docs/comet/`（可配）	默认 `docs/openspec/` + `docs/superpowers/`
澄清模式	`sequential` / `batch` 可选	由 `brainstorming skill` 苏格拉底式一问一答
是否装 `OpenSpec`/`Superpowers`	否	是（`comet init` 时自动装）

4、安装与初始化

1）前置要求

Node.js 22+
npm 或 npx
Git
支持的 AI 编码平台之一：Claude Code / Codex / Cursor / Gemini CLI / OpenCode / ZCode / Windsurf / Antigravity / GitHub Copilot / Trae 等（官方支持 34 个）

2）全局安装 `CLI`

npm install -g @rpamis/comet

# 验证
comet --version

3）项目初始化

进入项目根目录：

comet init

向导会问你两个问题：

Skill 语言：en 或 zh-CN
目标平台：从检测到的 AI 编码工具中选（可多选）

默认使用 Native 工作流。生成的文件：

.comet/
├── config.yaml          # 项目配置
comet/                   # Native 工作区根（默认）

显式指定工作流的常用参数：

# Native 工作流，产物写到 docs 目录
comet init --workflow native --root docs

# Classic 工作流（会同时安装 OpenSpec + Superpowers + CodeGraph）
comet init --workflow classic

# 两种都装
comet init --workflow both

# 全局安装（对所有项目生效）
comet init --scope global --workflow both

4）验证安装

comet doctor           # 健康检查
comet doctor --repair  # 自动修复常见问题
comet status           # 查看当前工作流状态

5）第一个命令

在你的 AI 编码工具（比如 Claude Code）里输入：

/comet 实现用户资料页的头像上传能力

/comet 会读 .comet/config.yaml，根据 default_workflow 转发到 /comet-native 或 /comet-classic，然后进入对应的阶段循环。

二、`Native` 工作流：强模型 · 全自动 `Coding`

1、核心理念

面向 Fable 5、GPT-5.6 这类强模型：模型自己调查代码、选实现、写测试，但完成判定不能自报——Runtime 会执行必要检查，并派发一个全新的、只读的 Verifier 逐项核验验收条目。

关键词：Loop Engineer、独立 Verifier、只读 Runtime、决策边界。

2、`Shape → Build → Verify → Archive` 四阶段

/comet-native（或 default_workflow: native 时的 /comet）
  Shape  ──确认需求──>  Build  ──Builder 交接──>  Verify  ──验证通过──>  Archive
                           ^                              │
                           └──────── 验证失败 ────────────┘

阶段	主要工作	必要结果
Shape	调查环境、逐轮澄清、编写 brief 和每个 capability 的完整目标规格	无阻塞问题，用户确认当前目标
Build	Agent 自主规划、实现和自测，完成后提交简短 Builder 交接	每项验收都有实现说明，普通源码写入只发生在 Build
Verify	Runtime 运行必要检查，并分派新的只读 Verifier 逐项验收	通过后进入 Archive；失败返回 Build，并携带明确的修复项
Archive	同步完整目标规格并移动 change；正常路径不重复运行 Build 或 Verify 的检查	归档事务完整提交

1）`Shape`：固定目标与用户决定

做什么：

调查仓库事实（读代码、看文档、扫描相关模块）
澄清用户意图（sequential 逐问或 batch 打包问一次）
产出 brief.md（一句话目标 + 关键约束 + 非目标）
产出完整的 target Specs（验收场景 A1..An）
用户确认

决策边界：

用户来定	模型自主
用户可见结果	实现结构
默认行为	库选择
兼容性	测试方式
范围	修复方式
风险 / 不可逆改动	内部结构变动

2）`Build`：模型自主实现

做什么：

以 brief.md + Specs + 仓库规则为边界
模型自己写代码、跑测试、修 bug
遇到”新的产品决定”（比如需要引入新的用户可见字段） → 回到 Shape
遇到”实现缺口” → 进入下一轮 Build
结束时提交 Builder handoff（一份自述报告 + 已跑的检查证据）

关键约束：模型不能自报”完成”，只能说”我实现完了，请验证”。

3）`Verify`：`Runtime` 检查 + 新 `Verifier`

做什么：

Runtime 解析 Specs，执行必要的静态/动态检查，日志留在本机
派发一个全新的只读 Verifier agent（不带 Build 阶段上下文），逐项核验 A1..An
Verifier 必须给出每一条验收项的通过/失败结论
可用 request-checks 追加检查
如果没有独立 Verifier 可用（比如平台限制），Runtime 会标记降级并等用户确认

为什么要新起一个 Verifier？ 防止 Build 阶段的自证偏见——已经写了代码的 agent 倾向于说”我写对了”。

4）`Archive`：只应用最终结果

做什么：

写入 verification.md（最终验收报告）
按 Specs 更新 canonical 文档
移动 change 到归档目录
清理 .comet/runtime/native/ 下的运行时状态

关键约束：Archive 阶段不会重复运行检查，它只是应用 Verify 阶段的结论。

3、澄清模式（`Clarification`）

Native 支持两种问询节奏，写在 .comet/config.yaml 的 native.clarification_mode：

模式	行为	适用场景
`sequential`	一次只问一个问题，答完再问下一个	需求模糊、你想边聊边想清楚
`batch`	打包一次问完所有问题	需求已经比较清楚，只是要补齐几个细节

新项目默认 batch。

4、产物与状态文件

1）用户可见产物

docs/comet/
├── changes/<change-name>/
│   ├── brief.md              # Shape 阶段一句话目标 + 约束
│   ├── specs/                # target Specs（含 A1..An 验收场景）
│   ├── verification.md       # Verify 阶段的最终报告
│   └── comet-state.yaml      # 阶段、Loop 计数、handoff、Verifier 结论
├── specs/                    # canonical Specs（归档后同步）
└── archive/                  # 归档目录

2）本机运行时目录（归档后清理）

.comet/runtime/native/
├── state.json                # Runtime 引擎状态
├── logs/                     # 运行日志
├── locks/                    # 并发锁
└── transactions/             # 事务

3）恢复机制

comet-state.yaml 保存了：阶段、Loop 计数、验收摘要、handoff、检查摘要、Verifier 结论、阻塞点、有限历史。跨设备恢复时：从 YAML 重建状态；但如果代码、artifact root、branch 不匹配，Comet 会暂停等用户确认，不会自动覆盖。

5、端到端示例：给用户资料页加”头像上传”

# 1. 在 Claude Code 里发起
/comet 给用户资料页加头像上传能力

# 2. Comet 读 .comet/config.yaml，default_workflow=native → 转发到 /comet-native

# 3. Shape 阶段
AI 调查仓库，发现：
  - 已有 UserProfile 组件
  - 已有 /api/user/upload/* 接口约定
  - 没有前端上传组件

AI 问（sequential 模式）：
  Q1: 图片大小限制？（1MB / 5MB / 10MB）
  Q2: 支持格式？（JPG/PNG/WebP）
  Q3: 是否需要裁剪？
  Q4: 上传后立即预览还是保存后预览？

用户答完 → AI 产出：
  docs/comet/changes/avatar-upload/brief.md
  docs/comet/changes/avatar-upload/specs/A1-upload.md
  docs/comet/changes/avatar-upload/specs/A2-validation.md
  ...

用户点头 → 进入 Build

# 4. Build 阶段
AI 自主：
  - 挑选 react-image-crop 库
  - 写 <AvatarUploader> 组件
  - 写单测
  - 跑测试
  - 提交 Builder handoff:
    "已实现 A1-A5，跑了 12 个测试全绿，请验证"

# 5. Verify 阶段
Runtime:
  - 执行 npm run test → 12 passed
  - 执行 npm run typecheck → 0 error
  - 派发独立 Verifier（新会话，只读）

Verifier 逐项核验：
  A1 上传：PASS（有 e2e 测试）
  A2 验证：PASS（拦截了 6MB 文件）
  A3 裁剪：PASS
  A4 预览：FAIL（预览是保存后才出现，需求是上传后立即预览）
  A5 错误提示：PASS

# 6. Runtime 报告失败 → 回到 Build
AI 修 A4 → 重新提交 handoff → Verify 再跑

# 7. 全绿 → Archive
verification.md 写入
canonical Specs 更新
change 移到 archive/
运行时目录清理

三、`Classic` 工作流：`Spec` 驱动 · 更多 `HITL`

1、核心理念

Classic 把 OpenSpec 和 Superpowers 连成一条可恢复的链路。每一阶段有明确的归属方、明确的输入产物、明确的确认点。适合大改动、跨模块、对 spec 严格追溯的场景，也适合还没达到”强模型”级别的 AI 使用。

关键机制：handoff_hash——把 OpenSpec 生成的 artifacts（proposal.md / design.md / tasks.md）用 SHA-256 绑定到后续阶段。离开 design 时如果 hash 漂移，直接 FATAL；verify 用 --hash-only 快速判断是否需要全文重读。

2、五阶段全景与归属表

/comet-classic（或 default_workflow: classic 时的 /comet）
  ↓
/comet-open  -->  /comet-design  -->  /comet-build  -->  /comet-verify  -->  /comet-archive
(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)

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

/comet-tweak（轻量预设路径，串联 OpenSpec）
  open  -->  build  -->  verify  -->  archive

阶段	命令	归属方	关键产物
`open`	`/comet-open`	`OpenSpec`	`proposal.md`、`design.md`、`tasks.md`、delta spec、`.comet.yaml`、`.openspec.yaml`
`design`	`/comet-design`	`Superpowers`（`OpenSpec` 保权威）	`docs/superpowers/specs/...-design.md`、`handoff` 包（含 `handoff_hash`）
`build`	`/comet-build`	`Superpowers`	`docs/superpowers/plans/...md`、代码改动、测试证据
`verify`	`/comet-verify`	双方	验证报告、`branch_status: pending`
`archive`	`comet-archive.mjs`	`OpenSpec`	`changes/archive/YYYY-MM-DD-<name>/`、design doc 加 `status: final`

3、`open`：`OpenSpec` 记录 `WHAT`

做什么：把想法翻译成结构化的 OpenSpec change。

产物：

docs/openspec/changes/<change-name>/
├── proposal.md          # 一句话提议 + 目标 + Non-Goals
├── design.md            # 高层设计（决策、备选、风险）
├── tasks.md             # 任务清单（会作为 build 的活文档）
├── specs/
│   └── <capability>/
│       └── spec.md      # delta spec（验收场景）
├── .comet.yaml          # 工作流阶段与执行方式
└── .openspec.yaml       # OpenSpec 生命周期

关键规则：

用 /comet-open，不要用 /opsx:new——后者会让 change 落在 Comet 状态机之外，后续 guard、archive 都拦不住
完整工作流禁止跳过 brainstorming 直接一次性生成提案

4、`design`：`Superpowers` 深度设计

做什么：把 OpenSpec 的 WHAT 翻译成 HOW。

输入：open 阶段的所有 artifacts，通过 comet-handoff.mjs 生成交接包（handoff.json + handoff_hash）。

产物：

docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md

Design Doc 的 frontmatter 必须声明：

---
canonical_spec: openspec
handoff_hash: sha256:abc123...
---

关键约束：

Agent 不能写第二份需求 spec——OpenSpec 是唯一权威
如果设计过程中发现需求要补充 → 只能通过 Spec Patch 回写到 OpenSpec，不能在 Design Doc 里偷偷加需求

5、`build`：`Superpowers` 执行

做什么：把 Design Doc + tasks.md 变成代码。

执行方式（build_mode）：

模式	说明	适用
`subagent-driven-development`	每个 task 分派新 subagent，实现→审查→修复循环	复杂多模块任务，推荐
`executing-plans`	主 agent 按计划逐步推进	平台不支持 subagent 时的备选
`direct`	直接干，不走 `plan/task` 拆分	`hotfix` / `tweak` 预设默认

其他执行控制字段：

isolation：current / branch / worktree——是否隔离工作区
tdd_mode：是否强制 Red-Green-Refactor
review_mode：off / standard / thorough——每个 task 后的代码审查粒度
context_compression：off / beta——是否启用上下文压缩（见第六章）

产物：

docs/superpowers/plans/YYYY-MM-DD-<topic>-plan.md   # 任务分解
<repo>/**                                             # 实际代码改动
tests/                                                # 测试证据

6、`verify`：双方联合验证

做什么：验证实现是否符合 Design Doc 和 Spec。

两种模式（verify_mode）：

模式	检查项	何时用
`light`	6 项：任务完成、diff 对比、构建、测试、安全、轻量代码评审	日常改动
`full`	`light` + `openspec-verify-change`（检查 delta spec 与 `Design Doc` 是否矛盾）	大改动、关键变更

spec 漂移决策（当发现 delta spec 与 Design Doc 不一致时）：

A：追加 Implementation Divergence 段，说明偏差原因
B：回到 build 重新对齐
C：接受偏差，archive 时同步 spec

verify 阶段结束后 branch_status 保持 pending——不会自动合并，等你手动 archive。

7、`archive`：`OpenSpec` 归档

做什么：把 delta spec 同步到 canonical spec，change 归档。

前置条件：

phase = archive
verify_result = pass

入口：

node "$COMET_ARCHIVE" <change-name>
# 内部委托给：openspec archive --yes

产物：

docs/openspec/changes/archive/2026-08-18-<change-name>/
├── proposal.md
├── design.md
├── tasks.md
└── specs/

同时：

design.md 加 status: final
design.md 和 plan.md 都加 archived-with: <archiveName>

关键警告：归档成功后不要再跑 comet-guard <name> archive——Guard 会以为你要重新进入 archive，产生冲突。

8、轻量预设：`/comet-hotfix` 与 `/comet-tweak`

两个预设都跳过 brainstorming 和 Design Doc，走 open → build → verify → archive 四步。默认设置相同：

build_mode: direct
tdd_mode: direct
review_mode: off
verify_mode: light

预设	定位	delta spec	独有步骤
`/comet-hotfix`	修 bug、不新增 capability	例外——仅当修改了已有 spec 的验收场景	Step 3 根因消除检查
`/comet-tweak`	调整行为或内容	一等公民产物	无

升级机制：如果检测到”跨模块改动 / 新增 capability / DB schema 改动 / 新公开 API / 深度架构问题”，Comet 会暂停让你选择：

继续用 hotfix / tweak
升级到 full（走完整五阶段）

文件数暗雷：改动文件超过约 4 个时也会暂停（不是硬阈值升级，只是让你确认）。

升级必须走正规通道：preset-escalate 转换命令，不能手工编辑 .comet.yaml——已完成的工作会被完整保留。

9、`Classic` 端到端示例：看板 CRUD

# ─────────────────  Step 1: open  ─────────────────
/comet 实现看板：Column 和 Task 的增删改查，后端 Go + SQLite，前端 React

Comet 路由到 /comet-classic → /comet-open：

OpenSpec 通过 brainstorming skill 一问一答：
  Q1: 部署方式？（本地 / 云 / 二者都要）
  Q2: 是否需要多用户？
  Q3: Task 需要哪些字段？

产出：
  docs/openspec/changes/kanban-crud/
  ├── proposal.md          # Non-Goals: 不做拖拽、不做实时同步
  ├── design.md            # 三层架构：SQLite / Go REST / React SPA
  ├── tasks.md             # 6 个 task
  ├── specs/
  │   ├── column/spec.md   # A1-A4：Column CRUD 验收
  │   └── task/spec.md     # B1-B5：Task CRUD 验收
  ├── .comet.yaml          # phase: open
  └── .openspec.yaml

用户审查 → 通过 → 阶段推进到 design

# ─────────────────  Step 2: design  ─────────────────
/comet-design 或 auto_transition=true 自动进入

comet-handoff.mjs 生成 handoff.json + handoff_hash

Superpowers brainstorming 深度设计：
  - 数据库表结构
  - API 路由与错误码约定
  - 前端组件树
  - 测试策略

产出：
  docs/superpowers/specs/2026-08-18-kanban-design.md
  frontmatter:
    canonical_spec: openspec
    handoff_hash: sha256:8f2c3d...

用户审查 → 通过 → 阶段推进到 build

# ─────────────────  Step 3: build  ─────────────────
/comet-build

.comet.yaml:
  build_mode: subagent-driven-development
  isolation: worktree
  tdd_mode: strict
  review_mode: standard

主 agent 读 tasks.md → 拆成 6 个 subagent 任务：
  Task 1: DB schema + models
  Task 2: Column API
  Task 3: Task API
  Task 4: React 组件
  Task 5: 前后端联调
  Task 6: e2e 测试

每个 subagent：
  RED: 写失败测试 → GREEN: 最小实现 → REFACTOR: 优化
  实现完提交 → 派 reviewer subagent 审查
  Critical/Important 问题 → 派 fixer subagent 修复
  最终 → 标记 task 完成

所有 task 完成 → 阶段推进到 verify

# ─────────────────  Step 4: verify  ─────────────────
/comet-verify (verify_mode: light)

Runtime 跑 6 项检查：
  ✓ tasks.md 全部勾选
  ✓ diff 与 plan 一致
  ✓ go build / npm build 通过
  ✓ go test / npm test 全绿
  ✓ 无高危依赖
  ✓ 轻量代码评审 0 个 Critical

verify_result: pass
branch_status: pending  (不自动合并！)

# ─────────────────  Step 5: archive  ─────────────────
node "$COMET_ARCHIVE" kanban-crud

产出：
  docs/openspec/changes/archive/2026-08-18-kanban-crud/
  canonical spec 更新：
    docs/openspec/specs/column/spec.md    ← 从 delta 同步
    docs/openspec/specs/task/spec.md      ← 从 delta 同步
  design.md.frontmatter:
    status: final
    archived-with: 2026-08-18-kanban-crud

四、`CLI` 命令参考

1、常用命令

命令	作用
`comet init [path]`	项目初始化，可加 `--workflow` / `--scope` / `--platform` / `--language`
`comet status`	显示默认入口、`Native`/`Classic`/未管理的 `OpenSpec changes` 分组
`comet resume-probe`	只读恢复决策：告诉你能不能安全 resume，需要不需要重建
`comet dashboard`	启本地只读 Web `UI`（切换 `Classic` / `Native` 工作区看板）
`comet doctor`	诊断安装 / 配置完整性；`--repair` 自动修
`comet update`	刷新 `Skills`；`--self-update` 升级 `npm` 包本体
`comet uninstall`	移除 `Comet` 分发的 `skills` / `rules` / `hooks`

2、`Skill` 创作与评估

命令	作用
`comet creator`	引导创建新 `Skill`（`/comet-any` 是对应的 `Skill` 入口）
`comet eval [target]`	评估 `Skill`，支持 `--collect` / `--html` / `--quick` / `--suite langsmith`
`comet publish`	发布 `Skill` 到 `Comet` 生态
`comet bundle`	打包 `Skill` 分发

3、状态管理

命令	作用
`comet state select <name>`	多个活跃 `change` 时选定”当前”
`comet state current`	查看当前选定的 `change`
`comet state clear-selection`	清除选定
`comet state set <name> <field> <value>`	修改可写字段（机器字段不可改）

4、恢复中断的工作

最简单的做法——在项目里重开 Claude Code（或其他 AI 工具），输入：

/comet 继续

Comet 自动：

读 .comet/config.yaml 找默认工作流
读 .comet/current-change.json 找当前 change
从 comet-state.yaml（Native）或 .comet.yaml + run-state.json（Classic）重建阶段
从上次的证据接着往下走

五、`Hooks + Guard` 三层防漂移架构

这是 Comet 相对 OpenSpec / Superpowers 单用最大的技术差异——用平台的 Hook 机制拦截所有写入操作，把”AI 会自己遵守流程”这件不靠谱的事，变成”AI 想跳步也跳不了”。

1、三层结构

┌─────────────────────────────────────────────────────┐
│ Layer 1: Rule 层                                    │
│ 每个平台一个 comet-workflow-guard 规则              │
│ 声明"在什么阶段允许写什么路径"                       │
├─────────────────────────────────────────────────────┤
│ Layer 2: Hook 层                                    │
│ 一个 comet-hook-router.mjs 作为唯一 Hook 入口       │
│ 每次写文件前触发，路由到对应 Guard                   │
├─────────────────────────────────────────────────────┤
│ Layer 3: Guard 层                                   │
│ Native Guard 和 Classic Guard 各自维护              │
│ 独立的阶段状态和白名单路径                          │
└─────────────────────────────────────────────────────┘

2、`Guard` 的实际行为

假设你现在处于 Classic 的 design 阶段，AI 想 Write 一个 .go 源码文件。

AI 调 Write 工具，目标路径 internal/models/column.go
平台 Hook 触发 comet-hook-router.mjs
Router 检查 .comet/config.yaml，发现是 Classic
Router 委托给 Classic Guard
Classic Guard 读 .comet.yaml，看到 phase: design
Classic Guard 检查白名单：design 阶段只允许写
   - docs/superpowers/specs/**
   - docs/openspec/changes/<name>/**  (Spec Patch)
internal/models/column.go 不在白名单 → 拒绝
Router 返回错误："phase=design 不允许写代码文件，请先推进到 build 阶段"

AI 想跳步也跳不了——这是 Comet 的核心工程价值。

3、状态文件详解

1）`.comet/config.yaml`（项目级）

schema: comet.project.v1
default_workflow: classic        # /comet 转发目标
workflows:                       # 启用的工作流
  - native
  - classic
ambient_resume: true             # 是否允许自动恢复检测

native:
  artifact_root: docs            # Native 产物根目录
  language: zh-CN                # en / zh-CN
  clarification_mode: sequential # sequential / batch

classic:
  artifact_layout: docs          # legacy(openspec/) / docs(docs/openspec/)
  language: zh-CN
  context_compression: off       # off / beta
  review_mode: standard          # off / standard / thorough
  auto_transition: true          # 阶段完成后是否自动进入下一阶段

hook:
  allow_paths:                   # 保护阶段允许写入的项目相对路径
    - README.md
    - CHANGELOG.md

2）`.comet.yaml`（`Classic` change 级）

位于 <classic-root>/changes/<name>/.comet.yaml。核心字段分组：

# ── 工作流 / 阶段 ──────────────────
workflow: full                   # full / hotfix / tweak
language: zh-CN
phase: build                     # open / design / build / verify / archive
auto_transition: true

# ── 执行 ──────────────────────────
build_mode: subagent-driven-development
build_pause: false
subagent_dispatch: parallel
tdd_mode: strict
review_mode: standard
isolation: worktree
bound_branch: feat/kanban-crud
context_compression: off

# ── 验证 / 分支 ───────────────────
verify_mode: light
verify_result: pending           # pending / pass / fail
verify_failures: []
verification_report: ""
branch_status: pending
verified_at: null

# ── 路径 ──────────────────────────
design_doc: docs/superpowers/specs/2026-08-18-kanban-design.md
plan: docs/superpowers/plans/2026-08-18-kanban-plan.md
base_ref: main
direct_override: false

# ── 时间 / 归档 ───────────────────
created_at: 2026-08-18T09:15:00Z
archived: false
archive_confirmation: null

# ── 机器字段（勿改！）────────────
classic_profile: default
classic_migration: null
run_id: run_01H8XZM...

3）`.comet/run-state.json`（引擎运行状态）

位于 <changeDir>/.comet/run-state.json。机器所有，运行时自动写入。字段：currentStep / pending / trajectory / artifacts。不要手工改。

4）`.comet/state-events.jsonl`（审计日志）

追加型日志，每行一条 JSON：

{"schemaVersion":1,"timestamp":"2026-08-18T10:03:22Z","change":"kanban-crud","event":"build-complete","source":"comet state","from":{"phase":"build"},"to":{"phase":"verify"},"effects":["phase: build -> verify"]}

5）`.comet/current-change.json`（活跃 `change` 选择）

多个 change 同时活跃时，声明”当前是哪个”，消除写入歧义。用 comet state select 管理。

6）配置优先级（`Classic` 字段）

change 级 .comet.yaml
    > 环境变量（COMET_LANGUAGE / COMET_AUTO_TRANSITION / COMET_CONTEXT_COMPRESSION）
        > 项目 .comet/config.yaml
            > 全局语言默认
                > 内置默认

环境变量只在 change 级字段为空时生效。

4、辅助脚本

脚本	作用
`comet-guard.mjs`	阶段推进 `guard`，`--apply` 真正执行推进
`comet-handoff.mjs`	生成 `design` `handoff` 包，`SHA-256` 追溯
`comet-archive.mjs`	一键归档，委托 `openspec archive --yes`
`comet-yaml-validate.mjs`	校验 `YAML schema`
`comet-state.mjs`	统一状态管理
`comet-hook-router.mjs`	单一 `Hook` 入口（每平台一个）
`comet-native-runtime.mjs`	`Native` 状态 / 检查 / 归档 / 恢复

所有脚本都是 Node.js，不依赖 Bash / WSL——Windows 用户开箱即用。

六、进阶特性

1、`Context Compression`（`Beta`）

只在 Classic 的 design → build handoff 阶段生效。

是什么：把 proposal.md / design.md / tasks.md 用 SHA-256 哈希引用代替全文，只有 delta spec 保留原文（保证验收场景零漂移）。

收益（官方数据）：

指标	`off`（默认）	`beta`
测试通过率	100%	100%
规格覆盖	100%	95%
`Token` 节约	基线	~25-30%
大任务节约	—	最多 ~15,000 tokens

启用（项目级，推荐）：

# .comet/config.yaml
classic:
  context_compression: beta

启用（change 级，一次性）：

node "$COMET_STATE" set kanban-crud context_compression beta

注意：beta 模式下 --full 标志被忽略；如果哈希投影缺失或过期，重新生成，别让 agent 靠总结去猜。

2、`Auto Transition`

.comet.yaml 的 auto_transition: true 时，阶段完成后自动进入下一阶段——不需要手动 /comet-design、/comet-build。

强制暂停点（无论 auto_transition 如何）：

hotfix / tweak 需要升级到 full 时
任务数超过 3 时的工作区选择
verify 失败时
archive 前的最终确认

3、`Isolation Modes`

模式	行为
`current`	直接在当前工作区改，最快，冲突风险高
`branch`	建一个新分支，改完 `PR`，最常见
`worktree`	用 `git worktree` 建隔离目录，多任务并行时首选

4、`Review Mode`

模式	行为
`off`	不做代码审查（`hotfix` / `tweak` 默认）
`standard`	每个 task 完成后派 reviewer subagent，`Critical` / `Important` 必修
`thorough`	深度审查，含架构一致性、性能、安全、可维护性四维度

5、`Skill` 创作：`/comet-any`

Comet 内置了 Skill 创作 Skill——用 /comet-any 引导你走完 RED → GREEN → REFACTOR 循环创建一个新 Skill：

/comet-any 创建一个 "生成 README 徽章" 的 skill

→ RED: 设计 3+ 压力场景，验证 agent 没 skill 时会怎么错
→ GREEN: 写最小 SKILL.md，验证 agent 现在遵守
→ REFACTOR: 堵漏洞、加反驳表、构建红旗清单
→ comet eval 评估
→ comet publish 发布

评估维度：pass^N（连续通过 N 次的比例）、pass@N（N 次里至少通过一次的比例）。

6、性能数据

官方 0.4.0-beta.7 vs 0.4.0 Classic 对比（16 tasks × 48 runs，41 clean pairs）：

指标	0.4.0-beta.7（`Native`）	相对 `Classic`
`Token` 总量	降	-76.8%
`Agent` 轮次	降	-57.4%
耗时	降	-47.4%
`pass^3`	87.5%	—
`pass@3`	100%	—

要点：Native 明显更省 Token 和时间，Classic 换来的是严格的 HITL 追溯——不是升级关系，是选型关系。

七、`AI` 编程实战选型指南

1、我该用 `Native` 还是 `Classic`？

用 Native 的场景：

手上是 Fable 5 / Claude Opus 4.7+ / GPT-5.6 级别的强模型
单人开发，或需求边界你自己就能拿定主意
追求速度和 Token 效率
任务规模中小（一次 change 5 个文件以内）
不需要 spec 文档留档给团队评审

用 Classic 的场景：

团队协作，需求评审是流程的一部分
大改动（跨模块、DB 迁移、API 变更）
合规 / 审计要求可追溯的 spec
用中等强度模型（Sonnet 4.6 / GPT-4o）
需要严格的 TDD + 代码审查纪律

2、`Comet` vs 单用 `Superpowers` / `OpenSpec`

对比项	单用 `Superpowers`	单用 `OpenSpec`	`Comet`
`TDD` / 代码审查	✅	❌	✅（`Classic`）
结构化 `Spec`	❌	✅	✅（`Classic`）
阶段 `Guard`（跨阶段写入拦截）	❌	❌	✅
状态可恢复	部分（`SDD` 有 `progress.md`）	部分	✅（`YAML` + `JSON` 双备份）
`Handoff Hash` 绑定	❌	❌	✅
独立 `Verifier`	❌	❌	✅（`Native`）
跨平台（34 个）	Claude / Cursor 为主	通用	✅
上下文压缩	❌	❌	✅（`beta`）
`Skill` 评估体系	❌	❌	✅（`comet eval`）

3、`AI` 编程日常上手节奏

第 1 步（一次性）：

npm install -g @rpamis/comet
cd my-project
comet init --workflow both --language zh-CN
comet doctor

第 2 步（每次开新功能）：

/comet 我要做 XXX

Comet 自动路由到 Native 或 Classic，进入对应循环。你只在这些确认点介入：

Native：Shape 阶段答问题、Build → Verify 之间批准 handoff
Classic：每个阶段的 HITL 检查点

第 3 步（每次会话被压缩 / 换机器 / 隔天继续）：

/comet 继续

第 4 步（归档）：

Native 自动完成
Classic：node "$COMET_ARCHIVE" <change-name>

4、常见坑与避雷

坑	避雷
用 `/opsx:new` 而不是 `/comet-open`	`change` 会脱管，`guard` / `archive` 都不生效
归档后又跑一次 `comet-guard <name> archive`	状态冲突，只归一次
手工编辑 `.comet.yaml` 里的机器字段（`run_id` / `classic_profile`）	会破坏 `run-state.json` 引用，用 `comet state set`
在 `design` 阶段偷偷写”第二份需求 spec”	`Guard` 会拦；要补需求只能 `Spec Patch` 回 `OpenSpec`
`hotfix` 干着干着发现要跨模块改	不要手工改 `.comet.yaml`，走 `preset-escalate` 升级到 `full`
`Native` 用弱模型	`Verifier` 环节容易失败；弱模型请老实走 `Classic`
`Windows` 上装 `Superpowers` 需要 `Git Bash`	`Comet` 全 `Node.js` 脚本，无此要求

ContactAuthor

一、认识 Comet

1、Comet 是什么

2、Comet、OpenSpec、Superpowers 三者关系

3、Native vs Classic 对比表

4、安装与初始化

1）前置要求

2）全局安装 CLI

3）项目初始化

4）验证安装

5）第一个命令

二、Native 工作流：强模型 · 全自动 Coding

1、核心理念

2、Shape → Build → Verify → Archive 四阶段

1）Shape：固定目标与用户决定

2）Build：模型自主实现

3）Verify：Runtime 检查 + 新 Verifier

4）Archive：只应用最终结果

3、澄清模式（Clarification）

4、产物与状态文件

1）用户可见产物

2）本机运行时目录（归档后清理）

3）恢复机制

5、端到端示例：给用户资料页加”头像上传”

三、Classic 工作流：Spec 驱动 · 更多 HITL

1、核心理念

2、五阶段全景与归属表

3、open：OpenSpec 记录 WHAT

4、design：Superpowers 深度设计

5、build：Superpowers 执行

6、verify：双方联合验证

7、archive：OpenSpec 归档

8、轻量预设：/comet-hotfix 与 /comet-tweak

9、Classic 端到端示例：看板 CRUD

四、CLI 命令参考

1、常用命令

2、Skill 创作与评估

3、状态管理

4、恢复中断的工作

五、Hooks + Guard 三层防漂移架构

1、三层结构

2、Guard 的实际行为

3、状态文件详解

1）.comet/config.yaml（项目级）

2）.comet.yaml（Classic change 级）

3）.comet/run-state.json（引擎运行状态）

4）.comet/state-events.jsonl（审计日志）

5）.comet/current-change.json（活跃 change 选择）

6）配置优先级（Classic 字段）

4、辅助脚本

六、进阶特性

1、Context Compression（Beta）

2、Auto Transition

3、Isolation Modes

4、Review Mode

5、Skill 创作：/comet-any

6、性能数据

七、AI 编程实战选型指南

1、我该用 Native 还是 Classic？

2、Comet vs 单用 Superpowers / OpenSpec

3、AI 编程日常上手节奏

4、常见坑与避雷

一、认识 `Comet`

1、`Comet` 是什么

2、`Comet`、`OpenSpec`、`Superpowers` 三者关系

3、`Native` vs `Classic` 对比表

2）全局安装 `CLI`

二、`Native` 工作流：强模型 · 全自动 `Coding`

2、`Shape → Build → Verify → Archive` 四阶段

1）`Shape`：固定目标与用户决定

2）`Build`：模型自主实现

3）`Verify`：`Runtime` 检查 + 新 `Verifier`

4）`Archive`：只应用最终结果

3、澄清模式（`Clarification`）

三、`Classic` 工作流：`Spec` 驱动 · 更多 `HITL`

3、`open`：`OpenSpec` 记录 `WHAT`

4、`design`：`Superpowers` 深度设计

5、`build`：`Superpowers` 执行

6、`verify`：双方联合验证

7、`archive`：`OpenSpec` 归档

8、轻量预设：`/comet-hotfix` 与 `/comet-tweak`

9、`Classic` 端到端示例：看板 CRUD

四、`CLI` 命令参考

2、`Skill` 创作与评估

五、`Hooks + Guard` 三层防漂移架构

2、`Guard` 的实际行为

1）`.comet/config.yaml`（项目级）

2）`.comet.yaml`（`Classic` change 级）

3）`.comet/run-state.json`（引擎运行状态）

4）`.comet/state-events.jsonl`（审计日志）

5）`.comet/current-change.json`（活跃 `change` 选择）

6）配置优先级（`Classic` 字段）

1、`Context Compression`（`Beta`）

2、`Auto Transition`

3、`Isolation Modes`

4、`Review Mode`

5、`Skill` 创作：`/comet-any`

七、`AI` 编程实战选型指南

1、我该用 `Native` 还是 `Classic`？

2、`Comet` vs 单用 `Superpowers` / `OpenSpec`

3、`AI` 编程日常上手节奏