Turn everything learned in this conversation into a single handoff document a fresh agent, with none of this context, can read and continue from. The point is transfer, not archival: capture the state and reasoning that only lives in this session, and point at the artifacts that already exist (specs, PRs, commits, diffs, issues) rather than copying them. By default, save it as a Markdown file under ; print it as a copy-pastable block only when the user explicitly asks for inline or terminal output, or when no writable filesystem is available.

The user wants continuity across a context boundary: "write a handoff", "hand this off", "summarize for the next session", "pass this to another agent", "compact this before we run out of context". If they give an argument (e.g. "handoff for finishing the migration"), treat it as the focus of the next session and slant the whole document toward it. Lead with what that goal needs and prune what it doesn't.

A handoff earns its keep by carrying what a new agent can't reconstruct:

Write these sections; drop any that are genuinely empty rather than padding them.

Two registers, split by section. Current state, Next steps and How to run / verify are read by someone who is doing the work, so write them in ASD-STE100 Simplified Technical English: one instruction per sentence, procedural sentences 20 words or fewer, active voice, present tense, name the actor, no metaphor or idiom, and one term per thing for the whole document. If the top calls it the worker, the bottom does not call it the job runner. Goal and Decisions & constraints are read by someone forming a judgment before they touch anything, so they keep ordinary prose with the reasoning intact; flattening a rejected approach into clipped steps strips the why that stops the next agent repeating it.

undefined

What we're trying to achieve and why. If the user gave a focus argument, frame this around it.

What's done and working, what's half-done, what's untouched. Be concrete.

The ordered actions the next agent should take. Start with the very first one.

Paths and URLs that matter (source files, the spec, the open PR, the failing test). Reference, don't reproduce.

Choices made and why; approaches already ruled out; hard limits and things not to break.

Unknowns, pending answers, or anything waiting on the user.

Commands to build, run, or test, enough to reproduce the current state.

Capabilities the next session should reach for, e.g. a commit skill to land the work, a PR skill to open the pull request, a test-plan skill to verify. Name them by function, not by a specific tool that may not be installed. Recommend by relevance to the goal.

undefined

Default: save a Markdown file. Write the finished handoff into in the workspace, creating that directory if it doesn't exist. Name it , using a short lowercase kebab-case subject slug and the handoff's ISO creation date at the end (for example, ). Keep that date stable if the same handoff is edited, and update the existing file in place. If a genuinely distinct handoff would collide on the same day, make the slug more specific; only as a last resort insert the next available sequence immediately before the date (). Tell the user the exact path.

On explicit request: print inline. When the user explicitly asks for terminal, inline, chat-only, or copy-pastable output, emit the finished handoff as a single Markdown codeblock and do not write a file.

No writable filesystem: degrade gracefully. If the environment cannot write files, emit the finished handoff as a single Markdown codeblock and say that no file was created.

What changed. Nothing in the project itself; the handoff is a new (or updated) document, and say which.

Where it landed. Give the exact path (), or "printed inline, no file written" when that's what happened.

Next. One move. Start a fresh session pointed at this document, beginning with the handoff's own first next-step. Name that step here so the user doesn't have to open the file to learn it. Nothing else follows in this session; the whole point of the handoff is that this context can now end.