Handoff

---
name: handoff
description: Generate a concise session handoff for resuming work later, including current state, decisions, open issues, and next steps.
---

# Handoff

Use when the user asks for a handoff, context note, session summary, or resume
brief.

## Workflow

1. Inspect the current repo state with `git status --short`.
2. Review relevant recent commits or diffs if needed.
3. Summarize only durable context that would help the next session.
4. Queue USER ACTION items to `~/.claude/operator-queue.md` — see
   "Operator-action queue" below for the block format and rules.
5. Session-end hygiene (before saving the note):
   - `git worktree list` — record every task worktree as removed, or retained
     with its owner, reason, PR, and concrete follow-up command. Follow the
     shared lifecycle procedure in `claude/scripts/README.md`. Stop owned
     processes first and archive recovery/review evidence. Remove explicitly
     released worktrees only after verified integration and applicable user or
     standing cleanup authorization. Preserve active/locked worktrees, unique
     work, dirty/untracked/ignored content, stashes and unknown ownership.
     Pending PRs retain their worktrees; release the exact completed artifact
     when appropriate so a later session can assess it after merge.
   - Inventory local branches fully merged into the default branch
     (`git branch --merged "$(git rev-parse --abbrev-ref origin/HEAD)"` —
     don't assume it's named `main`). Delete them only when the user or an
     applicable standing order explicitly authorizes branch deletion.
   - Push or PR every branch that has work on it — never leave work
     stranded local-only.
   - `gh pr list` — note each open PR's review + CI state in the
     handoff's "Open issues" section.
6. Save the note to `~/.claude/handoffs/YYYY-MM-DD-<project>-handoff.md` —
   the same directory the Claude `/handoff` skill uses, so either tool can
   resume the other's session. Create the directory if needed. Never save it
   inside the public repo.

## Output

Use the same section names as the Claude `/handoff` skill so notes are
interchangeable across tools:

```markdown
## Handoff — YYYY-MM-DD

### What we did
- ...

### Where we left off
- ...

### Key decisions made
- ...

### Open issues
- ...

### Next steps
- ...

### Context for next session
- ...

### Session continuity
- (optional) Resumable agent sessions: my Codex session id (`codex resume <id>`),
  or an agy conversation id (`agy --conversation <id>`). Omit if none.
```

Keep it concise. Do not include secrets, private project details, tokens, or
machine-specific paths unless the user explicitly asks and the destination is
private.

### Operator-action queue

Anything only the operator can do (rotate a token, click an approval, decide
on a purchase) goes to the durable queue at `~/.claude/operator-queue.md` —
handoff prose gets buried by the next handoff; the queue does not. One item
per block:

```markdown
## <stable-slug>
- added: YYYY-MM-DD
- project: <source project>
- deadline: YYYY-MM-DD
- verified: YYYY-MM-DD
- action: <one line: what the operator must do>
```

The slug is stable (same action = same slug across sessions); `deadline` and
`verified` are optional — omit the line if none. **Append only if absent** —
match on the slug, never re-add or duplicate an existing item. **Remove an
item's block only when the action is actually done**, not when it's merely
mentioned again.

`verified` records the last time the item was checked against live state
(the PR, the env var, the dashboard — not the previous handoff). **When a
session touches an item's subject, re-check it against live state and
set/bump `verified`; remove the block only when done.** The SessionStart
reminder treats the newest of `verified`/`added` as the item's freshness and
marks anything older than 30 days `[stale — re-verify]`, so an unbumped item
announces its own rot instead of being repeated as fact.