relay — session relay (compact + next-task baton)

Think of a relay race: the runner hands off the baton before stopping. Before context fills up, this skill produces two things: ① a one-line /compact command that compresses everything so far, and ② a handoff document (a "baton") that lets the next session start running immediately on the next task.

When: context is 70%+ used, work is about to be interrupted, or the user asks to "relay / hand off / next session / baton / handoff."

Important (invariant): this skill never runs /compact directly (a skill cannot execute /compact). It only produces the one-liner the user pastes in.

Let $SKILL be the absolute path of the directory containing this SKILL.md. Scripts live in $SKILL/scripts/.

Flow

0) Parse arguments

From $ARGUMENTS:

• First positional argument = next task (NEXT_TASK).
• Flags: --new-session (for a brand-new session — instructs the user to paste the whole baton), --no-ask (skip the clarifying question), --quick (skip prose, skeleton only), --copy (opt-in clipboard copy — off by default, see §6).

1) Collect state

Run bash "$SKILL/scripts/relay-collect.sh" → capture one JSON object. (facts about git/plan/session-summary/tasks/artifacts) This JSON is the source of truth for every "fact." Do not retype it from memory — quote it verbatim.

2) Confirm the next task

If NEXT_TASK is empty and --no-ask was not passed, ask one AskUserQuestion: "What's the first thing to do next?" — options pulled from plan.next_unchecked / session_summary.next_steps / tasks.items in the collect JSON, plus "type it myself." Tag the answer [from-user].

3) Write the /compact one-liner

bash "$SKILL/scripts/relay-build-focus.sh" "<NEXT_TASK>" "<files>" "<decision>"

• <files> = key files relevant to the next task (space/comma separated, optional).
• <decision> = one line capturing a key decision to preserve (optional).

4) Write the skeleton baton immediately (guarantees an artifact even at 95% context)

bash "$SKILL/scripts/relay-write-baton.sh" "<NEXT_TASK>" <path-to-collect.json or -> "<focus line>"

• Save the collect JSON to a file and pass its path, or pipe it via stdin with -.
• This step leaves a valid (skeleton) baton on disk even without prose.

5) Add prose (optional — skip if --quick)

Follow references/next-prompt-spec.md to write §2 (context needed) and §4 (repro pitfalls), plus §1's body.

• Apply the relevance filter (KEEP / one-line / DROP) based on the next task.
• Facts come verbatim from the collect JSON; inferences get tagged [from-claude].
• Save the prose to a temporary markdown file (use the ---§4--- marker to separate §2/§4), then re-run write-baton with the prose file as the 4th argument to splice it in.
• Copy/prose text should read like a relaxed expert, not a stiff, over-formal tone.

6) Output (three items — (c) must always be a code block)

(a) absolute path of the baton (b) preview of the next prompt — excerpt from §1 MISSION (c) the /compact one-liner, output as a single fenced code block, verbatim

Never write (c) inline. A long inline line wraps in the terminal and becomes hard to select and copy. A code block keeps it as one selectable unit.

• Do not put it on the clipboard by default. The clipboard is a single, volatile slot — if the user copies anything else in the meantime, the line is gone, and whatever was on the clipboard before gets silently overwritten without consent. On-screen text stays in scrollback and can be copied again anytime.
• If clipboard is actually needed, opt in explicitly with --copy, which sets RELAY_COPY=1 on the write-baton call in step 4. Even then, still emit the (c) code block.
• With --new-session, instead of (c), tell the user to paste the entire baton into the new session (path from (a)).

CRITICAL guards

• Skeleton first, prose later: if context runs out at step 4, a valid baton still remains.
• MISSION-first: oriented toward "what to do next," not a "log of what was done." §1 comes first.
• Facts stay verbatim: pulled directly from the collect JSON. Never retype from memory.
• Never runs /compact directly — the skill only produces the one-liner.
• Always emit absolute paths (no relative paths, no unexpanded ~).
• Can finish with just the skeleton if context is running low.

Opt-in auto-restore (SessionStart:compact)

hooks/post-compact-restore.sh is wired to settings.json's SessionStart (matcher "compact"). Right after /compact, this hook injects the pointer (the carryover left by write-baton) into the session exactly once (consume-once).

• When auto-restore fires, the next task, carryover, and baton path reappear in context right after compaction.
• If the hook doesn't fire (no pointer / expired / already consumed), it degrades gracefully to the (a) baton path above — just Read that path.

References

• Baton 7-section template + relevance filter + prose format: references/next-prompt-spec.md (SSOT)
• Scripts: scripts/relay-lib.sh, relay-collect.sh, relay-build-focus.sh, relay-write-baton.sh
• Auto-restore hook: hooks/post-compact-restore.sh

Dev dependency (optional)

tests/relay.bats uses bats-core. It is not required to use the skill — only to run the test suite locally (bats tests/relay.bats from skills/relay/). If bats isn't installed, the scripts still work standalone; just skip the test run.