/forward

name: forward
description: Hand off the current session to the next one. Use when user says "forward", "handoff", "wrap up", or before ending a session.
argument-hint: "[--bg | asap | --only]"

/forward - Handoff to Next Session

Create context for next session, then enter plan mode to define next steps.

Usage

/forward              # Create handoff, show plan, wait for approval
/forward --bg         # Hand the whole handoff to a background Haiku — returns instantly
/forward asap         # Create handoff + commit immediately (no approval needed)
/forward --only       # Create handoff only, skip plan mode

---

/forward --bg

**Fire-and-forget.** A background Haiku subagent mines the session JSONL and writes the handoff file. Returns immediately — no plan mode, no blocking. Use it to snapshot progress mid-session, or at the end when you'd rather keep moving. For the full interactive flow with plan approval, use plain `/forward`.

Haiku is the right tier here: this is bullet extraction from structured JSONL, not writing. (Its sibling `/rrr --bg` uses Sonnet — a retro's diary and lessons *are* writing.)

Resolve first, then spawn

ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
ENCODED_PWD=$(echo "$ORACLE_ROOT" | sed 's|^/|-|; s|[/.]|-|g')
PROJECT_DIR="$HOME/.claude/projects/${ENCODED_PWD}"
LATEST_JSONL=$(ls -t "$PROJECT_DIR"/*.jsonl 2>/dev/null | head -1)
SESSION_ID=$(basename "$LATEST_JSONL" .jsonl | cut -c1-8)
PSI=$(readlink -f "$ORACLE_ROOT/ψ" 2>/dev/null || echo "$ORACLE_ROOT/ψ")
REPO_NAME=$(basename "$ORACLE_ROOT")
DATE_SLUG=$(date +%Y-%m-%d_%H-%M)

Substitute every `<PLACEHOLDER>` with the real value before spawning — the subagent cannot see your shell. Check whether the handoff directory exists; if not, tell the subagent to `mkdir -p` it.

Spawn ONE background Agent (`model: "haiku"`, `run_in_background: true`)

You are a session archivist. Write a handoff file for the current session.

JSONL path: <LATEST_JSONL>
Vault path (PSI): <PSI>
Session ID: <SESSION_ID>
Repo: <REPO_NAME>
Date: <YYYY-MM-DD HH:MM>

Steps:
1. Run: python3 "$(ls ~/.claude/skills/forward/scripts/dig-session.py \
             ~/.claude/plugins/marketplaces/*/skills/forward/scripts/dig-session.py \
             ~/.claude/plugins/cache/*/*/*/skills/forward/scripts/dig-session.py \
             ~/.claude/skills/forward/dig-session.py 2>/dev/null | head -1)" "<LATEST_JSONL>"
2. From the JSON output, write 4-8 bullets summarizing what happened. Be specific:
   skills invoked, teammates used, files changed, key outputs.
3. Run: git -C <ORACLE_ROOT> status --short
4. Write the handoff to: <PSI>/inbox/handoff/<DATE_SLUG>_bg-forward.md

Format:

# Handoff: [session focus from the JSONL]

**Date**: <YYYY-MM-DD HH:MM>
**Source**: /forward --bg (JSONL-mined, not memory)
📡 Session: <SESSION_ID> | <REPO_NAME>

## What We Did
<bullets from the JSONL analysis>

## Uncommitted Files
<from git status --short, or "none">

## Pending
<infer from the session: what was in progress? what was mentioned but not done?>

## Next Session
<1-3 specific actions based on where the session ended>

After writing, print: "📤 Handoff written: <absolute_path>"
Do NOT enter plan mode. Do NOT commit anything.

After spawning

Tell the user where it will land, then **keep working — don't wait**:

📤 /forward --bg launched — handoff writing in background.
   Session: <SESSION_ID>
   Will write to: <PSI>/inbox/handoff/<DATE_SLUG>_bg-forward.md

Sibling: `/rrr --bg` (retrospective). Run both at session end — `/rrr --bg` looks back, `/forward --bg` looks forward.

Steps

1. **Git status**: Check uncommitted work 2. **Detect session**: Current session ID for traceability 3. **Session summary**: What we did (from memory) 4. **Pending items**: What's left 5. **Next steps**: Specific actions

Session Detection

ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
ENCODED_PWD=$(echo "$ORACLE_ROOT" | sed 's|^/|-|; s|[/.]|-|g')
PROJECT_DIR="$HOME/.claude/projects/${ENCODED_PWD}"
LATEST_JSONL=$(ls -t "$PROJECT_DIR"/*.jsonl 2>/dev/null | head -1)
if [ -n "$LATEST_JSONL" ]; then
  SESSION_ID=$(basename "$LATEST_JSONL" .jsonl)
  echo "SESSION: ${SESSION_ID:0:8}"
fi

Include in handoff header if detected:

📡 Session: 74c32f34 | repo-name | Xh XXm

Skip silently if detection fails.

Output

Resolve vault path first:

ORACLE_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -n "$ORACLE_ROOT" ] && [ -f "$ORACLE_ROOT/CLAUDE.md" ] && { [ -d "$ORACLE_ROOT/ψ" ] || [ -L "$ORACLE_ROOT/ψ" ]; }; then
  PSI=$(readlink -f "$ORACLE_ROOT/ψ" 2>/dev/null || echo "$ORACLE_ROOT/ψ")
else
  PSI=$(readlink -f ψ 2>/dev/null || echo "ψ")
fi

Write to: `$PSI/inbox/handoff/YYYY-MM-DD_HH-MM_slug.md`

**IMPORTANT**: Always use the resolved `$PSI` path, never the `ψ/` symlink directly. This ensures handoffs go to the project's vault (wherever ψ points). Do NOT `git add` vault files — they are shared state, not committed to repos.

# Handoff: [Session Focus]

**Date**: YYYY-MM-DD HH:MM
**Context**: [%]

## What We Did
- [Accomplishment 1]
- [Accomplishment 2]

## Pending
- [ ] Item 1
- [ ] Item 2

## Next Session
- [ ] Specific action 1
- [ ] Specific action 2

## Key Files
- [Important file 1]
- [Important file 2]

Confirm handoff write (announce-mode — absolute paths required)

announce-mode → absolute path (no ψ/, no ~/, no $VAR, no ...).

Use: echo "marker: $RESOLVED_PATH" — bash substitutes. See CONVENTIONS.md.

HANDOFF_FILE="$PSI/inbox/handoff/$(date +%Y-%m-%d_%H-%M)_${SLUG}.md"
echo "📤 Handoff: $HANDOFF_FILE"

Then: Create Issues from Pending Items

After writing the handoff file, extract actionable items and offer to create GitHub issues.

Step 1: Extract Items

From the handoff you just wrote, collect all `- [ ]` items from **Pending** and **Next Session** sections.

Step 2: Filter Actionable Item