aria-knowledge

/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
• Any other arg → stop: "Unknown argument '{arg}'. Use '/handoff', '/handoff auto', '/handoff brief', or '/handoff snap'."

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

Step 1: Identify Project Context

Same logic as /wrapup Step 1 — detect:

• Project root — directory containing PROGRESS.md and/or CLAUDE.md (search upward from cwd)
• PROGRESS.md path — if exists
• CLAUDE.md path(s) — root + relevant subfolder
• Memory files — any project_*.md files in ~/.gemini/antigravity/transcripts/ matching the current path
• Git repos — run git status in each git repository within the project to detect uncommitted changes

Additionally, determine the project marker for the next-session opener (Step 9):

• Match the working directory against the project codes documented in the user's root CLAUDE.md (e.g., cs, ss, df, kn, ar, jp if those conventions exist).
• If no SessionStart-hook project-code convention is detected, use the project's folder name as the marker.
• If no project is identifiable, use the literal [no-project] — the opener will still work, just without auto-routing.

If no PROGRESS.md or CLAUDE.md is found, note this — proceed with the steps that apply.

Step 2: Synthesize Session Work (silent)

Build the session synthesis internally — do NOT print it yet:

1. Files changed — list files created/modified/deleted during this session (from conversation context, not git)
2. Key decisions — architectural choices, approach selections
3. Current state — what's working, in-progress, blocked
4. Next steps — what the user indicated should happen next, or what logically follows
5. Open threads — anything explicitly deferred or flagged for later

This synthesis feeds every subsequent step.

Mode branch: If mode = brief, jump to Step 2B (Brief Output) and stop there. Skip Steps 3-8 entirely. Otherwise continue to Step 3.

Step 2B: Brief Output (brief mode only)

Skip this step entirely if mode != brief.

Brief mode produces a single copy/paste artifact — a coworker-facing prose brief. No PROGRESS update, no CLAUDE.md edit, no memory write, no commit, no /extract call. Just the prose, formatted for paste into Slack / email / chat.

2B.1: Build the brief from Step 2 synthesis

Compose an 80-150 word prose block following this template (cap at 200 words). Fill placeholders from the Step 2 synthesis; if a section has no relevant content for this session, omit the section line entirely (don't leave empty bullets).

Hey [coworker] —

Quick brief on {topic from synthesis} from {YYYY-MM-DD}:

**What happened:** {2-3 sentence summary drawn from synthesis "Current state" + "Files changed"}

**Key decisions:**
- {decision 1 from synthesis "Key decisions"}
- {decision 2}
- {decision 3 if relevant — cap at 4 bullets}

**What's next:** {1-2 sentences from synthesis "Next steps" + "Open threads"}

**Where to pick up:** {file path, PR link, ticket ref, or doc link — omit this whole line if N/A}

Let me know if you want me to walk through any of this.

Notes for filling the template:

• Keep [coworker] as a literal placeholder — user fills the name at paste time. Don't prompt for a name.
• Tone: warm-but-professional default. Write as if briefing a peer who shares context but wasn't in the room. Avoid corporate hedging and avoid forced casualness.
• "What happened" is the heaviest section — get the 2-3 sentence summary right. If the session was short or unclear, say so plainly rather than padding.
• "Key decisions" should be the genuinely-decided things, not options-still-on-the-table. 0 decisions is fine — if so, omit the section entirely.
• "Where to pick up" only appears if there's a concrete artifact reference (file, PR, ticket, doc URL). Otherwise omit the line.
• Stay under 200 words. Above that, the format breaks down and reads as a memo, not a brief.

2B.2: Emit the brief

Emit the brief inside a code fence so it copies cleanly. Format:

## Coworker Brief — {YYYY-MM-DD}

Paste this directly into Slack / email / chat:

{full brief from 2B.1}

That's it — no further handoff steps run in brief mode. If you also want to update PROGRESS.md, memory, or run /extract, invoke `/handoff` (default) or `/handoff auto` separately.

Exit after emission. Do not run any subsequent steps.

Step 3: Draft All Updates (silent)

In parallel, draft every artifact this handoff might write. Do NOT apply anything yet.

3a: PROGRESS.md entry

If PROGRESS.md exists: draft a new session entry matching the existing format (heading style, date format, structure). If today's entry already exists, draft an append-to-existing delta instead of a duplicate entry.

3b: CLAUDE.md updates

If CLAUDE.md exists: check if anything from this session contradicts, outdates, or is missing from it. If updates are needed, dr