comet handoff

comet handoff 负责把当前阶段的 OpenSpec artifacts 整理成交接包，并计算 handoff hash。它是 design 阶段把 OpenSpec（WHAT）和 Superpowers（HOW）物理对接的稳定公开命令，也服务于长任务、子代理执行和上下文恢复。下文用 <classic-root> 表示当前 Classic OpenSpec 根目录：新项目默认是 docs/openspec/，保留旧布局的项目是 openspec/。实际位置由 classic.artifact_layout 决定，详见项目文件结构。

它算哪些文件

handoff hash 对以下 OpenSpec artifacts 计算内容 hash：

<classic-root>/changes/<name>/proposal.md
<classic-root>/changes/<name>/design.md
<classic-root>/changes/<name>/tasks.md
<classic-root>/changes/<name>/specs/<capability>/spec.md   # 每个 delta spec

对每个文件先算 per-file sha256，再把”相对路径 + per-file sha256”拼起来算最终 sha256，得到 handoff_hash。路径统一用正斜杠，保证 macOS/Linux/Windows 字节一致。

交接包格式

comet handoff ... --write 在 <classic-root>/changes/<name>/.comet/handoff/ 下产出：

模式	产出文件	内容
`off`（默认）	`design-context.json` + `design-context.md`	完整 artifacts 内容，每文件带 SHA256
`beta`（压缩）	`spec-context.json` + `spec-context.md`	spec 文件 verbatim 投影 + supporting 文件只存 hash，节省约 25–30% token

JSON 包含 change、phase、mode、canonical_spec: openspec、context_hash 和 files 数组。markdown 包带 Generated-by: 标记和每个文件的 Source:/SHA256: 引用。

hash 的作用

handoff_hash 写入 .comet.yaml，在三个地方发挥作用：

阶段	hash 的作用
design	生成 hash 并写入 `.comet.yaml` 的 `handoff_hash` 和 `handoff_context`
guard（离开 design）	重算 hash，不一致就 FATAL，提示重新生成 handoff
verify	用 `--hash-only` 快速重算，一致说明 OpenSpec artifacts 未变

快速重算

--hash-only 是快速路径，跳过所有文件写入，只重算 hash（前提是 change 目录和 3 个必需文件存在）：

comet handoff <change-name> --hash-only

什么时候有用

build 阶段任务很多。
使用 subagent-driven development。
Agent 会话发生上下文压缩。
需要把当前工作交给另一个会话。

普通用户不需要手工运行 handoff。/comet-design 会在 design 阶段自动生成；恢复时直接调用 /comet，仅在诊断时使用 comet status。

安装包仍包含 comet-handoff.mjs 兼容 launcher，但普通使用和 Agent 指令应优先采用 comet handoff。

下一步

工作流概念 — 理解 handoff 如何把 OpenSpec 和 Superpowers 串起来
状态与配置 — handoff_hash 和 handoff_context 字段

安装和健康检查

Skill、评估和发布（进阶）

核心脚本

它算哪些文件

交接包格式

hash 的作用

快速重算

什么时候有用

下一步

​它算哪些文件

​交接包格式

​hash 的作用

​快速重算

​什么时候有用

​下一步

它算哪些文件

交接包格式

hash 的作用

快速重算

什么时候有用

下一步