自动推进机制

用户正常调用 /comet。项目配置进入 Classic 后，内部 /comet-classic 会自动检测当前阶段、推进状态并衔接下一阶段 Skill；你不需要先判断“现在该做什么”。本页解释这个内部机制。

阶段推进 vs 自动衔接

理解自动推进，首先要区分两个容易被混淆的概念:

概念	谁做	做什么	受 auto_transition 影响
阶段推进	guard `--apply`	更新 `.comet.yaml` 的 `phase` 字段	否，始终发生
自动衔接	`comet-state next`	决定是否自动调用下一个阶段 Skill	是，读取 `classic.auto_transition`

阶段推进一定发生——guard 的 —apply 总是更新 phase。 auto_transition 只控制是否自动调用下一个 Skill，不影响 phase 推进。用户决策点无论 auto_transition 取何值都必须阻塞。

小鱼用 guard 推动阶段珠子，同时用 auto_transition 开关控制下一步衔接

阶段推进负责更新状态，自动衔接只决定下一张 Skill 卡片是否继续递出去

自动检测怎么工作

每次调用 /comet 并进入 Classic 后，内部 /comet-classic 不依赖对话历史，而是重新读取文件状态判断当前阶段。

Step 0：发现活跃 change

预设检测（优先级最高）——命中 hotfix/tweak 时直接调用对应预设 Skill
未命中预设时运行 openspec list --json 获取所有活跃 change
按 change 数量和用户输入决定行为:

活跃 change	用户输入	行为
无	非预设	调用 `/comet-open`
1 个	`/comet <描述>`	配置进入 Classic 后询问：继续还是创建新
多个	`/comet <描述>`	配置进入 Classic 后询问：继续还是创建新；选继续则列出清单
1 个	`/comet`（无描述）	配置进入 Classic 后自动选中
多个	`/comet`（无描述）	配置进入 Classic 后列出清单让用户选择

Step 1：读取状态

优先读取当前 Classic OpenSpec 根目录下的 changes/<name>/.comet.yaml：新项目默认是 docs/openspec/changes/<name>/.comet.yaml，保留旧布局的项目是 openspec/changes/<name>/.comet.yaml。不存在时回退到 openspec status、tasks.md 和 docs/superpowers/ 文件检查。根目录由 classic.artifact_layout 决定，详见项目文件结构。

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`	自动调用下一阶段 Skill	`auto_transition` 不是 `false`
`NEXT: manual`	不调用下一 Skill,打印 HINT 让用户手动运行	`auto_transition: false`
`NEXT: done`	流程已完成	`archived: true`

Skill 路由

next 根据 phase 和 workflow 决定下一个 Skill:

phase	full	hotfix	tweak
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 调用由配置进入 Classic 后，从检测到的阶段开始；退出条件满足后自动推进后续阶段。

/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
`false`	`NEXT: manual`,打印 HINT,由你手动运行

什么时候用 false

想在阶段之间插入人工审核
每个阶段完成后需要换模型或换人
CI/CD 场景需要逐步控制

# 环境变量临时覆盖
export COMET_AUTO_TRANSITION=false

预设升级

hotfix/tweak 执行过程中，如果命中升级信号,会暂停让你二选一:

信号类型	触发	决策
质变信号	跨模块协调、新增 capability、schema 变更、新 public API、深层架构问题	命中任一即暂停
文件数 tripwire	改动文件数超阈值	暂停交用户决定

选项	结果
继续预设轻量流程	继续当前预设
升级为完整 `/comet-classic`	`transition preset-escalate` → 回退到 design → 补 Design Doc → 回到完整流程

preset-escalate 是预设→full 升级的唯一合法通道——原子地设 workflow/classic_profile 为 full，回退 phase 到 design,清除 design_doc。

断点恢复

上下文压缩或会话中断后，重新调用 /comet；配置进入 Classic 后，内部路由重新读取文件状态恢复：

场景	恢复行为
`phase: build` + `build_pause: plan-ready` + 已设 isolation/build_mode	stale 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

下一步

五阶段停顿点和用户选择点 — 自动推进在哪里暂停
Classic 配置 — auto_transition 字段和配置优先级
工作流概念 — 五阶段如何串联
恢复中断的工作 — 断点恢复的实践

理解 Comet Classic

五阶段工作流

轻量预设

恢复与排查

实践场景

阶段推进 vs 自动衔接

自动检测怎么工作

Step 0：发现活跃 change

Step 1：读取状态

Step 2：阶段判定

状态转换

自动衔接：next 命令

Skill 路由

连续执行

auto_transition 配置

什么时候用 false

预设升级

断点恢复

红旗清单

下一步

​阶段推进 vs 自动衔接

​自动检测怎么工作

​Step 0：发现活跃 change

​Step 1：读取状态

​Step 2：阶段判定

​状态转换

​自动衔接：next 命令

​Skill 路由

​连续执行

​auto_transition 配置

​什么时候用 false

​预设升级

​断点恢复

​红旗清单

​下一步

阶段推进 vs 自动衔接

自动检测怎么工作

Step 0：发现活跃 change

Step 1：读取状态

Step 2：阶段判定

状态转换

自动衔接：next 命令

Skill 路由

连续执行

auto_transition 配置

什么时候用 false

预设升级

断点恢复

红旗清单

下一步