Handoff

---
name: 'handoff'
description: 'When the human types `/handoff` (or "next session", "what''s next", "handoff note"), produce a copy-paste markdown block for the next session.'
disable-model-invocation: true
---

When the human types `/handoff` (or "next session", "what's next", "handoff note"), produce a copy-paste markdown block for the next session. Top half is human-scannable; bottom half is pure agent instructions for next session's start-up. This is the closing half of the pair that makes sessions continuous: handoff writes the note, start-up reads it.

## Precondition: the background-work barrier

Handoff may not emit while any background task spawned this conversation is unresolved: await finite work, act on landed-but-unhandled results, retire session daemons, or (narrowly, never for a verification task) abandon with the reason written down. Right after wrap-up this is a quick re-check that nothing new was spawned; standalone, the full barrier applies first. See AGENTS.md § The background-work barrier.

## Pull request authority

Invoking handoff is explicit permission to resolve pull requests created by the work being handed off. Do this before writing the handoff note:

1. Inspect the exact head commit, base branch, required reviews, and checks.
2. If the pull request is ready and the work is meant to ship, merge it using the repository's merge policy. Never bypass a failed check or required review.
3. If the pull request is superseded, abandoned, or should not ship, close it without merging.
4. Prove the final GitHub state, clean up the resolved branch, synchronize the base branch, and verify any resulting base-branch check.

This authority is narrow. It covers pull requests created by this session or explicitly named in the work being handed off. It does not cover unrelated pull requests, product or provider changes, spending, deployment, or any other external effect. If an in-scope pull request cannot be resolved safely, leave it open and state the exact blocker in the handoff.

## Voice

The output IS chat to the human: follow AGENTS.md § Voice, including in every fill-in. Pipe the draft through `node scripts/voice-gate.js` before sending.

## Locked template

Output is ONE fenced markdown code block. Inside it:

````markdown
## Handoff

{One paragraph for the human: what the session that just ended focused on, what's left over, and the recommended focus for next time. About 3-5 sentences of plain English. No file paths in the prose, no unexplained acronyms, no marker tags.}

- {Key context bullet 1}
- {Key context bullet 2}
- {Up to 4-5 bullets max}

---

**For the agent:**

Start with `/start-up`. Draw up a plan focused on **{recommended focus, one phrase}** using construct-the-plan. If open questions remain after the draft, run `/frame-it` and get the human's answers. Then STOP and wait: the human queues the challenge rounds, `/build-it`, `/test-it`, the implementation challenges, and `/wrap-up`; never start them unprompted.

**Specific items to pick up (agent-doable without the human):**
- {Item 1 with file path or scope}
- {Item 2}

**Needs the human's input, do NOT pick up unsupervised:**
- {Item, or "None"}

**Out of scope:**
- {Item, or "None"}
````

The horizontal rule separates the human-scannable top from the agent instructions. The whole block is wrapped in a markdown code fence so it pastes cleanly.

## Sources to pull from

- This session's chat: deferred decisions and in-flight items.
- The handoff note from last session, if one is still relevant.
- `docs/plans/` filtered to plans marked IN_PROGRESS.
- Whatever standing to-do or issues surface your project keeps.

Missing or unreadable sources: skip, continue, and add a one-line `Skipped sources: [list]` footnote.

## Sorting items into sections

- Deferred markers from the conversation go to needs-the-human.
- Plans marked PROPOSED go to needs-the-human (they await review); plans marked IN_PROGRESS are agent-doable.
- Lint warnings, drift findings, doc updates: agent-doable.
- Design questions, product tuning, anything taste-shaped: needs-the-human.
- When in doubt, flag as needs-the-human.

Cap the agent-doable list at the top 5 by relevance and say where the rest live.

## Empty case

If nothing's left over and nothing qualifies, output exactly: `Nothing to hand off this time. Self-contained session.`

## Has an opinion

The recommended focus picks ONE thing and justifies it in a sentence. Don't offer a menu.

## Repository boundary

After resolving in-scope pull requests, handoff modifies no product or documentation files. It produces the block and stops. The Git and GitHub state changes described above are the only writes this command authorizes.

## Rationale (recorded so future edits don't drift it)

The two-half shape exists because the note serves two readers with opposite needs: the human skims the top in ten seconds to remember where things stand, and the next session's agent executes the bottom verbatim. Mixing the two produces a note neither reader trusts. The pull request step belongs before the note because handing off a ready or obsolete pull request just makes the next session repeat the end of this one. The explicit STOP instruction in the agent half is load-bearing: without it, next session's agent tends to run the whole chain uninvited, and the human loses the checkpoints the process exists for.