| name | handoff |
| description | Produce a dense, copy-pasteable handoff that lets a fresh, memoryless agent resume the current thread of work. Use when wrapping up a session, running low on context, pausing work, or handing the active task to a new agent window. |
| user_invocable | true |
handoff
Emit a single copy-pasteable block that lets a fresh agent with no memory resume the
one task currently in flight — nothing else from the session.
Core principle — pointers over payloads. A fresh agent has tools: it can read files,
run git log, read issues. So point to anything it can cheaply re-derive; spend tokens
only on what dies when this session ends — the decisions, the rationale, the approaches
already ruled out, and what the user said they want. That irreplaceable signal is the
handoff's real cargo. Everything else is a reference.
When to use
- Context is running low and work must continue in a new window.
- Pausing a task to resume later or hand to another agent.
- The user says "hand this off", "write a handoff", "/handoff".
Output
One fenced code block in the chat response, preceded by a one-line "paste this into a new
agent" preamble. Write nothing to disk and commit nothing — a stray handoff file on a
working branch is exactly what this avoids.
Procedure
- Find the active thread. Isolate the one task in flight. If genuinely ambiguous
(two unrelated live threads), ask the user one question to pick before generating.
Otherwise infer it.
- Fill the template (below) from the session.
- Gap-check (private). Ask yourself: what would a newcomer need to ask to act
correctly here? Fold any missing answers into the template. These questions are
scaffolding — they never appear in the output.
- Compress. For every line apply the rule: can a fresh agent cheaply re-derive this
with its tools? Yes → replace with a pointer (
path:line-range + one line of why).
No → keep it inline. Inline a short code/state excerpt only when the target is
volatile or hard to locate. Drop anything that fails both "needed to act" and
"can't recover".
- Emit the block. Omit any empty section. Telegraph English — drop articles and
filler, keep load-bearing nouns and verbs.
Template
Emit exactly these sections (skip any that are empty):
# Handoff: <one-line task title>
## Goal
<the durable why — what success ultimately looks like>
## State
<done · in-flight · exactly where we stopped>
## Next move
<the single concrete first action — a command or edit, not a direction>
## Key locations
<path:line-range · issue # · branch · command — one pointer per line, each with why>
## Decided / rejected
<choices made + why · approaches tried and ruled out>
## Gotchas & scope guard
<constraints · do-NOT-do-X · things that bit us>
## Verify
<how the new agent knows it succeeded>
## First move
read <X>, run `git status`, then continue: <Y>
Decided / rejected and Gotchas & scope guard are the irreplaceable sections — weight
them. Key locations is where the pointer discipline pays off.
Guard rails
- No secrets in the block — never inline
NUGET_API_KEY, GITHUB_TOKEN, any
*_TOKEN / *_SECRET / *_KEY value, bearer tokens, or raw payloads. Point to where
they live instead.
- Read-only — generating a handoff reads the session and the repo; it writes no file
and runs no mutating command.
Common mistakes
| Mistake | Fix |
|---|
| Pasting file contents the new agent could just read | Point to path:line-range + one line of why |
| Recapping the whole session | Only the one active thread |
| Vague next step ("continue the refactor") | One concrete action — a command or a specific edit |
| Dropping the why behind a decision | That's the irreplaceable part — always inline it |
| Emitting the self-interrogation Q&A | It's private scaffolding; emit the filled template only |
