Handover

You are winding this session down so a FUTURE session (not you) can continue seamlessly. The reader of everything you produce has none of your context. Honest verdicts throughout: verified means observed; anything unverified is labeled unverified, never rounded up to done.

Phase 0: Inventory (read-first, before touching anything)

Gather the full picture; write it to .claude/scratch/handover-inventory.md:

1. git status --short, current branch, git stash list.
2. git worktree list --porcelain -- classify each: MERGED-CLEAN / DIRTY /

UNMERGED-BRANCH / HELD-BY-CLAIM / not-yours.

1. Open PRs you authored: gh pr list --author @me (+ check states).
2. Active claims: /claim --list (or git ls-remote origin "refs/claims/*").
3. Running example-app converges (example-app status if on PATH) and background tasks.
4. The plan (docs/plan.md / docs/plans/), roadmap, and this session's

checkpoint file if one exists.

Phase 1: Finish or park (no half-measures)

• A task within ~10 minutes of a verifiable finish: FINISH it (through its

normal gates), don't hand it over.

• Everything else is PARKED: stop at a coherent boundary (compiling, tests

in a known state -- note which), never mid-edit.

• Running example-app converges are NOT killed: note goal_id, workspace, and how to

read the terminal result (example-app status) in the notes. A converge that finishes after you leave still lands its branch.

Phase 2: PR sweep (the no-stranded-PRs rule, applied at exit)

For each open PR you authored:

• GREEN + you are cleared to merge: merge (rebase), confirm, clean up its

worktree/branch.

• GREEN + a lead owns the gate: post the review request; add an In flight

roadmap line naming who it waits on.

• RED: fix if inside the finish budget; else document exactly what is red

(failing check, link, suspected cause) in the notes + a Blocked roadmap line. A red PR handed over with no diagnosis is a stranded PR.

• Pass --no-merge to force review-request mode for everything.

Phase 3: WIP to the remote handover branch

Nothing valuable may exist only on this machine or only in your context.

1. On the main checkout: commit WIP as wip(handover): --

(small scoped commits; never git add -A across unrelated changes; NEVER commit secrets/credentials -- scan first).

1. Push to the handover branch: git push -u origin HEAD:handover (override

name with --branch). If the remote branch exists and is not an ancestor (another session's handover), DO NOT force-push: use handover-- and record the divergence in the notes.

1. Harvest DIRTY or UNMERGED worktrees that are yours: commit their WIP on

their own branches and push those branches; list each in the notes with its state. Do not merge them into handover -- a pickup session decides.

1. Delete every stale worktree whose changes are now safe on the remote:

fully-merged worktrees, AND harvested worktrees once you have VERIFIED their branch is on origin (git ls-remote origin shows the pushed SHA). The branch preserves the work; the worktree is dead weight on a shared disk. Preconditions for each deletion: pushed-and-verified, claim-free, yours, no live process inside (a running example-app converge keeps its worktree), and your cwd is outside it.

Phase 4: Handover notes (the contract with the next session)

Write docs/handover.md on the handover branch (commit + push it):

# Handover -- , session 
## TL;DR (3 lines max: what this session was doing, where it stopped, the single next action)
## Done & VERIFIED (observed evidence per line: PR#, live check, test run)
## Done but UNVERIFIED (what still needs observing, and how)
## In flight (per item: branch/worktree, exact state, next action, gotchas)
## Blocked (per item: what unblocks it, who owns that)
## Running processes left alive (example-app goal_ids, background tasks, how to read their results)
## Landmines & context (non-obvious things that will bite: env, flaky suites, half-migrations)
## How to resume (ordered: fetch; checkout handover; read this + roadmap + plan;
   claim lanes via /claim; where the checkpoint file is)

Then /checkpoint save, and persist non-obvious findings where they belong: invariants -> docs/lore.md, session narrative -> docs/devlog.md.

Phase 5: Fleet bookkeeping

• Release every claim you hold (/claim --release) -- a held claim from

a dead session parks its lane until TTL.

• Roadmap (docs/roadmap.md): move your items -- Shipped stays, In progress

-> In flight/Blocked/Planned each pointing at docs/handover.md. Mirror the lane state to the Engineering Portfolio Notion row (global rule).

• Board + bus: post one handover record to

~/.claude/bus//coordination.md (branch name, notes path, lanes released) and announce on the bus. This is your final liveness trace.

Phase 6: Verify, then report

Confirm before claiming done: git status clean (or leftovers listed in the notes with reasons); handover branch + notes visible on the remote (git ls-remote); zero claims held; zero unswept authored PRs. Report: branch pushed, notes path, PRs merged/handed off, claims released, worktrees harvested/deleted, processes left running -- and anything you could NOT verify, stated plainly.

Does NOT do

• Mid-task pause/resume within the SAME session -- that is /checkpoint.
• Merging red PRs, force-pushing, or deleting unmerged/others' work -- never.
• Killing example-app converges or other sessions' processes.
• Post-session cleanup of a repo you are not handing over -- that is /tidy.

Concurrency

Assume sibling sessions are alive and grinding (liveness-is-evidence rule in team/SKILL.md): never touch their worktrees, claims, or WIP; on any shared file (roadmap, board) pull --rebase --autostash before writing. The handover branch divergence rule above exists because two sessions can hand over simultaneously.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.