/handoff

description: "Generate a passoff package so the next reader can pick up cleanly — future-you in a new session (typically when context is high) or a coworker. Default + `auto` modes emit a paste-ready next-session opener plus PROGRESS / CLAUDE / memory updates, commit, and /extract; `brief` emits an 80-150 word coworker brief (no file writes); `snap` runs like auto but archives the transcript via /snapshot instead of running /extract — use when context is high; `resume` lists stored next-session prompts with freshness so you can pick. Use when handing off, not when closing out a finished session with nothing pending. Triggers: '/handoff', '/handoff auto', '/handoff brief', '/handoff snap', '/handoff resume', 'hand it off', 'handoff and extract', 'context is full, restart this', 'pass off to next session', 'brief a coworker on this', 'wrap and prompt', 'resume the handoff', 'which handoffs are pending'. (Code port — ADR-094.)"

/handoff — Express Session Handoff

Generate a passoff package so the next reader can pick up cleanly. Two audiences:

• **Next-session handoff** (default + `auto`) — For future-you in a new session (typically when context is high and you need to restart). Synthesizes the session, applies PROGRESS.md / CLAUDE.md / memory updates, commits, runs `/extract`, and emits a **paste-ready next-session opener as the headline artifact**.
• **Coworker brief** (`brief`) — For another person. Produces a copy/paste prose block (Slack/email-ready) summarizing the session. Does NOT update PROGRESS/CLAUDE/memory, does NOT commit, does NOT run /extract. Output-only — paste it and you're done.

For "I'm done, close it out cleanly" with no passoff intent, use `/wrapup` instead.

**Four modes:**

• **Default (`/handoff`)** — Generate ALL drafts (session summary, PROGRESS entry, CLAUDE.md edits, memory updates, commit message, next-session prompt) into one scroll, ask once for combined-go, then apply atomically. Per-item edits allowed.
• **`auto` (`/handoff auto`)** — Implicit-yes on all gates. Run silently. Apply all drafts without confirmation. Emit final report only. Use when the session is short and unambiguous.
• **`brief` (`/handoff brief`)** — Generate a coworker-facing prose brief (80-150 words, copy/paste-ready). Skips PROGRESS/CLAUDE/memory/commit/extract entirely. Emits the brief as the only artifact.
• **`snap` (`/handoff snap`)** — Like `auto` (silent, apply all drafts, emit the next-session opener), but archives the raw transcript via `/snapshot` for later extraction **instead of** running `/extract` now. Use when context is high: you still get the full handoff package + opener + commit, but defer the expensive, compaction-risky knowledge synthesis to a later session (or the next `/audit knowledge` digest pass, which reads the snapshot automatically).

**The next-session opener is the headline artifact** in default + auto + snap modes — always produced, even when no other surface changed. That is what distinguishes `/handoff` from `/wrapup`. Brief mode is a different shape — handoff to a person, not to a session.

**`snap` is `auto` plus one swap.** snap follows auto's behavior exactly (silent, implicit-yes, apply all drafts, emit the opener) — wherever a step below applies to `auto`, it applies identically to `snap`. The single difference is the capture step (Step 6): `snap` runs `/snapshot` (archive the transcript for later) while `auto` runs `/extract` (synthesize now). Nothing else differs. (snap is NOT brief — it produces the full next-session package, not a coworker prose block.)

Step 0: Resolve Config and Parse Mode

Read `~/.gemini/antigravity/aria-knowledge.local.md` and extract `knowledge_folder`. If missing, stop: "aria-knowledge is not configured. Run /setup to get started."

Parse the argument:

• No arg, or arg is empty → `mode = combined-go` (default)
• Arg matches `auto` (case-insensitive) → `mode = auto`
• Arg matches `brief` (case-insensitive) → `mode = brief`
• Arg matches `snap` (case-insensitive) → `mode = snap`
• Arg matches `resume` (case-insensitive) → `mode = resume`
• Any other arg → stop: "Unknown argument '{arg}'. Use '/handoff', '/handoff auto', '/handoff brief', '/handoff snap', or '/handoff resume'."

Use `{knowledge_folder}` as the base path for all file operations.

Step 0r: `resume` mode — pick up a stored prompt (runs INSTEAD of Steps 1-8)

⛔ **If `mode = resume`, run this section and STOP.** It is a READ flow: it writes nothing except the consumed mark on the entry you actually pick. None of the handoff write steps run.

**1 — build the candidate set.** Source `bin/lib-session-state.sh` and call `kt_ss_ledger_candidates "{project_root}"`. It emits `<sid>|<at>|<status>|<source>`, one per line, covering the active `## Next session prompt` **and** every unconsumed entry under `## Pending handoffs` or the legacy `## Prior sessions` — **one candidate set**, which is what makes a pending entry visible when there is no active prompt beside it. ⛔ Do NOT re-implement this parse inline: it absorbs four format axes (two headings, a terminator that may be absent, two prompt serializations, several status forms) and a hand-rolled version silently drops candidates. ⛔ Archived sections are deliberately excluded.

**2 — zero candidates.** Say so plainly and stop. ⚠ This is **not** an error — a clean project with nothing pending is the normal state.

**3 — one candidate.** State its `focus` and its age, confirm, then resume it.

**4 — two or more.** Render a numbered list, newest first — **ONE LINE PER CANDIDATE**:

 1. ·  1d  DEV-1089 PHASE 2 is deployed, verified and closed (served f92839b, LOG-142); /preflight…
 2. ·  2d  DEV-1130 T4 + T7 SHIPPED, PUSHED and DEPLOYED to staging (backend a217670, frontend ma…
 3. S  7d  Currency arc. DEV-1659 SHIPPED + DEPLOYED + VERIFIED LIVE. DEV-1662 specced, gated twi…

`<n>. <freshness: · fresh / S stale> <age> <focus, clipped to ~88 chars with an ellipsis>`.

⛔ **`next:` is NOT in the list.