Skip to main content
关于 /comet 按项目配置进入经典 Spec 模式后，五阶段工作流、状态、守卫和预设的常见问题。

​
基础概念

Comet 不替代任何一方。OpenSpec 负责 WHAT（需求、提案、spec 生命周期、归档），Superpowers 负责 HOW（brainstorming、技术设计、计划、执行、验证）。Comet 把两者串成一条可恢复的五阶段工作流，并用状态机和守卫保证交接可靠。详见工作流概念。
用户统一调用 /comet；项目配置选择 Classic 后，内部永久入口 /comet-classic 驱动 open/design/build/verify/archive 五阶段流程。/comet 是项目配置驱动的统一别名，可能进入 Native 或 Classic。/comet-any 是 Skill Creator，用来创建、优化、组合可复用的 Skill；三者职责不同。
经典 Spec 模式依赖两者——OpenSpec 记录需求规格，Superpowers 提供设计/执行方法论。使用 comet init --workflow classic 时会安装两者；新的项目级 comet init 默认使用不依赖它们的 Native。如果你只想用 Comet 的 Skill 平台能力（用 /comet-any 组合任意 Skill，生成可验证、可评审、可分发的 Skill Bundle），可以从组合任意 Skill 快速上手开始。

​
与相似产品的区别

两者都想把 OpenSpec 和 Superpowers结合成一条工作流，但实现形态和保障级别完全不同。superpowers-bridge 是一个 OpenSpec 原生 schema bundle：你把它拷进项目当前 OpenSpec 根目录的 schemas/（Classic 新项目默认是 docs/openspec/schemas/，保留旧布局的项目是 openspec/schemas/），用 --schema superpowers-bridge 按 change 选择。它是纯 prompt 层集成——不改 Superpowers 源码、不改 OpenSpec CLI，靠 schema.yaml 里的制品 DAG（brainstorm → proposal → design → specs → tasks → plan → verify → retrospective）和散文 PRECHECK 约束顺序。它还补了一个 Superpowers 原生缺失的、以证据为先的 retrospective 制品。Comet 是一个独立的 npm 包（@rpamis/comet），带跨平台 Node runtime、.comet.yaml 状态机、hook 硬拦截、诊断和恢复。两者核心差异：
相对 superpowers-bridge 这类纯 schema 集成，Comet 的优势集中在四点：
  1. 可恢复的状态机：.comet.yaml 显式记录 phase、build_mode、tdd_mode、review_mode，长任务或上下文压缩后能精确恢复断点，而不是靠”哪些制品文件已存在”倒推。
  2. 硬性执行防线：Comet 有 comet-hook-guard.mjs（PreToolUse hook）做硬拦截，加上每轮注入的 phase-guard 规则——比如 design 阶段禁止写源码、非法空跳阶段会被拦下。纯 schema 的 PRECHECK 只是散文，模型可以”读到但不执行”。
  3. 入口健壮 + 跨平台：意图路由能从任意用户输入路由到阶段，不存在”只有走 /opsx:* 才生效、自然语言触发就漏气”的前门问题；且不强制 subagent 平台。
  4. 不只是工作流，是 Skill 平台：/comet-any 组合任意 Skill、comet eval 评估本地 Skill、comet dashboard 可视化每个 change，范围超出单一开发工作流。
如果你只想在 OpenSpec 里加一层 Superpowers 且不介意手动驱动，superpowers-bridge 更轻量；要长任务可恢复性、防漂移强约束、多平台和 Skill 平台能力，Comet 更合适。想了解 Comet 的运行时、工作流、评估和 Skill 创作分别对应哪些业界实践，可以进一步阅读 Comet 与业界实践对照。

​
状态与恢复

