comet-state

Comet 流程的状态回退 skill。用于将 OpenSpec change 的 .comet.yaml 阶段安全倒退，例如从 archive 回到 verify、从 build 回到 design。

本 skill 只做回退，不做前进。正常推进请使用 /comet 及各阶段 skill（/comet-open、/comet-design、/comet-build、/comet-verify、/comet-archive）。

触发方式

在 Cursor / Claude Code 中：

/comet-state

或自然语言描述，例如：

• 「把这个 change 回退到 design 阶段」
• 「撤销归档，重新验证」
• 「comet 状态倒退到 open」

阶段顺序

full:    open → design → build → verify → archive
hotfix:  open ─────────→ build → verify → archive
tweak:   open ─────────→ build → verify → archive

回退规则：目标阶段必须严格早于当前阶段。

允许	禁止
archive → verify / build / design / open	open → archive（跨阶段前进）
verify → build	同阶段「回退」（如 build → build）
build → design（full）	hotfix/tweak → design
build → open	把 archive 作为回退目标

目录结构

comet-state/
├── README.md                       # 本文件
├── SKILL.md                        # Agent 执行指令
├── references/
│   └── rollback-matrix.md          # 各目标阶段的字段重置矩阵
└── scripts/
    └── comet-rollback.sh           # 安全回退脚本（推荐）

依赖

• comet skill（提供 comet-env.sh、comet-state.sh）
• 目标 change 存在 .comet.yaml（活跃目录或 archive 目录均可）

命令行用法

1. 加载环境

. .claude/skills/comet/scripts/comet-env.sh

执行后会导出 COMET_STATE 等变量。

2. 查看当前状态

CHANGE=your-change-name

bash "$COMET_STATE" get "$CHANGE" phase
bash "$COMET_STATE" get "$CHANGE" workflow
bash "$COMET_STATE" get "$CHANGE" archived

3. 预览回退（推荐）

bash .claude/skills/comet-state/scripts/comet-rollback.sh "$CHANGE" design --dry-run

4. 执行回退

bash .claude/skills/comet-state/scripts/comet-rollback.sh "$CHANGE" design

有效目标阶段：open、design、build、verify（不含 archive）。

5. 验证入口条件

bash "$COMET_STATE" check "$CHANGE" design

6. 继续 Comet 流程

回退完成后，调用对应阶段 skill：

回退目标	下一步
open	/comet-open 或 /comet
design	/comet-design
build	/comet-build
verify	/comet-verify

常用场景

当前阶段	回退到	典型场景
archive	verify	归档后想重新验证
archive	build	归档后想继续改代码
archive	open	保留 change 目录，从头来过
verify	build	主动回到构建（区别于 verify 阻塞点的 verify-fail）
build	design	计划/实现方向有误，重做设计
build	open	hotfix/tweak 重做 proposal
design	open	提案阶段重来

手动回退（脚本不可用时）

使用 comet-state.sh set 逐字段更新。以 archive → open 为例：

bash "$COMET_STATE" set "$CHANGE" phase open
bash "$COMET_STATE" set "$CHANGE" archived false
bash "$COMET_STATE" set "$CHANGE" design_doc null
bash "$COMET_STATE" set "$CHANGE" plan null
bash "$COMET_STATE" set "$CHANGE" build_mode null
bash "$COMET_STATE" set "$CHANGE" isolation null
bash "$COMET_STATE" set "$CHANGE" verify_mode null
bash "$COMET_STATE" set "$CHANGE" verify_result pending
bash "$COMET_STATE" set "$CHANGE" verification_report null
bash "$COMET_STATE" set "$CHANGE" branch_status pending
bash "$COMET_STATE" set "$CHANGE" verified_at null
bash "$COMET_STATE" set "$CHANGE" handoff_context null
bash "$COMET_STATE" set "$CHANGE" handoff_hash null
bash "$COMET_STATE" set "$CHANGE" direct_override false

若 change 在 archive 目录，需先移回活跃目录：

mv openspec/changes/archive/YYYY-MM-DD-"$CHANGE" openspec/changes/"$CHANGE"

完整字段矩阵见 references/rollback-matrix.md。

注意事项

1. 执行前需用户确认：Agent 会说明当前阶段、目标阶段及将清空的字段。
2. 不删除磁盘文件：回退只更新 .comet.yaml 引用，不自动删除 proposal.md、tasks.md、plan 文件等。
3. 不撤销 spec 同步：从 archive 回退不会自动还原已同步到主 spec 的内容，需人工检查 git 历史。
4. 不用 transition 回退：comet-state.sh transition 仅支持前进事件；回退请用 set 或 comet-rollback.sh。
5. entry check 可能失败：状态回退成功后，目标阶段的入口检查仍可能 FAIL（例如回退到 design 但 design_doc 已被清空），需按提示补齐。

与 verify-fail 的区别

机制	路径	说明
transition verify-fail	verify → build	Comet 验证失败阻塞点的官方路径，需用户决策
/comet-state	任意合法倒退	用户主动发起的通用回退，支持多阶段

相关文档

• SKILL.md — Agent 完整执行流程
• rollback-matrix.md — 字段重置矩阵
• comet-state.sh — 底层状态读写接口