handoff

Use this when the lead session has gotten heavy (long-lived, large transcript — see the auto-wake handoff nudge) and the healthy move is a fresh context, not more of this one.

First, write the handoff file — a short packet-file-style summary under ~/.relay-tasks/ (gate-exempt), covering: what's in flight, what's reviewed/committed, open questions, next steps. Write it like a memo to your successor, not a transcript dump. Carry forward every [discipline] marker your own predecessor's doc had (relay warns if one goes missing — see the linter note below), and on every queue item name an EXECUTOR to do it (or write "delegate this") — never phrase box/deploy/ops work as this lead's own to pick up (§10's [ops-not-lead-work] incident: a dropped marker plus ops phrased as the lead's task is exactly how a successor drifted into implementation).

Then run:

${CLAUDE_PLUGIN_ROOT}/bin/relay handoff <path-to-handoff.md>

Call relay as ${CLAUDE_PLUGIN_ROOT}/bin/relay (Claude Code substitutes the plugin's absolute path when this skill loads) — not bare relay, which often isn't on the Bash tool's non-interactive PATH. Unlike other relay commands, handoff reads the caller's session id from $CLAUDE_CODE_SESSION_ID automatically — no need to pass it yourself.

This opens a NEW lead tab, pre-armed (its routing gate and auto-wake are already active from turn one), seeded with a short pointer at a relay-prepared copy of the handoff file — your source md is never modified; relay appends a SUCCESSOR AFTERCARE section to its own copy instead, so the successor's launch prompt stays a one-line pointer (a prior version inlined the aftercare directly into the prompt and it truncated a real launch command — see build_handoff_copy). As its final act, this steps the CURRENT session down — the gate and auto-wake here turn off. Any executors this lead owned are re-parented to the successor here, and each one's already-seen report stamps travel with it, so a report the outgoing lead reviewed and committed doesn't re-wake the successor as new. If any of them are pinned (relay keep / spawn --keep), the handoff output names them — auto-close will never park a pinned executor, so the successor inherits them indefinitely until someone runs relay keep <sid> --off.

Aftercare, for the successor. Once it's settled in (read the handoff, run /relay:list), the successor runs /relay:mode — idempotent if the pre-arm pin held, and it arms for real if Claude Code minted a different session id for the tab. It then asks the user whether to close the predecessor's now-unarmed tab, and on a yes runs relay close-predecessor (never unasked) — the predecessor's tab identity travels in the successor's marker for exactly this.

Optional flags: --project NAME and --model NAME override the successor's project/model (default: inherited from this lead's own marker).

Linter note. relay handoff compares the doc THIS lead itself inherited against the doc it's handing off and warns if any [discipline] marker went missing (dropped_discipline_markers) — silent when nothing was dropped, or when this is the first-ever lead with no inherited doc to compare against.