handoff

Handoff

Write a handoff document summarizing the current conversation so a fresh agent can continue the work. Save it to the temporary directory of the user's OS — not the current workspace ($TMPDIR on macOS, /tmp as a fallback). Print the saved path so the user can pass it to the next session.

The reader is an agent with zero memory of this conversation. The document is its only context. Make it self-contained: enough to resume without asking the user anything, but no more.

What to include

• Task — what we're trying to accomplish, in one or two sentences.
• State — what's done, what's in progress, what's left. Be honest about what's verified vs. assumed vs. untested.
• Key decisions — choices made and the reasoning, so the next agent doesn't relitigate or accidentally reverse them.
• Gotchas — landmines, dead ends already explored, things that look wrong but aren't.
• Next steps — the concrete first actions for the new session.
• Suggested skills — which skills the next agent should invoke, and when.

Rules

• Don't duplicate other artifacts. PRDs, plans, ADRs, issues, commits, and diffs already capture their own content — reference them by path or URL instead of restating them.
• Redact sensitive information — API keys, passwords, tokens, PII. Never copy a secret into the handoff.
• Tailor to the next focus. If the user passed an argument, treat it as a description of what the next session will work on and shape the document around that. Cut anything irrelevant to it.
• Keep it tight. A handoff is a launchpad, not a transcript. If it reads like a meeting recap, cut it down.