> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet handoff

> 生成阶段交接包和 handoff hash，把 OpenSpec artifacts 整理成 Superpowers 能读懂的上下文。

`comet handoff` 负责把当前阶段的 OpenSpec artifacts 整理成交接包，并计算 handoff hash。它是 design 阶段把 OpenSpec（WHAT）和 Superpowers（HOW）物理对接的稳定公开命令，也服务于长任务、子代理执行和上下文恢复。

下文用 `<classic-root>` 表示当前 Classic OpenSpec 根目录：新项目默认是 `docs/openspec/`，保留旧布局的项目是 `openspec/`。实际位置由 `classic.artifact_layout` 决定，详见[项目文件结构](/zh/guides/project-structure)。

## 它算哪些文件

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

```text theme={null}
<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 个必需文件存在）：

```bash theme={null}
comet handoff <change-name> --hash-only
```

## 什么时候有用

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

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

<Note>
  安装包仍包含 <code>comet-handoff.mjs</code> 兼容 launcher，但普通使用和 Agent 指令应优先采用{' '}
  <code>comet handoff</code>。
</Note>

## 下一步

* [工作流概念](/zh/concepts/workflow) — 理解 handoff 如何把 OpenSpec 和 Superpowers 串起来
* [状态与配置](/zh/concepts/state-management) — `handoff_hash` 和 `handoff_context` 字段