context-handoff

name	context-handoff
description	生成/更新会话进度交接文档（HANDOFF.md，落到本会话实际改动的项目目录），用于上下文接近上限时把当前所有工作落盘，方便 /clear 或 /compact 后让新会话无缝接力。Use when 上下文用量偏高、用户说"交接/接力/handoff"、或准备清理会话之前。也会被全局 Stop hook（context-handoff-check.py）在用量达阈值（默认 50%）时自动调用。
allowed-tools	Read, Write, Glob, Bash
metadata	{"tier":"default-min","cost":"light","side_effects":"none"}

会话进度交接

把当前会话"到目前为止"的全部工作整理成一份交接文档，写入本会话真正在改的那个项目目录下的 HANDOFF.md，让新会话读这一个文件就能接着干。

参数 $ARGUMENTS：可能包含当前上下文百分比、触发原因、以及 hook 推断好的落点路径（由 hook 传入），可写进 frontmatter。

步骤

0. 确定落点目录（修复「错位」：当前 shell 目录 cwd 未必是真正在改的项目）：

   1. 若触发原因 $ARGUMENTS 里 hook 已给出 HANDOFF.md 的绝对路径，就用它；
   2. 否则（手动调用），看你本会话实际 Edit/Write 过的文件，取其所属项目根（含 CLAUDE.md/.git/package.json 等标记的最近上层目录）；若多个项目，取改动最多的那个；
   3. 都判断不出再用当前工作目录。

1. 回顾整段会话：通读本次会话做过的事——用户的目标、你已经完成的改动、正在进行但没收尾的部分、过程中做过的关键技术决策、踩过的坑、还没解决的问题。

2. 写 / 更新 <落点目录>/HANDOFF.md（已存在则覆盖为最新状态），结构如下：

---
date: <YYYY-MM-DD>
session_id: <若已知>
context_pct: <如有，来自 $ARGUMENTS>
updated: <YYYY-MM-DD HH:MM>
---

# 进度交接

## 当前目标
<这次会话要达成什么，一两句说清>

## 已完成
- <做完的事> —— 涉及文件 `path/to/file`（具体改了什么）
- ...

## 进行中 / 未完成
- <正在做、卡在哪、差什么>

## 关键决策与原因
- <选了 A 没选 B，因为……>

## 下一步（可直接执行）
1. <新会话第一件该做的事，越具体越好，给出命令/文件/函数名>
2. ...

## 继续 / 复现方式
<怎么把环境跑起来、怎么验证、相关端口/命令>

## 未决问题
- <还需要用户拍板的点 / 待确认的事>

3. 确认 + 提醒清理 + 给接管提示词：文档确实写好之后，按下面三段输出（用真实绝对路径）——

   ✅ 交接文档已生成：<交接文档绝对路径>
   当前上下文已达 X%，现在可以安全 /clear 或 /compact 了。
   
   清空后，把下面这句直接粘给新会话即可接管：
   ┌─────────────────────────────────────────────
   │ 读取 <交接文档绝对路径>，按其中"下一步"接管之前的工作并继续。
   └─────────────────────────────────────────────
   
   或者：如果接下来要做的是无关的新事情，直接 /clear 后开一个全新任务即可（无需读交接文档）。
   

   要点：必须先确认文档真的写成功再提示清空（用户据此才敢清空）；接管提示词里填真实绝对路径，让用户复制即用。

约定

• 内容以中文为主（内部工作文档，无需三语）。
• 文件路径用真实绝对/相对路径，方便新会话直接定位。
• 只写交接文档这一件事，不要在交接过程中展开新任务。
• 若当前目录已有 HANDOFF.md，先 Read 旧内容，增量更新而非凭空重写，保留仍有效的历史信息。