跳转到主要内容
Comet 的 state machine 为每个 change 使用两个 YAML 文件。一个归 OpenSpec 所有，用于跟踪正式的 spec lifecycle。另一个归 Comet 所有，用于跟踪 workflow engine 需要知道的一切：change 处于哪个 phase、应该如何 build、verification 是否通过，以及 change 是否已 archived。二者配合后，即使 AI 编程会话被关闭再重新打开，agent 也能从长时间运行的 change 中断处准确恢复。

​
解耦的 State Files

FileOwner用途
.openspec.yamlOpenSpec由 OpenSpec Skills 管理的 spec lifecycle metadata、change identity 和 status annotations
.comet.yamlComet由 Comet scripts 管理的 workflow phase、execution mode（build_mode、isolation）、verification status、artifact paths 和 archive state
这两个文件都位于 openspec/changes/<name>/ 下的 change directory 中。保持分离意味着 OpenSpec operations 永远不会破坏 Comet workflow state，Comet state updates 也不会干扰 OpenSpec 的 spec-lifecycle logic。从直接编辑的角度看，Agents 应将 .comet.yaml 视为只读，所有写入都应通过 comet-state.sh 完成。

​
The .comet.yaml File

一个完整填充的 .comet.yaml 如下所示： 
workflow: full
phase: build
build_mode: subagent-driven-development
build_pause: null
isolation: branch
verify_mode: null
design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
base_ref: a1b2c3d4e5f6...
verify_result: pending
verification_report: null
branch_status: pending
created_at: 2026-05-26
verified_at: null
archived: false
direct_override: false
build_command: null
verify_command: null
handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
handoff_hash: <sha256>

​
核心字段

字段允许值含义
workflowfull, hotfix, tweak此 change 使用的 workflow preset。它在 init 时设置，并驱动整个 pipeline 中的 routing decisions。
phaseopen, design, build, verify, archive当前 workflow phase。由 comet-state.sh init 初始化为 open；只能通过 guard transitions 推进。
build_modesubagent-driven-development, tdd, direct, or null用户在 build 阶段选择的 Superpowers execution method。必须在 build → verify transition 前设置。
build_pauseplan-ready, null内部 build-phase pause marker。参见下方 The build_pause Field。
isolationbranch, worktree, nullWorkspace isolation method。hotfix 和 tweak 默认使用 branch；full workflow 会保持 null，直到用户在 Phase 3 选择。必须在 build → verify 前解析完成。
verify_modelight, full, nullVerification thoroughness。tweak 使用 light；full workflow 和 hotfix 使用 full。
verify_resultpending, pass, fail最近一次 verification run 的结果。pass 作为 archive phase 的门禁；fail 会触发阻塞性的用户决策。
verification_reportFile path or null已写入 verification report file 的路径。必须指向一个现有文件，才允许 verify-pass transition。
branch_statuspending, handledBranch operations（merge、close 或 carry-forward）是否已完成。Verify 通过前必须是 handled。
archivedtrue, falseChange 是否已完成 archive phase。一旦为 true，workflow 即完成，目录已移动到 archive tree。
verified_atISO timestamp or null应用 verify-pass transition 时由 comet-state.sh 写入的 timestamp。
created_atDate string (YYYY-MM-DD) or nullChange 创建日期，由 comet-state.sh init 自动设置。

​
Artifact Path 字段

字段允许值含义
design_docFile path or nullPhase 2 产出的 Superpowers Design Doc（technical RFC）路径。Brainstorming 完成后由 comet-design 写入。
planFile path or nullPhase 3 产出的 Superpowers implementation plan 路径。生成 plan file 时写入。
base_refGit commit SHA or nullChange init 时记录的 Git commit SHA。在没有 plan 时用于 scale assessment。
handoff_contextFile path or null离开 Phase 2 时由 comet-handoff.sh 生成的 design-context JSON package 路径。用于将可追踪的 OpenSpec context 传入 Superpowers。
handoff_hashSHA-256 hex string or nullhandoff context file 的 hash，由 comet-handoff.sh 记录。Guard 会在 build phase 开始前验证此 hash。

