handoff

/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 / AGENTS.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.

Three modes:

• Default (/handoff) — Generate ALL drafts (session summary, PROGRESS entry, AGENTS.md / 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.

The next-session opener is the headline artifact in default + auto 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.

Step 0: Resolve Config and Parse Mode

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

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, AGENTS.md, and/or CLAUDE.md (search upward from cwd)
• PROGRESS.md path — if exists
• AGENTS.md path(s) — root + relevant subfolder
• CLAUDE.md path(s) — root + relevant subfolder
• Memory files — any project_*.md files in ~/.claude/projects/ 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 AGENTS.md or 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, AGENTS.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 AGENTS.md / 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: AGENTS.md / CLAUDE.md updates

If AGENTS.md or CLAUDE.md exists: check if anything from this session contradicts, outdates, or is missing from it. Prefer AGENTS.md for Codex-specific instructions; keep CLAUDE.md current when the project also uses Claude Code. If updates are needed, draft the specific edits (show old → new diffs). If nothing needs updating, mark as current — do NOT force updates for the sake of updating.

3c: Memory updates

Check ~/.claude/projects/.../memory/project_*.md files matching the current project path. Compare against the session synthesis. If memory is stale, draft an update (specific old → new lines). If no update needed, mark as current.

3d: Commit message(s)

For each git repository with uncommitted changes: draft a conventional-commit message based on the session synthesis. List specific files to stage (NOT git add -A). Skip repos with no changes.

3e: Next-session opener (the always-on artifact)

Build a fenced block intended for paste into the next session. Format:

{project-marker}
Resume {project-na