/handoff

Purpose: package the current state so the next agent (or future you) can resume quickly.

Persist the handoff note (always)

Determine repo root.
- Prefer: git rev-parse --show-toplevel
- Fallback: current working directory
Use a git-tracked handoff area so it can be reused later (including via automations):
- If the work is tied to a dossier under docs/04-projects/.../<dossier>/: write to <dossier>/tmp-handoffs/.
- Otherwise (non-dossier or cross-dossier): write to docs/98-tmp/handoffs/.
Create the folder if missing.
Generate filename using the handoff time:
- handoff_YYYY-MM-DD_HH-MM-SS_<3-5 words>.md
- Choose 3–5 words that describe the work or topic.
- Prefer lowercase kebab-case for the words (avoid spaces and special characters).
Write the handoff checklist content into that markdown file.
Echo the saved file path at the top of the handoff output.

Scope/status: what you were doing, what’s done, what’s pending, and any blockers.
Working tree: git status -sb summary and whether there are local commits not pushed.
Branch/PR: current branch, relevant PR number/URL, CI status if known.
Running processes: list tmux sessions/panes and how to attach:
- Example: tmux attach -t codex-shell or tmux capture-pane -p -J -t codex-shell:0.0 -S -200
- Note dev servers, tests, debuggers, background scripts.
Tests/checks: which commands were run, results, and what still needs to run.
Next steps: ordered bullets the next agent should do first.
Risks/gotchas: any flaky tests, credentials, feature flags, or brittle areas.

Prefer writing the note even if the session continues. A fresh thread can be started at any time without losing state.
If file write is not possible, print the handoff checklist in chat and ask the user to save it into the git-tracked handoff area.