Session Handoff

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

Workflow

save  --> append snapshot at top of .artifacts/.session-handoff.md
load  --> Read .artifacts/.session-handoff.md; latest snapshot at top
clear --> overwrite .artifacts/.session-handoff.md with empty content

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

Clear

Write empty content to .artifacts/.session-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.