craft-handoff
craft-handoff
Purpose
End the current session cleanly by producing two paired artifacts the next session is intended to use together:
- A rich handoff doc at
~/.craftkit/handoff/docs/<worktree-slug>.md— narrative-first, depth scales with what actually happened in the session. The durable record of how this session got here: decision rationale in long form, what didn't work, abandoned approaches, time-ordered progress, related external context. Per-project, overwritten on the next handoff for the same project (previous version archived). - A craft-prompt-grade prompt at
~/.craftkit/handoff/pending/<timestamp>-<worktree-slug>.md(mirrored to clipboard) — structurally complete (context / task / rules / success criteria), and explicitly commands the next agent to read the handoff doc first to fully restore prior context before acting. Per-session, never overwritten.
The prompt is what gets pasted (or auto-loaded by the SessionStart hook). The doc is what the prompt instructs the agent to read. Both are part of the intended workflow — the prompt is not a "fallback if the doc is missing"; it is the entry artifact that orchestrates the resume, and the doc is its required reading. Modern Claude / GPT context windows handle this pair comfortably; the depth wins back the turns saved by not having the next agent ask "why did we do X?"
This pairs the patterns that mature AI session-handoff designs converge on (Cline memory-bank, BMad story-files, claude-code-context-handoff): a structured entry artifact + a deeper durable doc.
This is not a session-summary doc for humans, and not a single compact prompt. The pair is the unit of handoff.