Write the document your next agent opens before it works. A handoff compacts everything that matters about a long-running task into one structured markdown file, so an agent with an empty context window resumes exactly where you left off — without re-reading the conversation.
When to use
Manual — the user asked: a handoff / state save / "next plan of action". Write the file. Automatic checkpoint — when the host requests a context handoff, write the file and append the auto-continue note (step 7). A file-edit count alone is not a reason to interrupt authorized work.
Pipeline (summary)
gather → structure → write → verify → resume. Full detail in ref/pipeline.md.
- Preflight. Capture the known goal and next action even if little work has happened. If neither exists, say "Nothing to hand off yet"; never fabricate progress.
- Gather mechanically. Derive read/modified sets from tool history; capture commands, test output, and error text verbatim; confirm git branch/HEAD/dirty via read-only probes. Never trust recall.
- Preserve the open thread. Capture any unanswered user question VERBATIM (the most-failed item) → Open Questions, and Current State if it blocks the next step.
- Structure. Fill
ref/templates/handoff.md—-coding.mdfor a feature build,-debugging.mdfor an investigation — in order: Current State first; Done labeled "DO NOT REDO" + quantified; ONE next step; decisions with rationale; concrete file:line / commands / real errors. - Self-verify. Run
ref/checklists/quality.md; fix any secret, placeholder, vagueness, missing verify command, or dropped open question before writing. - Write. Save
handoffs/handoff-<UTC>.mdin the working project (ISO 8601,:/.→-, e.g.handoff-2026-05-30T12-00-00-000Z.md); chain and merge a prior handoff if one exists. - Emit + report. Print the path + a one-line summary, then the doc wrapped in
<handoff-context>…</handoff-context>(exact wrapper in ref/pipeline.md) as the paste-ready resume block. - (Auto trigger only) Add the auto-continue note: honor the user's LATEST intent; say so if nothing remains.
Reference files
- ref/pipeline.md — the full step-by-step pipeline and cold-resume failure modes
- ref/templates/handoff.md — the document template (general)
- ref/templates/handoff-coding.md — feature-build variant
- ref/templates/handoff-debugging.md — bug/debug variant
- ref/checklists/quality.md — pre-write self-verification gate
- ref/checklists/resume.md — what the RESUMING agent does first
- examples/ — filled handoffs you can imitate
- scripts/check-staleness.sh — validate a handoff before trusting it
Hard rules
- Capture exact technical state, not abstractions — paths, symbols, commands, real errors.
- Never include secrets, tokens, or keys.
- Producing the artifact is the whole job: reply with it and where it lives, and route the conversation's own questions into Open Questions rather than answering them.
- The file is the source of truth; the
<handoff-context>block is its transport.