handoff

name	handoff
description	Save current conversation state to disk so a later session resumes with full context. Captures focus and next step, plus optional decisions, findings, open threads, blockers, and references; appends snapshots newest-at-top. Use when ending a session before context loss, checkpointing mid-session, saving, loading, or clearing a handoff, or starting a session that should continue prior work. Not for end-of-session persistence across memory systems or for repository-wide project context.
argument-hint	[focus]

Handoff

Capture conversation state to .artifacts/HANDOFF.md so a later session resumes with full context. Three ops: save, load, clear.

Triggers

• Save ("save context", "dump conversation", "checkpoint this", "session handoff", "save handoff") → save.md
• Load ("resume session", "load handoff", "continue from last") → load.md
• Clear ("clear handoff", "reset handoff") → see Clear below

Workflow

save  → append snapshot at top of .artifacts/HANDOFF.md
load  → Read .artifacts/HANDOFF.md; latest snapshot at top
clear → overwrite .artifacts/HANDOFF.md with empty content

Clear

Write empty content to .artifacts/HANDOFF.md. Do not delete the file — an empty file is treated as missing on next load, and writing avoids a Bash permission prompt. Silent no-op when the file is already absent.

Guidelines

• Append snapshot at top, never bottom — most recent always first
• One snapshot per save; do not merge across saves
• Skip ops silently when file is absent (load and clear no-op)
• Save what is not already in committed artifacts — focus, open threads, next step, decisions and findings worth carrying

Anti-Pattern: Restating Artifacts

Snapshots that repeat content already captured in artifacts on disk, commits, PRs, issues, or documentation waste space. The handoff carries context that lives only in the conversation: unresolved threads, decisions made on the fly, where to pick up, which skill to invoke next. Anything already persisted elsewhere should be referenced by path or URL, not duplicated.

Anti-Pattern: Overwriting on Save

Each save prepends a new dated block at the top. Overwriting destroys prior snapshots that may still hold useful context for older threads. Append-at-top preserves history while keeping the latest visible first.