Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the OS temp directory, resolved explicitly ($env:TEMP on Windows; $TMPDIR, else /tmp, on Linux / WSL / macOS) - not the current workspace. A bare /tmp/... path reaching a Windows-native tool (node, python, pi's write) resolves to C:\tmp\... instead, so pass the resolved absolute path on Windows.
Report the document's path back to the user as a copy-paste-ready pi @ mention: one leading @, the absolute path with forward slashes, wrapped in double quotes, and nothing else on that line. Example: @"C:/path/to/handoff-xyz.md" on Windows (the %TEMP% directory, e.g. under AppData/Local/Temp); @"/tmp/handoff-xyz.md" elsewhere.
The quotes are load-bearing, not decoration: in pi's prompt editor, @ opens a fuzzy file-completion popup, and pressing Enter while it is open applies the popup's top suggestion instead of sending. An unquoted or backslash-slashed Windows path after @ becomes one long completion token that the popup clobbers on Enter. The quoted form (@"...") ends the token at the closing quote, so no popup ever opens and the pasted path survives verbatim. Keep the closing quote last on its line - a . or / after it starts a new completion prefix.
Also give the bare forward-slash path (e.g. C:/path/to/handoff-xyz.md) for CLI launches: start pi with pi @C:/path/to/handoff-xyz.md. The shell strips its own quoting before pi parses @file args, so quote marks there break resolution.
Open the document with a handover preamble addressed to the next agent, worded to force an alignment stop before any work:
You are the incoming agent. Read this document and every artifact it references in full before doing anything else. Then reply with your understanding of four things: the goal, the current state, the next steps, and the risks. Wait for the user's confirmation before starting work.
Include a "suggested skills" section in the document, naming which skills the next agent should load (read each SKILL.md and follow it) and in what order.
Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.