Use when the user wants to stop the current session and hand off work to a fresh agent, when context is getting too high, or when explicitly asked for a handoff
Write a structured handoff document so a fresh agent can continue the current work. Then stop.
Core principle: Capture current state concisely — what matters is what the next agent can't easily rediscover from the codebase.
Announce at start: "Writing handoff document."
Run these in parallel:
git branch --show-current
git status
git log --oneline -10
git stash list
Write HANDOFF.md at the project root with ALL of these sections (do not skip any):
# Handoff: <brief task description>
## Branch
`<current-branch>`
## Goal
<1-2 sentences: what the USER is trying to accomplish — their intent, not just the technical task>
## What Was Done
<numbered list of completed work, with file paths>
## User Decisions
<decisions the user made during this session that a fresh agent can't rediscover from the code — design choices, rejected alternatives, preferences expressed in Q&A. Skip if no significant decisions were made.>
## In Progress
<what was actively being worked on RIGHT NOW when stopped — the specific file, function, or problem being debugged. If mid-design or mid-brainstorm, include the approved content so far (tables, specs, criteria) so the next agent doesn't re-present it. This is the most important section.>
## Known Issues
<bugs, blockers, failed attempts — include exact error messages verbatim>
## Unstaged / Uncommitted Changes
<list files from git status that have unsaved work, and briefly describe each>
## Next Steps
<ordered list of concrete actions — include file paths and commands, not vague descriptions>
## Key Files
<list of specific files with line numbers that the next agent should read first — only include files that aren't obvious from the task description>
Every section is mandatory. If a section has nothing, write "None." — do not omit it.
Rules:
After writing the file, tell the user:
Handoff written to HANDOFF.md. To continue in a new session, say "pick up where we left off" or use /pickup.
Do not take any further actions. Do not offer to do more work. The handoff is complete.
Writing too much
Missing the "in progress" state
Vague next steps
Losing user decisions from brainstorming/Q&A
Missing key file pointers