/handoff

/handoff — Context handoff manager

Subcommand argument received: $ARGUMENTS

Dispatch

Inspect $ARGUMENTS (case-insensitive, trimmed) and run the matching flow below.

Argument	Flow	Effect
empty / none	WRITE (default)	Draft + confirm + write .claude/HANDOFF.md
clear	CLEAR	Archive or delete .claude/HANDOFF.md
status	STATUS	Show current handoff preview (read-only, no prompt)
list	LIST	List active + archived handoffs
help	HELP	Show subcommand menu
anything else	HELP + warn unknown	Unknown subcommand: <x>. Showing help…

---

HELP flow

Output exactly:

/handoff — Context handoff manager

  /handoff              Write or update .claude/HANDOFF.md (default)
  /handoff clear        Archive or delete .claude/HANDOFF.md
  /handoff status       Show current handoff preview (read-only)
  /handoff list         List active + archived handoffs in .claude/
  /handoff help         This menu

Loader hook auto-injects HANDOFF.md at SessionStart (full <24h, pointer 24h-7d, STALE >7d).
Use /handoff before pausing work, /handoff status to peek, /handoff clear when done.

Then stop. No further action.

---

STATUS flow

1. Check ./.claude/HANDOFF.md. If absent, output:

   ∅ No HANDOFF.md in this project at ./.claude/HANDOFF.md
   

   …and stop.

2. Read frontmatter. Display preview (no edits, no questions):

   HANDOFF.md
   ─────────────────
   Path:    .claude/HANDOFF.md
   Updated: <relative>
   Tokens:  ~<n>
   Summary: <text>
   Resume:  <text or "—">
   ─────────────────
   

3. Stop. Do not prompt or modify.

---

LIST flow

Run ls -lat ./.claude/HANDOFF*.md 2>/dev/null (Bash). Output:

Handoffs in this project:

  ACTIVE:
    HANDOFF.md                              <relative time>

  ARCHIVES:
    HANDOFF.archive-2026-05-10-143022.md    <relative time>
    HANDOFF.archive-2026-05-08-091500.md    <relative time>

If no active: omit ACTIVE section, show only ARCHIVES. If no archives: omit ARCHIVES section. If neither: output ∅ No handoff files in .claude/.

Stop. No prompts.

---

CLEAR flow

1. Check ./.claude/HANDOFF.md. If absent:

   ∅ No HANDOFF.md to clear at ./.claude/HANDOFF.md
   

   …and stop.

2. Read file. Display preview block (same format as STATUS).

3. Use AskUserQuestion with three options:

   • Archive (Recommended) — rename to .claude/HANDOFF.archive-YYYY-MM-DD-HHMMSS.md. Loader ignores archives.
   • Delete permanently — rm the file. Recoverable only via git if tracked.
   • Cancel — no change.

4. Execute:

   • Archive → mv ./.claude/HANDOFF.md ./.claude/HANDOFF.archive-$(date -u +%Y-%m-%d-%H%M%S).md. Confirm new path.
   • Delete → rm ./.claude/HANDOFF.md. Confirm removed.
   • Cancel → output Cancelled. HANDOFF.md unchanged.

5. After clear, suggest: /handoff to write a fresh handoff, or leave clean if work is done.

Safety rules

• Never silent-delete. Always preview + confirm.
• Default to Archive (loss-resistant).
• Never bulk-clean archives. User manages those manually.

---

WRITE flow (default)

Generate or update ./.claude/HANDOFF.md so the next session resumes cleanly.

1. Locate target

• Ensure ./.claude/ exists (create if missing).
• Target: ./.claude/HANDOFF.md.
• If file exists, Read it first — treat as prior state, update don't overwrite blindly.

2. Pre-draft verification (REQUIRED — do not skip)

Run these and capture output. Build State from this evidence, NOT transcript impressions.

git status --short                    # uncommitted changes
git diff --stat                       # what's actually modified
git log --oneline -10                 # recent commits
git diff --cached --stat              # staged but not committed

If not a git repo: find . -type f -mtime -1 -not -path './node_modules/*' -not -path './.git/*' | head -20.

Use as ground truth. Anything claimed as [done] must show in commits or git diff --stat. Anything in git status but not committed = [wip].

3. Draft using strict template

---
updated: <ISO 8601 UTC>
summary: <one line, <100 chars — current state for quick scan>
resume: <one line, <80 chars — concrete first action to take when resuming>
inject: <optional: "full" or "pointer" to override loader auto-decision>
---

# Handoff

## Task
<2-3 lines: what + why. No fluff.>

## State
- [done] <thing> — evidence: `commit abc1234` or `path/to/file.ts:42`
- [wip] <thing> — evidence: shows in `git status`, not committed
- [planned] <thing> — NOT started, just intended

## Files
- `path/to/file.ts:42` — <one-line note on what's there>

## Decisions
- [locked] <choice> — rationale (must have code/commit backing this)
- [tentative] <choice> — rationale (no code yet, may change)

## Blockers
- <thing> — verbatim error: `EXACT_ERROR_TEXT_FROM_TERMINAL`
- <thing> — what's needed to unblock

## Next
1. <concrete step>
2. <concrete step>

4. Accuracy rules (HARD)

• resume: field required. Should match Next #1, paraphrased into one short imperative line.
• State tags required. Every bullet under State gets [done] / [wip] / [planned]. No untagged items.
• Evidence required for [done]. Cite commit hash or file:line. If you can't cite, demote to [wip].
• Decisions tagged. [locked] only if backed by committed code. Otherwise [tentative].
• Errors verbatim. Copy-paste exactly. Never paraphrase. Wrap in backticks.
• No aspirational claims. Discussed-but-not-built → goes under Next, not State.

5. Per-item confirmation

Before writing, present draft. For ambiguous items (e.g. "we tried X" — kept or reverted?), use AskUserQuestion: "Item: <text> — keep as [done] / change to [wip] / drop?". Cap at 4 items per call. Skip confirmation only for items with rock-solid evidence (committed hash that exists in git log).

6. Final confirm + write

Show full draft. AskUserQuestion: "Write to .claude/HANDOFF.md? [Yes / Edit section / Cancel]"

• Yes → Write file.
• Edit section → Ask which, revise, re-confirm.
• Cancel → Discard. No file change.

7. Token budget

Target <600 tokens (~2400 chars). Hard cap 2000 tokens (~8000 chars) — beyond this loader forces pointer mode regardless of freshness. Compress aggressively if exceeding.

Edge cases

• Task fully complete. Ask: "Task appears done. Run /handoff clear instead of writing stale resume state?"
• Pivoting to unrelated work. Ask: "Current session is unrelated to existing HANDOFF.md. Replace, append a section, or leave alone?"
• No git history at all. Use find -mtime -1 for evidence. Flag explicitly that evidence is filesystem-only, not commit-backed.

Why these rules exist

• Aspirational [done] items = #1 handoff failure mode.
• Verbatim errors preserve debug grep-ability.
• Tentative-as-locked decisions cause next session to skip re-evaluating still-open choices.
• Git as ground truth removes "I think we did X" guesswork.