Handoff

Write the opening instructions your next session needs to pick up the work. The next session is a cold agent: same tools and checkout, zero memory of this one — its only input is this document. Every handoff is a briefing for a stranger, so it's a work order, not a report: it says what to do next, not what happened. There is no "we," nothing "we decided," no "where we left off" — if a line only makes sense to someone who was here, cut it. Size it to the next move, not to the session — a one-file fix earns a ten-line handoff, however long the session was.

One variable: does the reader already share this project? If yes, pointers can be bare paths and ticket IDs. If not (a teammate, a different context), strip originating-project assumptions and spell out where things live.

Workflow

1. Commit any unfinished work first, if it's in a committable state and the project uses version control. A clean tree means the cold agent starts from a known point instead of reverse-engineering a working tree of half-done edits — and Next can then point at committed state rather than spending lines describing uncommitted diffs. A wip: commit is fine; note it in Next so the reader knows to build on or amend it. Skip only when the work genuinely can't be committed (broken build mid-refactor) — then say so in one line.
2. Write Next first: the one concrete action the next session starts with, specific enough for a cold start. Everything else gets in only by tracing to it.
3. Admit each further line by one test: could the cold agent execute Next without this? If yes, cut it — however much work it represents. "Important context" and "we decided this" don't count; a decision is recorded only if Next would otherwise violate it, and then as the rule, not its history. The code, git log, and standing docs (AGENTS.md, SPEC, TODO) already hold the past — link, don't recount, and never paste file contents, diffs, or command output.
4. If this conversation opened with a prior handoff, merge: carry what still constrains Next, drop the rest. Never append verbatim.
5. Budget check: the whole handoff fits on one screen. Longer means you drifted into reporting — cut, don't reorganize.
6. Write it to date -u +/tmp/handoff-%Y%m%dT%H%M%SZ.md and copy it in the same step (pbcopy < <path> / xclip -selection clipboard < <path>) — no confirmation gate.
7. Print the whole handoff verbatim in your reply. The write and the copy are both silent and tool output is truncated, so this is the only place the user sees it — print the body as prose, never a cat. Once, then stop.
8. Tell the user to /clear and paste as the first message — clearing is client-side, their one manual step. On requested edits: rewrite, re-copy, reprint in full.

Format