/handoff-revive

name: handoff-revive
description: Save a compact handoff checkpoint and resume work in a fresh session without replaying the entire transcript via `--resume`. SAVE trigger — the slash command `/handoff-revive:save` (carries forward still-relevant goal/decisions/lessons from any existing handoff, then runs a content-quality check). AUTO-SAVE trigger — when the UserPromptSubmit hook injects "5-hour usage at N%" context (run SAVE flow without asking, prepend brief notice). RESUME trigger — the slash command `/handoff-revive:resume`. Also use when the SessionStart hook surfaces an existing handoff at `.claude/handoff/current.md` — read that file instead of recommending `claude --resume`. Configuration via `/handoff-revive:auto on|off|status` (per-session toggle). Do NOT trigger on natural-language phrases like "save handoff" / "ハンドオフ保存して" / "続きから" — only the slash commands and hook contexts above.

handoff-revive

Save the minimum state needed to continue work later, so the next session can start fresh (NOT via `--resume` / `-c`) and reload only a small file.

Why not `claude --resume`

`--resume` and `-c` replay the entire prior transcript into context. For a typical session this costs **tens of thousands of tokens** (often **100k+ for long sessions**) before the user even asks anything. A handoff file costs **1,000–3,000 tokens**. Always prefer the handoff file when one exists.

Two modes

Mode 1: SAVE (`/handoff-revive:save`)

Triggered ONLY by:

• User runs the slash command `/handoff-revive:save`
• The UserPromptSubmit hook injects auto-save context (see Mode 1c below)

Do **NOT** trigger on natural-language phrases like "save handoff", "checkpoint", "ハンドオフ", "保存", "保存して中断". Users are expected to use the slash command. If a user types one of those phrases without the slash command, treat it as a regular message (gently remind them they can run `/handoff-revive:save` if they want to save).

Steps:

1. **Detect language** — read `.claude/handoff/lang` if it exists. Trim whitespace; the file holds a language code (one of: `ja`, `en`, `zh` (Simplified), `zh-TW` (Traditional), `ko`, `es`, `pt`, `de`, `fr`, `tr`) with no trailing newline. Otherwise detect from the user's most recent message:

• Hiragana/Katakana → `ja`
• Hangul → `ko`
• Han characters: simplified markers (e.g. 这, 国, 学) → `zh`; traditional markers (e.g. 這, 國, 學) → `zh-TW`
• Cyrillic / Arabic → fall back to `en`
• Latin script: detect by common diacritics + words:
• `é à è ç` + words like *fichier*, *avec*, *est* → `fr`
• `ä ö ü ß` + words like *Datei*, *und*, *ist* → `de`
• `ã õ ç` + words like *arquivo*, *está*, *para* → `pt`
• `ñ` + Spanish words (*archivo*, *está*, *con*) → `es`
• `ı ş ğ ç` + Turkish words (*dosya*, *için*, *çalış*) → `tr`
• Otherwise → `en`

When the message is mixed or ambiguous, default to `en`. Write the chosen code to `.claude/handoff/lang` (no newline) using your file-write tool. Subsequent saves reuse the persisted value unless the user explicitly asks to switch language.

2. **Carry forward, then fill the schema** — if `.claude/handoff/current.md` already exists, read it first and preserve any `goal`, `decisions`, and `lessons_learned` that are **still relevant** (drop what is now obsolete). This matters in long sessions: details captured in an earlier save survive even if they have since scrolled out of your context. Then write the full handoff to `.claude/handoff/current.md` using the template below. All section keys stay in English (machine-readable); section *values* go in the user's language. If approaches were tried and abandoned this session, record them under `## lessons_learned` (attempted / why_abandoned / learned); omit the section if there were none.

**Overwrite guard**: if `.claude/handoff/current.md` already exists and its `branch:` metadata differs from the current git branch, it likely belongs to *different work*. Ask the user before overwriting it (e.g. "既存の handoff は別ブランチ (feature/x) の作業のものです。上書きしますか?"). In AUTO-SAVE mode (Mode 1c), do not ask — proceed, but mention the cross-branch overwrite in the notice.

3. **For `next_action`: be executable.** Not "continue refactoring auth" but `Edit src/auth/login.ts:42 — replace the bcrypt.compare call with the timing-safe variant from line 88`. Include the exact file:line and the exact next command/edit. The goal is zero "thinking time" on resume.

4. **For `touched_files`: format as `path -- one-line reason`.** Use ` -- ` (space, two dashes, space) as the separator, NOT `:`, because Windows absolute paths contain a colon (`C:\...`) and would break the schema. Always prefer **project-relative paths with forward slashes** (`src/auth/login.ts`); fall back to absolute paths only when the file is genuinely outside the project. No diffs, no line ranges — just enough to re-orient.

**Token-saving helper (recommended)**: instead of thinking through which files to list, run `extract-recent-files` to get a deterministic list from `git status` (or `find -mmin` if non-git). This saves ~200–500 tokens per save:

• Linux/macOS/WSL/Git-Bash: `bash "${CLAUDE_PLUGIN_ROOT:-.claude}/skills/handoff-revive/scripts/extract-recent-files.sh"`
• Windows PowerShell: `$r = if ($env:CLAUDE_PLUGIN_ROOT) { $env:CLAUDE_PLUGIN_ROOT } else { ".claude" }; powershell -ExecutionPolicy Bypass -File "$r/skills/handoff-revive/scripts/extract-recent-files.ps1"`

The script outputs `- <path> -- <reason>` lines (max 20). Paste them under `## touched_files`, then refine reasons where the auto-generated `modified` / `untracked` doesn't capture intent (e.g. "needs rollback" / "validated; do not touch").

5. **Run `finalize-handoff`** — single zero-token call that does validate + cleanup + savings report. Path uses `${CLAUDE_PLUGIN_ROOT:-.claude}` so the same command works in plugin and standalone installs:

• Linux/macOS/WSL/Git-Bash:

     bash "${CLAUDE_PLUGIN_ROOT:-.claude}/skills/handoff-