relay

Files (7)

• SKILL.md
• next-prompt-spec.md · references/
• relay-build-focus.sh · scripts/
• relay-collect.sh · scripts/
• relay-lib.sh · scripts/
• relay-write-baton.sh · scripts/
• relay.bats · tests/

SKILL.md (first lines)

# 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](https://github.com/bats-core/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.

From sangrokjung/claude-forge, MIT.

More from sangrokjung/claude-forge