handoff

name	handoff
description	Generate a handoff prompt to pass context to another agent thread. Use when switching repos, handing off work, or sharing context between agents.
tags	["personal"]

Context Handoff

Generate a structured prompt capturing the current conversation context so it can be pasted into another agent thread or saved for session continuity.

Arguments

• $ARGUMENTS - Optional: specific instructions about what to emphasize or who the target is

Context

• Repo: !git rev-parse --show-toplevel 2>/dev/null | xargs basename 2>/dev/null | head -1
• Branch: !git branch --show-current 2>/dev/null || echo '(not in a git repo)'
• Recent commits: !git log origin/HEAD..HEAD --oneline 2>/dev/null | head -15
• Uncommitted changes: !git status --short 2>/dev/null | head -20
• Changed files vs base: !git diff --name-only origin/HEAD..HEAD 2>/dev/null | head -30

Instructions

Review the full conversation history and synthesize a handoff prompt.

Step 1: Generate the Handoff Document

Use this format, omitting empty sections:

## Handoff: [brief title]

### Background
[1-3 sentences on what was being worked on and why]

### What Was Done
- [Completed work with specific file paths]

### Current State
[Branch state, what is working, what is not]

### Key Decisions
- [Decision]: [Rationale]

### Remaining Work
- [ ] [Specific actionable items]

### Important Context
- [Gotchas, constraints, or patterns the next agent needs]
- [Specific file paths, function names, code patterns]

### Files to Read First
- [Ordered list of files to get up to speed]

Keep it concise but complete enough that the receiving agent can continue without re-discovering context.

Step 2: Present the Handoff and Copy to Clipboard

Print the handoff inside a fenced code block so the user can review it. Then automatically copy it to the clipboard using pbcopy:

cat <<'HANDOFF_EOF' | pbcopy
[the full handoff document content]
HANDOFF_EOF

This ensures the handoff is immediately ready to paste into a new session without manual selection.

Step 3: Persist to memory (optional)

If a persistent memory system is available in this session, save a one- or two-sentence summary of the handoff (branch, repo, remaining items, key files) so the context survives beyond the clipboard. Skip this step if no memory system is present — the clipboard copy from Step 2 is the primary deliverable.