Handoff

Write what a fresh session needs to continue this work into a file, and end with the one line the user pastes after /clear.

Classification: Degraded — where the runtime cannot write outside the workspace (a sandbox that forbids it), the prompt is printed in one fenced block instead of saved, and the user pastes that block.

Step 1 — Choose the file

• <project> is the folder name of the repository root (git rev-parse --show-toplevel), or of the working directory outside a repository.
• The file is ~/.handoff/<project>.md, where ~ is the user's home folder (%USERPROFILE% on Windows). Resolve it to an absolute path, and create the folder if it is missing.
• Before every write, read the first line of the candidate file if it exists. Overwrite it only when that line is exactly Project: <this project's absolute path>. Any other first line — another path, an empty line, anything unrecognized — means the file is not this project's: never overwrite it. Prefix the name with the next parent folder (<parent>-<project>.md, then <grandparent>-<parent>-<project>.md) and check again, until the name is free or this project's own. Stop at the filesystem root or a drive (a name never contains / or C:): if the parent folders run out first, write nothing and print the prompt as Step 3's fallback does.

Step 2 — Write the prompt

The first line is exactly Project: <absolute path of the project>. Then write, for a reader who has none of this conversation:

• Written — the date and time, the branch, and the last commit (git log -1 --oneline).
• Goal — what the work is for.
• Done — what is finished, and how it was verified.
• Next — the next concrete steps, in order.
• Decisions already made, and why — so the next session does not reopen them.
• Traps found — what failed or misled, and what to do instead.
• Files to read first — paths, including the project's CLAUDE.md / AGENTS.md where either exists. Describe a file by its path and what it is for; never restate its contents, which the next session reads for itself and a paraphrase gets wrong.
• Uncommitted work — git status --short, and which of those changes are this work's.
• Open questions for the user.
• A closing instruction: before acting on any of it, check the repository's current state (git status, git log -1), because the file may be older than the tree.

Be concrete: name files, commands and commit hashes. The next session can read the code; it cannot read this conversation. Never write a secret, key, token, password or credential into the file, which sits in the home folder as plain text: name where a credential is kept, never its value.

Do not stage, commit or push anything. The file lives outside the repository.

Step 3 — Report

When the file was written, end with one short sentence telling the user to paste the next line after /clear, then exactly this line, with the file's absolute path in it:

Read <absolute path> and continue from it.

If the file cannot be written, say why in one sentence and print the whole prompt in one fenced block instead. The user pastes that block after /clear.