handoff

/handoff — write a session handoff

Prerequisite: this skill drives scripts and hooks from https://github.com/Sting25/claude-code-handoff: write_handoff.sh under ~/.claude/bin/ and the Stop / SessionStart / SessionEnd hooks in the project's .claude/settings.json (or .claude/settings.local.json with --local, or ~/.claude/settings.json) are NOT part of this file. Run ./install.sh --scope project --project <dir> from that repo before first use.

Used at clean boundaries (after a commit, when a major track wraps), when the user signals context pressure, or whenever the user invokes /handoff. Hands the next session a complete state snapshot so nothing gets lost across the restart boundary.

What this skill does

1. Snapshot state: runs write_handoff.sh (resolved from ~/.claude/bin/, see Steps below), which captures:
   • HEAD, branch, recent commits, working-tree state for the current repo
   • Same for an optional sibling "substrate" repo (configured via HANDOFF_SUBSTRATE_NAME, e.g. a shared decisions / RFCs repo)
   • In-flight (untracked or modified) .md docs under the configured directories (default: docs/; configurable via HANDOFF_INFLIGHT_DIRS)
   • The "verify state matches reality" command block
   • Before overwriting handoff_current.md, the script rotates the previous one into .claude/handoff_history/ and prunes to the last HANDOFF_HISTORY_KEEP (default 5). The next session's SessionStart hook auto-includes the most recent history entry if the current handoff has no curated Notes; /handoff-more lets a future session pull more of the history into context on demand. (Auto-compaction is also checkpointed: a PreCompact hook fires the same --if-curated safety net, so an uncurated session gets a mechanical snapshot before compaction destroys the conversation. That snapshot is a placeholder — running /handoff to curate is still the only path that captures intent.)
2. Replace the placeholder block with session-specific intent — the script's snapshot is git-state-only; the conversation knows things git doesn't (decisions made, in-flight ASKs, open questions, "next session should start with X" notes). The auto-generated file contains a ## Notes from this session section with a placeholder block bracketed by a <!-- HANDOFF_PLACEHOLDER: ... --> sentinel comment. Replace the entire placeholder block (sentinel + italic prose) with curated Notes using Edit — do not just append below the placeholder, because the SessionEnd safety-net detects "no curation happened" by the presence of that sentinel. Removing the sentinel is what tells the SessionEnd hook to stand down and preserve your work. Explicit fences for the next session go in the marker-wrapped ## Rules section, NOT in Notes (see Steps). After editing, re-sign with write_handoff.sh --restamp so the rules load as binding, not data.
3. Confirm the raw-dump backup exists — the Stop hook (handoff_turn_append.sh) has been appending turn-by-turn to .claude/handoff_backups/handoff_raw_<session_id>.md throughout the session, so by the time /handoff runs the backup is already there. Verify it: ls -la .claude/handoff_backups/. If the file is missing (hook not installed, or session started before the hook landed), fall back to writing a one-shot dump per the "Raw dump fallback" section below. The hook prunes to 3 newest automatically — you do not need to.
4. Print a loud, unmissable banner — the ASK must be impossible to miss (the user specifically asked for this; do not soften).
5. Stop. Do not start new work after the banner. The session is over.