repo-handoff

Codex form of the /repo:handoff command. Other commands appear as $repo-<verb> skills. Helper scripts and .claude/ paths below are relative to the repository root and exist when the Claude Code surface is installed alongside this one.

$repo-handoff — Roll the Session Safely

Rolling a Claude Code session — quitting the CLI and starting fresh — is the moment a session's most valuable output is most likely to be lost, because what is worth carrying forward is exactly what exists only in the session's context: in-flight state, settled decisions, and empirically-discovered traps. This command makes the roll a repeatable ritual instead of an ad-hoc scramble.

It composes the existing commands rather than reimplementing them — [[followups]] to capture deferred work, [[reset]] to reach a clean git baseline — and adds only what does not exist yet: the CLI version check, the handoff note, and exact restart instructions.

Relationship to /compact: compaction handles the soft boundary — context pressure within a continuous session. $repo-handoff handles the hard boundary: process restart, CLI upgrade, or a deliberate fresh start. If the version check below finds no update and the only pressure is context size, say so — a /compact may be all that's needed.

Usage

$repo-handoff                  # Run the ritual end-to-end, confirmations as usual
$repo-handoff --dry-run        # Preview the note and proposed actions; file, prune, and write nothing
$repo-handoff --prune          # Pass --prune through to the reset stage
$repo-handoff --force          # Proceed even when the step-0 preflight fails

Steps — ordering is load-bearing

Run the stages in exactly this order. Each later stage depends on the earlier ones having actually happened.

0. Preflight — confirm something will actually read the note