| name | handoff |
| description | Write a handoff document so a fresh Codex agent can continue this work after the conversation ends. Invoke when the user is about to clear or compact context, when context is filling up, or when the user asks to hand off, checkpoint, pause, or resume work later. Optional user text may specify what the next session should focus on. |
The conversation is about to end or be cleared. A fresh agent will continue without any of this conversation's history — write it what it needs to pick up cleanly.
Save to the OS temp directory (`$TMPDIR`, falling back to `/tmp`), e.g. `/handoff-.md` — **not** the repo. A handoff is ephemeral conversation state, not durable project knowledge (durable knowledge belongs in the project-owned agent-knowledge graph rooted at `AGENTS.md`). Tell the user the absolute path at the end so they can point the next agent at it.
Write for an agent with zero context. Be concrete — file paths, not vague descriptions; the *why* behind decisions, not just the *what*.
- Goal & current state — what we're doing and why; where we are (planning / implementing / debugging); whether the codebase is working, broken, or half-done.
- Decisions made & why — especially trade-offs a fresh agent would otherwise re-litigate or accidentally undo.
- What's pending — remaining work and the single next immediate step; known blockers.
- Orientation — the few files to read first, non-obvious patterns/gotchas, and any user preferences expressed this session.
- Open questions — unresolved decisions waiting on the user.
- Suggested skills/agents — which promode agents or skills the next session should reach for.
- **Reference, don't duplicate.** Anything already captured in commits, PRDs, plans, ADRs, issues, or the knowledge graph → link it by path, don't restate it. The handoff is the connective tissue between those artifacts, not a copy of them.
- **Redact secrets** — no API keys, passwords, tokens, or PII in the document.
- If the user passed an argument, treat it as the next session's focus and tailor the doc to it.
1. Show the user a short summary of what you captured.
2. Ask: "Anything else to capture before you clear?" — iterate if they flag gaps.
3. End with the absolute path and a one-line pointer for the next agent:
`Handoff ready: — the next agent should read this first.`
