| name | nexus-session-handoff-legacy |
| description | Deprecated legacy alias retained for audit and rollback. Use pidev-specialised/session-handoff, which owns the canonical continuity capsule and live-state reconciliation contract. |
| argument-hint | [optional: ticket, branch, PR, feature, repo area, or handoff scope] |
| allowed-tools | Read, Grep, Glob, LS, Bash, Write |
/session-handoff — Durable Session Handoff
Deprecated: Do not invoke this alias for new work. Use pidev-specialised/session-handoff. This file is retained temporarily so earlier reports and rollback evidence remain inspectable without colliding with the canonical skill name.
The "1" of the handoff combo: gate the tree green, then write a durable handoff that
/resume-from-handoff (the "2") verifies against and continues from. Run before stopping,
switching terminals, opening a PR, or handing to another agent.
Boundary. This command runs LOCAL verification gates and writes the handoff report +
log. It must NOT commit, push, deploy, run migrations, modify tickets, rotate secrets, or
touch production — surface those for the user to do after the handoff.
Phase 0 — Gate the tree green (run FIRST, every time)
Before writing anything, run the definition-of-done gates:
scripts/handoff-loop.sh
It cleans cache/build bloat, then runs deps → generated-files-current → type → lint →
tests → production build → audits, writing a timestamped healthcheck log to
.handoff-logs/handoff-<ts>.log and printing that path on its last line. A gate whose
toolchain is absent is SKIPPED with a reason, not failed.
- Exit 0 (READY) → proceed to write the handoff; cite the log path + pass/skip counts in
§5 Running state and §6 Verification.
- Non-zero (BLOCKED) → do NOT declare the repo ready. Name the failing gate(s) from the
log, stop forward progress, and either fix the gate and re-run, or write a BLOCKED
handoff whose §8 first command is the fix + re-run. Never claim green without exit 0.
If scripts/handoff-loop.sh is absent (another repo), run that repo's detected equivalents
(type-check, lint, test, build, audit) and record the real results the same way.
Phase 0.5 — Definition of Done & ship classification (run before writing the report)
Phase 0 proves the tree is green. Phase 0.5 proves the session is finished — a green tree
can still hide half-done, uncommitted, or never-shipped work. A handoff must never let an
unfinished session masquerade as a clean stop. Classify the session into exactly one state
and record it in §1 of the report:
- SHIPPED — the change is committed, pushed, and a PR is open or merged, on a green tip.
Record the PR URL + merge state in §3. This is the only "fully closed" outcome.
- READY-TO-SHIP — work is complete and green but no PR exists yet. Do not silently stop.
Run the
merge-gate pre-open checklist (below), then make §8's First command to run the
exact gh pr create (or gh pr ready) command. session-handoff does not open it — opening
a PR here ≈ merging it (see merge-gate), so that stays an explicit user/next-agent action.
- WIP / BLOCKED — a task is unfinished, a gate is red, or the surface isn't demonstrable.
Mark the handoff INCOMPLETE; §7 lists exactly what remains to finish + test before it can
ship, and §8's first command is the finish-then-ship path — never a bare "resume".
Definition-of-Done checklist (evaluate honestly; a "no" forbids the SHIPPED state)
Make a todo per item. Every item is answered from a this-session tool result, not memory:
- Tasks closed — every task/goal the session set out to do is done, or explicitly moved to
§7 Deferred with an owner. No silent partials. (Check the task list / stated goal.)
- Tested for real — Phase 0 exited 0 with tests actually executed (not just types
compiling); paste the log path. A skipped test suite is a "no" unless the toolchain is
genuinely absent, and then it's named as a gap in §9.
- Tree whole —
git status clean and git stash list empty; nothing staged, stashed, or
uncommitted belongs in the change. (Pulls the merge-gate "Whole" check to the handoff.)
- Shipped or ready — the work is on a branch and either PR'd (SHIPPED) or carries the exact
ready-to-open command (READY-TO-SHIP). "Local/session-only" is only acceptable for a
deliberately-declared WIP handoff, stated as such in §1 and §3.
- Surface demonstrable (RA-1109) — any user-visible change produces a visible outcome, not
just HTTP 200 / green CI. If you can't point to the user-facing result, it isn't done.
merge-gate pre-open checklist (only for READY-TO-SHIP, before handing off the gh pr create)
Because auto-merge in this estate treats an opened PR as an authorised merge, the ship command
handed off in §8 is only safe when all of merge-gate's Iron-Law conditions already hold —
Whole · Green-on-the-pushed-tip · Dark-by-default · Atomic · Standards-clean · Authority
reconciled. If any is false, the session is WIP, not READY-TO-SHIP: say so and put the fix in
§8. Invoke the merge-gate skill for the full gate; do not paraphrase it here.
Input scope
User supplied handoff scope:
$ARGUMENTS
If $ARGUMENTS is empty, infer the scope from:
- Current branch
- Git status
- Recent commits
- Current diff
- Recently changed files
- Current conversation context
- Repo guidance in CLAUDE.md
- Agent boundaries in AGENTS.md
- Relevant
.harness/, skills/, scripts/, tests/, app/, dashboard/, or mcp/ state
Read-only inspection checklist
Inspect what is available without modifying anything:
git branch --show-current
git status --short
git log --oneline -n 8
git diff --stat
git diff --name-only
If safe and useful, also inspect:
git diff
Only run tests if the user specifically asks for verification execution. Otherwise, report the verification commands to run.
Required output
Write the handoff to docs/session-handoffs/handoff-<YYYYMMDD-HHMMSS>.md (create the
directory if absent) AND print it to the user — durable on disk is what lets
/resume-from-handoff find it. Follow the 10-section structure in the shared template
references/report-template.md:
- Summary — attempted / completed / partial / not touched, and the Phase 0.5 state
(SHIPPED / READY-TO-SHIP / WIP-BLOCKED) with the Definition-of-Done result in one line
- Where it started — request, branch, files, problem, constraints (
Unknown from available context if unclear)
- Decisions locked + what shipped — separate the two; if nothing committed/pushed, say
Nothing shipped yet. Current work is local/session-only.
- Key files — table; Status ∈ Created / Modified / Deleted / Read-only inspected / Needs review / Deferred / Unknown
- Running state — branch, tree, server/process (never claim running unless verified), open PR, blockers, safe-to-stop
- Verification — exact commands (backend / dashboard / smoke); cite the Phase 0 log path
- Deferred + open questions — two lists, each item with Owner / Blocking / Why
- Pick up here —
Start here steps · Do not redo · explicit First command to run
- Risk notes — unverified assumptions, failed commands, stale context, secrets/env gaps
- Handoff quality check — no faked verification, no hidden "still running", completed-vs-deferred clear
If Phase 0 was BLOCKED, mark the handoff BLOCKED and make §8's first command the gate fix.
End with: Handoff complete. Next safe action: <one sentence>.
The 1-2 combo
/session-handoff (this, the "1") and /resume-from-handoff (the "2") are a pair:
gate-and-write here → verify-and-continue there. The report at
docs/session-handoffs/handoff-<ts>.md and the log at .handoff-logs/handoff-<ts>.log are
the shared contract between them. /resume-from-handoff reads the latest of each and
re-runs scripts/handoff-loop.sh as its own verification gate before resuming — so the tree
is proven green on the way out AND on the way back in.
Companion: merge-gate (the ship boundary)
Phase 0.5 evaluates whether the session is ready to ship; merge-gate owns how the ship
happens safely. session-handoff never opens a PR itself — for a READY-TO-SHIP session it hands
off the exact gh pr create command in §8, gated by merge-gate's Iron Law (opening a PR in
this estate ≈ authorising its merge). Division of labour: session-handoff = the
definition-of-done gate run + the completion classification; merge-gate = the git-merge
boundary and the auto-merge threat around it; ship-chain / ship-it / ship-release = the
idea→ship lifecycle. Invoke merge-gate before running any handed-off ship command.
