vmihalis/claude-handover/handover

handover

Produce a handover document for this Claude Code session so work can resume cleanly after /clear or in a new session.

Where HANDOFF.md goes

Decide location by checking the session's working directory:

1. Inside a git repo (git rev-parse --show-toplevel succeeds): write to <repo_root>/HANDOFF.md. This keeps repo-scoped work next to the code.

1. Not in a git repo (home dir, ad-hoc session, etc.): write to ~/.claude/handovers/<slug>.md where:

• <slug> = user-supplied label from the invocation argument (e.g. /handover memory-cleanup → memory-cleanup.md), OR
• <slug> = auto-generated from session content: kebab-case topic + date suffix (e.g. claude-mem-research-2026-04-22.md).
• Create ~/.claude/handovers/ if it doesn't exist.
• Do not overwrite silently in this dir — if a file with the same slug exists, append -2, -3, etc.

Always print the absolute path of the file you wrote.

Template

Write the file using these exact section headers — the pickup skill parses them:

# HANDOFF — <short task label> (<YYYY-MM-DD HH:MM>)
 
_Scope: <`repo:<name>` or `adhoc` (non-repo session)>_
 
## Goal
<One sentence: what this session was trying to accomplish.>
 
## Status
<What's done, what's in progress, what's not started. Be specific. No generalities like "made progress on X".>
 
## Files touched
-`path/to/file.ext` — <one-line reason>
-...
(For ad-hoc sessions, list files across repos with absolute paths. For repo sessions, prefer repo-relative paths.)
 
## Key decisions
-Chose <X> over <Y> because <Z>.
-...
 
## Open threads / blockers
-<Unresolved question, failing test, external dependency, etc.>
 
## Next step
<The literal next action. One specific actionable sentence. Not a list.>
 
## Don't do
-<Dead end already ruled out or user correction — so the next session doesn't retry it.>

Rules

1. Secrets exclusion. No credentials, tokens, API keys, .env/.ssh/wallet content in HANDOFF.md.
2. Disk > chat. The summary goes in the file, not in chat.
3. Terse. Bullets over prose. Specifics over generalities.
4. Thin handovers are fine. If little happened, write it anyway — a skeleton is more useful than nothing.
5. Repo handovers overwrite `HANDOFF.md` in place. Ad-hoc handovers never overwrite — they suffix on collision.

Output to the user

After writing the file, print exactly this block and nothing else:

HANDOFF written: <absolute path>
 
Next: /clear, then /pickup <slug>

Where <slug> is the ad-hoc filename without the .md extension. For repo handovers (written to <repo_root>/HANDOFF.md), /pickup with no argument works — the pickup skill auto-detects ./HANDOFF.md from CWD.

The pickup skill does the reading, parsing, file re-reads (conditional on modification), and resumption from Next step — don't duplicate any of that guidance here. No paste-ready prompt needed; /pickup <slug> triggers the behavior.

No "here's what we did", no "let me know if...". Just the confirmation line and the Next command.