Handoff
让项目在 agent 之间交接时不丢东西。核心不是「告诉对方做了什么」，而是「让对方能立刻接着干」。
何时用
交出：会话变长上下文吃紧 / 要换 agent（WorkBuddy ↔ Claude Code ↔ Cursor ↔ Codex ↔ opencode）/ 今天收工明天继续 / 要换人接手。
接手：拿到一个 .wwlia-handoff/ 包，或新会话要继续别人干了一半的活。
模式路由
- 用户参数含
pickup、接手、onboard、resume之一 → 走接手流程 - 否则 → 走交出流程
- 参数里剩余的文字（如「下次专注前端」）当作下一个会话的焦点，用来加权「下一步」章节
四条核心原则
- 装知识，不装状态。 状态（分支、文件树、未提交改动）由脚本抓进
raw/，正文不重复。正文只写仓库里看不出来的东西：为什么、试过什么失败了、用户禁止什么。 - 分层，替接手方省 context。 L0 必读且 ≤150 行，细节放
context/，机器数据放raw/。一份 800 行大文档的结果是：要么全塞进去稀释注意力，要么干脆不读。 - 点名半成品。 改了一半的文件、临时 hack 必须写明。漏了最致命——接手方会默认它们是好的。
- 先复述，再动手。 接手方未获确认前不改任何文件。
交出流程
第 1 步 采集状态（脚本）
python "<skill目录>/scripts/collect.py" --project "<项目根>" --memory-days 14
产出 <项目根>/.wwlia-handoff/<时间戳>/raw/。非 git 项目自动降级，不报错。
不要让 AI 凭回忆写 git 状态——脚本更准，也不占对话轮次。
第 2 步 蒸馏知识（AI）
读 raw/memory-recent.md 和当前对话，按 references/extract-checklist.md 逐条挖。
三样东西缺一样，这次交接就是残的：
- 已失败的尝试——防止接手方重蹈覆辙
- 用户的红线与偏好——禁令、工作习惯、输出口味
- 半成品状态——见原则 3
按 references/template-L0.md 写 HANDOFF.md。硬上限 150 行，超了就把细节挪到 context/。
第 3 步 补 context/
context/decisions.md— 决策 + 理由 + 被否决的备选context/failed-attempts.md— 失败方案 + 失败现象原文 + 结论context/conventions.md— 项目约定、用户偏好、命令坑
第 4 步 打包校验
python "<skill目录>/scripts/pack.py" --pack-dir "<项目根>/.wwlia-handoff/<时间戳>" --title "一句话目标" --from "WorkBuddy" --to "Claude Code"
产出 MANIFEST.md 和脱敏扫描报告。校验会检查：行数上限、三节必填（半成品 / 红线 / 已失败尝试）、敏感信息。
有告警先处理再交付。跨机器传递前必须过脱敏，见 references/desensitize-rules.md。
接手流程
- 找包：
<项目根>/.wwlia-handoff/下时间戳最大的目录。找不到就直说，不要凭空猜、不要假装看过。 - 只读两个文件：
MANIFEST.md→HANDOFF.md。细节等需要时再下钻。 - 校验新鲜度：比对
MANIFEST.md里的源 commit 与当前git rev-parse HEAD。不一致 → 先告诉用户再动手。 - 复述确认：向用户复述——一句话目标 / 当前状态 / 下一步前三项 / 半成品 / 红线。等确认。
- 确认后才动手。缺细节时下钻
context/或raw/，不要一次全读。 - 收工或再次交接时，把新决策追加回同一个包，或新建包并在
MANIFEST.md里写明前序包路径。
硬性约束
HANDOFF.md超 150 行必须裁剪，不许靠放宽上限解决- 状态类信息不写进正文，只留在
raw/ - 「半成品」「红线」「已失败尝试」三节必填；确实没有要写明「已确认无」，不留空
- 未复述确认不动文件
- 跨机器 / 跨工具 / 跨人传递前必须过脱敏
- 密钥原文任何情况下都不进包（含
raw/），只写「需要什么 + 从哪拿」
目录约定
<项目根>/.wwlia-handoff/<YYYYMMDD-HHMMSS>/
HANDOFF.md 必读，≤150 行
MANIFEST.md 元信息 + 校验结果 + 文件清单
context/ 按需下钻
decisions.md
failed-attempts.md
conventions.md
raw/ 脚本生成，不手写
git-status.txt git-log.txt tree.txt memory-recent.md env.txt
.wwlia-handoff/ 建议加进 .gitignore，或交接完成后删除——它是一次性快照，不是长期文档。
与其他机制的关系
.workbuddy/memory/是日常流水账，交接包是对它的蒸馏。不要为了交接重复记一遍日常，也不要把流水账原样搬进正文。- 给别的 agent 交接时，别忘了在对方会读的规则文件里加一行指针，见
references/agent-adapters.md。