Comet 不依赖聊天历史。每次调用 /comet 并由配置进入 Classic 后，内部 /comet-classic 都会重新读取活跃 change 的 .comet.yaml 和 OpenSpec artifacts，判断当前阶段和证据是否一致，然后路由到正确的阶段 Skill。
这个 change 可能是用原始 /opsx:new 创建的，缺少 .comet.yaml，会被 comet status 静默跳过。在 Agent 平台调用 /comet 并由配置进入 Classic 让它接管补上状态文件。详见存量项目接入的”孤儿 change”。
用户可见字段（workflow、phase、build_mode 等）原则上通过 /comet-classic 和阶段守卫流转，不要手工改 phase。machine-owned Run 字段（在 .comet/run-state.json 或 .comet/runs/<run-id>）绝对不要手工改。排障时可以用 comet-state 命令，详见状态管理。
design 阶段写了 brainstorm-summary.md 作为恢复检查点，build 阶段的子代理有持久化 checkpoint。恢复时调用 /comet；配置进入 Classic 后，内部路由会从文件状态恢复而不是靠记忆。详见恢复中断的工作。

​
阶段与守卫

Comet 的核心原则是 brainstorming 不可跳过（hotfix/tweak 预设除外）。完整工作流的 guard 会检查 design_doc 是否存在，缺失会 FATAL。跳过设计会导致后续阶段缺乏技术依据。
不要直接归档。Comet 会让你选择：修复后回 build、接受偏差（在 design doc 追加说明）或退回重新 brainstorming。verify_result: fail 时归档会被 guard 阻止。
阶段推进由 guard 脚本 comet-guard.mjs --apply 完成。auto_transition: true（默认）时，一个阶段完成后自动调用下一个阶段 Skill；auto_transition: false 时暂停，按 HINT 手动运行。阶段推进本身一定发生，这个设置只影响是否自动调用下一个 Skill。
说明 design 阶段生成 handoff 后，OpenSpec artifacts（proposal/design/tasks/spec）被修改了。解决方法是重新运行 comet-handoff 让 Superpowers 拿到当前 OpenSpec 上下文。详见工作流概念的”产物如何交接”。

​
轻量预设与大需求

两者都跳过完整 brainstorming，保留 OpenSpec 状态、验证和归档。hotfix 适合复现路径明确的 bug 修复；tweak 适合范围明确的小改动。出现跨模块协调、新 public API、schema 变更时应升级 full。详见hotfix 预设。
/comet-open 会在创建 artifacts 前触发 PRD 拆分预检，把大需求拆成多个可独立设计、交付、归档的 change。详见大型 PRD 拆分。
review_mode（off/standard/thorough）控制 build 和 verify 阶段的自动代码审查强度。full workflow 必须在离开 build 前选择；hotfix 默认 off。可在 .comet/config.yaml 的 classic.review_mode 设置项目默认值。

​
常见问题

自动提交为Superpowers源码行为，您可以让AI为你生成拦截git commit的hook或rule来防止该行为发生。
先让 Agent 停下，不要继续写代码。然后按你实际做过什么处理：
  • 你改了 spec、design 或 tasks：直接再次调用 /comet。配置进入 Classic 后，Comet 会重新读取 .comet.yaml 和 OpenSpec artifacts，按当前 phase 恢复到正确阶段。
  • 你自己改了代码：也再次调用 /comet，并告诉 Agent：“我改过代码，请按当前工作区恢复。” Comet 会按 dirty-worktree 协议检查并归因未提交改动。
如果 spec 和代码都改了，也先用 /comet 恢复。你需要说明这些改动是否代表新方案；不要手工改 .comet.yaml 的 phase 或 .comet/run-state.json。Comet 以当前文件状态和持久化 artifacts 为准，而不是靠聊天记忆继续。
Comet Full流程为复杂需求/功能所需，会经过多轮澄清，以及可选的TDD执行和Review，过程较为严格，因此Token消耗较快。如果需要轻量快速的交付请使用comet-tweak和comet-hotfix预设。对于小需求/功能，也可以通过Plan或/loop替代。
最后修改于 2026年8月21日