tmsjngx0/session-handoff

Handoff

Generate a continuation prompt so the next Claude session picks up exactly where this one left off.

Step 1: Gather Context

1a: Git State

git branch --show-current
git log --oneline -5
git status --short

1b: Active Beads Work

br list --status=in_progress --json 2>/dev/null

1c: Tech Stack

ls package.json Cargo.toml go.mod pyproject.toml setup.py Gemfile *.csproj 2>/dev/null | head -5

1d: Conversation Analysis

Scan the current conversation for:

• Decisions made — architecture choices, approach selections, rejected alternatives
• Problems solved — bugs fixed, issues resolved, workarounds applied
• Problems remaining — blockers, open questions, known issues
• Files modified — what was changed and why
• Key discoveries — non-obvious things learned about the codebase

Step 2: Build Handoff Prompt

Compose using this template:

## Context

Project: [project name]
Branch: [current branch]
Tech: [detected stack]
Task: [in-progress beads issue ID + title, or "none"]

## Where We Left Off

[2-3 sentences: what was being worked on, current state]

## Decisions Made

- [decision]: [rationale]
- [decision]: [rationale]

## Key Files

- `[path]` — [what was done / why it matters]
- `[path]` — [what was done / why it matters]

## Next Steps

1. [immediate next action — specific and actionable]
2. [follow-up action]
3. [further steps if applicable]

## Watch Out For

- [gotcha, edge case, or known issue]

Rules:

• Be specific. "Implement process() in engine.go" not "continue implementation"
• Include file paths with line references where helpful
• Mention rejected alternatives so next session doesn't re-explore them
• If $ARGUMENTS provided, focus the handoff on that area

Step 3: Save and Display

3a: Save to beads (if task exists)

If there's an in-progress task:

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
br comments add $ISSUE_ID "## Handoff - $TIMESTAMP

$HANDOFF_CONTENT"

3b: Display

HANDOFF READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[handoff content]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Copy the above into your next Claude session to resume.

Notes

• Short session (< 5 exchanges): warn "Short session — handoff may be thin. Add notes with /handoff <context>"
• Handoff is a snapshot, not a plan — describe state, not strategy
• Don't include full file contents — just paths and what matters