Handoff

.agent/state.json and the map carry what has been settled. Neither carries the live thread — what is in flight right now, why this approach and not the other one, what was just tried and rejected. That is what compaction loses and what this document preserves.

Write it at a ticket boundary before /clear, or any time the context window has grown large enough that the next step deserves a fresh one.

Where it goes

The OS temporary directory — $TMPDIR on macOS, /tmp otherwise. Never the workspace.

A handoff is scaffolding for one session gap, not a project artifact. In the workspace it would become a third thing to keep in sync with the map and state.json, and would go stale the moment it was read.

Name it handoff-<ticket-or-topic>.md and give the user the full path so the next session can be pointed at it.

What it carries

• The live thread — what is in flight and why, in the conversation's own terms. What was tried, what was ruled out, what the next concrete step is.
• Suggested skills — which skills the next session should reach for.
• References, not copies — link the map, spec, ADRs, tickets, commits, and diffs by path or URL. Everything already written down stays where it is; the handoff points at it.
• Open questions — anything the user still owes an answer on.

Anything already captured in the map, a spec, an ADR, a ticket, a commit message, or a diff belongs in the references list, not the body. Copying it in creates a second copy that immediately starts drifting from the first.

Redaction

Strip API keys, tokens, passwords, connection strings, and personal data before writing. The temp directory is not a secret store.

Process

1. Identify the current ticket and phase from .agent/state.json.
2. Write the live thread — the reasoning that exists only in this conversation.
3. List references by path or URL.
4. Name the suggested skills for the next session.
5. Redact secrets.
6. Write to the temp dir and report the full path to the user.

Relationship to state.json

Complementary, not a replacement. state.json stays the machine-readable resume point the SessionStart hook reads automatically; the handoff is the human- and agent-readable thread that sits alongside it. Persist state.json as normal — a handoff never substitutes for it.

Scope

Keep the document to the live thread. When it starts restating the map or the spec, stop and link instead — a handoff that grows into a full project summary has become the artifact it was written to avoid.