​
可选和 Override 字段

字段允许值含义
direct_overridetrue, false允许在 full workflow 中使用 build_mode: direct。必须显式设置为 true；没有此 flag 时，guard 会阻止 full workflows 使用 direct mode。
build_commandShell command string or nullProject build command。如果已设置，comet-guard.sh 会在 build-phase validation 期间先运行它并打印失败输出。
verify_commandShell command string or nullProject verification command。Verify guard 会先运行它；如果不存在，则回退到 build_command。

​
State Machine Constraints

以下 constraints 是由 comet-guard.sh 和 comet-state.sh 共同强制执行的 hard rules。如果未满足这些条件就尝试推进阶段，会产生带可执行建议的 [HARD STOP] error。
  • isolation 必须是 branch 或 worktree，才允许 build → verify transition。null 值会阻止 transition。
  • build_mode 必须已选择（非 null），才允许 build → verify transition。
  • full workflow 中的 build_mode: direct 需要 direct_override: true。没有此 flag 时，guard 会拒绝 transition。hotfix 和 tweak presets 可以自由使用 direct。
  • verification_report 必须指向一个现有文件，才允许 verify-pass transition。null 值或指向不存在文件的路径都会阻止 transition。
  • branch_status 必须是 handled，verify 才能通过。Branch operations 不能跳过。
  • build_pause: plan-ready 不得写入 build_mode。它是 pause marker，不是 execution mode。见下方说明。

​
The build_pause Field

build_pause 是只在 build 阶段内部使用的特殊 marker，用于记录一次有意的阶段中暂停。它 不是 execution mode，绝不能赋值给 build_mode。
Value含义
null当前没有 pause。正常 build execution。
plan-readyImplementation plan 已生成。用户选择在此暂停，通常是为了在开始执行前切换 AI models，并且尚未选择 isolation 或 build_mode。
恢复 plan-ready pause 时：
  1. Comet 检测到 build_pause: plan-ready，并确认 plan 中路径指向的 plan file 存在。
  2. 现有 plan 会原样复用，不会重新生成。
  3. 系统会提示用户选择 isolation 和 build_mode 以继续。
  4. 两者都选择后，build_pause 会清除为 null，execution 恢复。
如果设置了 build_pause: plan-ready 但 plan file 缺失，Comet 会进入 corrupted-state recovery flow，并可能重新生成 plan。

​
State Transitions 如何工作

Agents 使用 comet-state.sh 通过 state transitions 推进 .comet.yaml。不允许直接编辑 YAML，所有 state writes 都要通过该脚本，以确保 schema validity、enum correctness 和一致的 field co-updates。 实践中，大多数 transitions 会在 phase exits 时由 comet-guard.sh --apply 自动触发。--apply flag 会指示 guard 验证 exit conditions；如果通过，则在内部调用 comet-state.sh transition。必要时你也可以直接触发 transitions： 
"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
每个 transition event 都映射到一组 field updates：
Event对 .comet.yaml 的影响
open-complete设置 phase: design
design-complete设置 phase: build，写入 handoff_context 和 handoff_hash
build-complete设置 phase: verify
verify-pass设置 verify_result: pass，写入 verified_at timestamp
verify-fail设置 verify_result: fail
archived设置 archived: true、phase: archive
$COMET_BASH 和 $COMET_STATE 是由 comet-env.sh 导出的环境变量。始终先 source 这个 helper，并在整个会话中使用这些变量，而不是硬编码 script paths： 
COMET_ENV="$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" \
  -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)"
. "$COMET_ENV"

# Now use $COMET_GUARD, $COMET_STATE, $COMET_HANDOFF, $COMET_ARCHIVE
"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply

​
Guard vs. Direct Transition

方法何时使用
comet-guard.sh <name> <phase> --apply阶段结束时使用。先验证 exit conditions，然后应用 transition
comet-state.sh transition <name> <event>当不需要 guard validation 时直接更新 state（例如 recovery flows、script internals）
Guard 是权威的 exit check。直接调用 comet-state.sh transition 会绕过 validation，只有在调用上下文已经独立验证 preconditions 时才应这样做。