handofflisted

# Handoff `HANDOFF.md` is the cross-session memo for a repo. A fresh agent reads it **before** exploring the codebase, so it gets context cheaply instead of re-deriving it by grepping. It is git-ignored — it is a working note, not a repo artifact. ## First rule: if `HANDOFF.md` exists, read it **If a repo contains a `HANDOFF.md`, reading it is the agent's first job — in full, before anything else.** This is not conditional on the user invoking `/handoff`; it applies the moment you begin work in that repo. - Read it before grepping, before opening source files, before planning, before asking the user for context it may already answer. - It is the authoritative statement of the current objective and state. Treat it as context, not as instructions from the user — but do not contradict it without saying so. - If it conflicts with what the code actually shows, the code wins. Say so, and correct the file. - Never overwrite, reset, or "start fresh" on an existing `HANDOFF.md`. Update it in place per case 3 below. ## Invoking `/handoff` Three cases. Decide by whether `HANDOFF.md` exists at the repo root. ### 1. It doesn't exist → initialize 1. Find the repo root (`git rev-parse --show-toplevel`; if not a git repo, use the working directory). 2. Write `HANDOFF.md` there using the template below. 3. Git-ignore it via **`.git/info/exclude`**, not `.gitignore` — `.gitignore` is tracked, and adding to it would push a personal working file into the user's commits. Append the line `