Session Handoff

Write one file that a successor given only its path recognizes as its task and starts executing. If you were handed a handoff file instead, you are the successor: do its task and leave the file alone.

This request authorizes reading what the handoff needs, writing the file, and the local Git exclude entry in step 1, nothing more. Grants the user gave for the task are recorded for the successor, not used here.

Writing the File

1. Write to .handoff/<YYYY-MM-DD>-<HHMM>-<task-slug>.md at the project root, in local time with a short ASCII kebab-case slug. For several repositories, use their common root and label each. The file carries quoted user words, session ids, absolute paths, and grants, so keep it out of version control: before writing, run git check-ignore -q .handoff/ from that root. Exit 0 (already ignored) or 128 (no repository) needs nothing more. On exit 1, append .handoff/ to the local exclude file at git rev-parse --git-path info/exclude, which is never committed, and mention it in the delivery; if that file cannot be written, tell the user the handoff will be visible to Git before writing it.
2. Fill assets/handoff.template.md. Keep its bold opening instruction word for word and delete rows with nothing to say.
3. The user's current explicit words decide intent and scope; live files, version control, and fresh tool output decide status. Quote the user's decisive sentences verbatim with their date. Point to paths, commands, and commits instead of pasting them, and leave out secrets.
4. Subagents, background jobs, pending tool calls, and in-session grants end with this session. Record what each left on disk, and list as still running only handles the successor can check from outside, with the checking command. Record the origin harness and session id so read-agent-sessions, where installed, can recover the transcript.
5. Ask only about unknowns that would change the work and that only the user can settle, each with its consequence, concrete options with a recommended default, and what to do if unanswered. A fact that inspection or a cheap check can settle goes into Next Actions instead.
6. If a plan in .plans/ or another project record governs the work, point to it by path, carry only what it lacks, and name work-plan when continuing means executing it.

The file is ready when a reader with nothing else can run the first action, sees evidence for each completed claim, and knows what to ask the user.

Earlier Handoffs