跳转到主要内容
/comet 的核心能力之一是自动推进——它能检测当前在哪个阶段、推进状态、衔接下一个阶段 Skill,而不需要你手动记住”现在该做什么”。本页解释这个机制的完整工作方式。

​
阶段推进 vs 自动衔接

理解自动推进,首先要区分两个容易被混淆的概念:
概念谁做做什么受 auto_transition 影响
阶段推进guard --apply更新 .comet.yaml 的 phase 字段否,始终发生
自动衔接comet-state next决定是否自动调用下一个阶段 Skill是
阶段推进一定发生——guard 的 —apply 总是更新 phase。auto_transition 只控制是否自动调用下一个 Skill,不影响 phase 推进。用户决策点无论 auto_transition 取何值都必须阻塞。

​
自动检测怎么工作

每次调用 /comet,Comet 不依赖对话历史,而是重新读取文件状态判断当前阶段。

​
Step 0：发现活跃 change

  1. Preset 检测（优先级最高）——命中 hotfix/tweak 时直接调用对应 preset skill
  2. 未命中 preset 时运行 openspec list --json 获取所有活跃 change
  3. 按 change 数量和用户输入决定行为:
活跃 change用户输入行为
无非 preset调用 /comet-open
1 个/comet <描述>询问：继续还是创建新
多个/comet <描述>询问：继续还是创建新；选继续则列出清单选择
1 个/comet（无描述）自动选中
多个/comet（无描述）列出清单让用户选择

​
Step 1：读取状态

优先读 openspec/changes/<name>/.comet.yaml。不存在时回退到 openspec status、tasks.md 和 docs/superpowers/ 文件检查。

​
Step 2：阶段判定

按以下顺序判断,命中即停（以文件状态为准,冲突时修正 .comet.yaml）:
判定条件路由到
archived: true 或已移入 archive流程已完成
verify_result: pass/comet-archive（先做归档前确认）
verify_result: fail验证失败决策阻塞点
phase: verify 或 tasks 全部勾选/comet-verify
phase: build 或有 Design Doc 但执行未完成hotfix→/comet-hotfix、tweak→/comet-tweak、full→/comet-build
phase: design 或有 change 无 Design Doc/comet-design
phase: open 或有活跃 change 无 .comet.yaml/comet-open
无活跃 change/comet-open

​
状态转换

阶段推进通过 guard --apply 或 comet-state transition 完成: 
# guard 推进（退出阶段 Skill 时调用）
node "$COMET_GUARD" <change-name> <phase> --apply

# 直接表达状态事件
node "$COMET_STATE" transition <change-name> open-complete
node "$COMET_STATE" transition <change-name> design-complete
node "$COMET_STATE" transition <change-name> build-complete
node "$COMET_STATE" transition <change-name> verify-pass
node "$COMET_STATE" transition <change-name> verify-fail
转换链: 
open-complete → design-complete → build-complete → verify-pass → archived
                                                      ↑
                                              verify-fail（回到 build）

​
自动衔接：next 命令

阶段推进后,运行 next 解析下一步: 
node "$COMET_STATE" next <change-name>
输出格式: 
NEXT: auto|manual|done
SKILL: <skill-name>     # done 时省略
HINT: <message>         # 仅 manual 时
输出含义触发条件
NEXT: auto自动调用下一阶段 Skillauto_transition 不是 false
NEXT: manual不调用下一 Skill,打印 HINT 让用户手动运行auto_transition: false
NEXT: done流程已完成archived: true

​
Skill 路由

next 根据 phase 和 workflow 决定下一个 Skill:
phasefullhotfixtweak
open/comet-design/comet-build(→/comet-hotfix)/comet-build(→/comet-tweak)
design/comet-build——
build/comet-verify/comet-verify/comet-verify
verify/comet-archive/comet-archive/comet-archive
verify 和 archive 阶段不受 workflow 类型影响,始终返回标准 Skill。

​
连续执行

单次 /comet 调用从检测到的阶段开始,退出条件满足后自动推进后续阶段。 
/comet
  ↓ 自动检测
/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
自动推进只适用于没有用户决策的衔接点。 遇到停顿点时必须暂停等待用户确认,不能用推荐规则、默认值或历史偏好代替。

​
auto_transition 配置

auto_transition 控制是否自动调用下一个 Skill。配置优先级: 
change 级 .comet.yaml > 环境变量 > 项目级 .comet/config.yaml > 默认值(true)
值行为
true（默认）NEXT: auto,自动调用下一 Skill
falseNEXT: manual,打印 HINT,由你手动运行

​
什么时候用 false

  • 想在阶段之间插入人工审核
  • 每个阶段完成后需要换模型或换人
  • CI/CD 场景需要逐步控制
# 环境变量临时覆盖
export COMET_AUTO_TRANSITION=false

​
preset 升级

hotfix/tweak 执行过程中,如果命中升级信号,会暂停让你二选一:
信号类型触发决策
质变信号跨模块协调、新增 capability、schema 变更、新 public API、深层架构问题命中任一即暂停
文件数 tripwire改动文件数超阈值暂停交用户决定
选项结果
继续 preset 轻量流程继续当前 preset
升级为完整 /comettransition preset-escalate → 回退到 design → 补 Design Doc → 回到完整流程
preset-escalate 是 preset→full 升级的唯一合法通道——原子地设 workflow/classic_profile 为 full,回退 phase 到 design,清除 design_doc。

​
断点恢复

上下文压缩或会话中断后,/comet 重新读取文件状态恢复:
场景恢复行为
phase: build + build_pause: plan-ready + 已设 isolation/build_modestale pause,自动清除并继续
phase: build + build_pause: plan-ready + 未设 isolation/build_mode回到 plan-ready 恢复点
phase: build + build_pause: plan-ready + plan 缺失状态损坏,重新生成 plan
phase: verify + verify_result: fail进入验证失败决策阻塞点
phase: open + artifacts 已完整先 guard --apply 修正状态再判定
phase: archive只允许调用 /comet-archive
断点恢复不依赖对话历史——每次都重新执行 Step 0 和 Step 1。

​
红旗清单

Comet 的自动推进有明确的边界。以下想法出现时必须停下检查:
Agent 心理实际风险
”用户应该会同意这个方案”不能替用户决策,必须等待明确选择
”这只是个小改动,不需要确认”决策点无大小之分
”用户之前选过 A,这次也选 A”历史偏好不能替代当前确认
”流程走到这里应该没问题了”验证不通过不等于通过,检查 verify_result

​
下一步