By name: handoff description: Write a handoff brief summarizing the current conversation so a fresh agent can pick up the work. Writes to a file if given, otherwise copies to the clipboard. argument-hint: "[filename]" disable-model-invocation: true allowed-tools: - Bash(pbcopy) - Bash(pwd) - Bash(git status:) - Bash(git log:) - Bash(git diff --stat:) - Bash(git rev-parse:)
Handoff Brief
Write a compact, actionable brief that lets a fresh agent (with empty context) resume where this conversation left off.
Arguments
$ARGUMENTS
If a filename is given, write the brief there. Otherwise pipe it to pbcopy.
Instructions
1. Gather lightweight repo state
Run only what's relevant — don't dump everything. Typical:
pwd
git rev-parse --abbrev-ref HEAD
git status --short
git log --oneline -5
git diff --stat
Skip git commands entirely if the work isn't in a repo or the state is irrelevant (e.g. pure research conversation).
2. Synthesize the brief
Use the structure below. Keep it dense — a fresh agent reads this cold and should be able to continue within a minute. Omit sections that don't apply; don't pad.
# Handoff: <one-line task title>
## Mission
<1–3 sentences: what the user is trying to accomplish and why it matters.>
## State
- **Cwd:** <path>
- **Branch:** <branch> (omit if not in a repo)
- **Uncommitted:** <short summary of dirty files, or "clean">
- **Last commit:** <sha — subject>
## Done
- <Completed step> — `path/to/file:line` if relevant
- ...
## In progress
- <What's actively being worked on; include the specific file/line and what's half-finished>
## Next steps
1. <First concrete action>
2. <Next>
3. ...
## Decisions made
- **<decision>** — <why>. Rejected: <what was considered and discarded>.
## Don't redo
- <Approach already tried that failed> — <why it didn't work>
## Open questions
- <Question for the user or new agent to resolve>
## Key files
- `path/to/file:line` — <why it matters>
## Useful commands
- `command` — <what it does in this context>
3. Deliver
If $ARGUMENTS is non-empty → treat it as the filename and write the brief there with the Write tool. Report the absolute path.
If $ARGUMENTS is empty → pipe the brief to pbcopy:
pbcopy << 'HANDOFF_EOF'
<the brief>
HANDOFF_EOF
Confirm "Handoff copied to clipboard" with a one-line summary of what's in it.
Principles
- Cold-read test: assume the next agent sees nothing but this brief. No "as discussed above" or pronouns without antecedents.
- Specific over comprehensive: include file paths, line numbers, command names. Don't restate code; point to it.
- Capture the why: decisions and dead-ends save more time than re-explaining what's done.
- No filler: drop sections that are empty. A short brief beats a padded one.
- Don't leak secrets: scrub tokens, passwords, or private endpoints before writing.
Examples
/handoff → copy brief to clipboard
/handoff HANDOFF.md → write brief to ./HANDOFF.md
/handoff /tmp/auth-refactor.md → write brief to absolute path
/handoff notes/today.md → write brief to nested path (create dirs as needed)