persistent-handofflisted

# Persistent handoff An agent that runs for weeks loses its context at every restart, compact, crash and reboot. The handoff is the one file that survives. It holds where the work stands, what to do next, and what a fresh session would otherwise relearn. An agent has one handoff file, always the same one. It holds the current state and no history. ## Quick reference | Rule | In practice | |---|---| | The same file, always | Rewrite it at the same path. Never a second file, never a dated copy | | Read at every session start | The `SessionStart` hook injects it, you rarely open it to read | | Written at milestones | Decision, PR, conclusion, blocker, unanswered question | | State, not narrative | Where things stand, not how they got there | | 300-500 tokens | Below: vague. Above: journal | | Prune on every update | Resolved items go, the file shrinks as work completes | | Empty means delete | No file is a valid state: nothing in flight | ## When to write At milestones, on your own, without being asked: - a decision is made - a PR is opened or merged - an investigation reaches a conclusion - you hit a blocker - you asked the human something and the answer has not come yet Not after every message. The transcript already keeps the conversation. The handoff keeps what a new session needs to act. ## Where it lives One path, chosen once, used by every session of this agent. The `SessionStart` hook reads that exact path, and a handoff written anywhere else is never read by a