自动推进机制

调用 /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 后询问：继续该 change 还是创建新的
多个	`/comet <描述>`	配置进入 Classic 后询问是否继续已有 change 或创建新的。若选继续，会列出清单
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`	≤3 次失败自动回 build 修复，第 4 次暂停等你决策
`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`（配置已齐全）	重新发起同一次联合决策，你补全配置后才清除暂停标记并继续
`phase: build` + `build_pause: plan-ready`（配置未齐全）	回到 plan-ready 联合决策，等你补选执行方式、TDD 和审查模式
`phase: build` + `build_pause: plan-ready` + plan 缺失	状态损坏，重新生成 plan
`phase: verify` + `verify_result: fail`	≤3 次失败自动回 build 修复。第 4 次暂停并等待你决策
`phase: open` + 产物已完整	先 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

预设升级

断点恢复

红旗清单

下一步