/handoff

name: handoff
description: >
  Generate a self-contained handoff prompt that lets the user continue work
  in a fresh coding agent session with empty context. The prompt captures
  everything a new agent needs: project, goal, progress, decisions, current
  state, and remaining work.

  **Triggers — use this skill when:**
  - User says "handoff", "hand off", "hand-off"
  - User asks to "generate a continuation prompt"
  - User says "give me a prompt to continue this"
  - User asks to "wrap up for a new session"
  - User says "context transfer", "session transfer"
  - User asks "how do I pick this up later"
  - User wants to "pass this to another agent"

Handoff — Session Context Transfer

Generate a self-contained prompt that a fresh coding agent (with zero prior context) can use to seamlessly continue the current work.

Philosophy

Context is expensive. When a session hits its limit, or you want to switch tools, the work-in-progress knowledge shouldn't evaporate. A good handoff prompt is:

• **Self-contained** — no references to "our earlier conversation"
• **Actionable** — the new agent knows exactly what to do next
• **Honest** — clearly states what's done, what's broken, and what's uncertain
• **Minimal** — includes only what's needed, not a transcript of the old session

---

Workflow

Step 1 — Gather State

Collect facts from the codebase. Do not rely on conversation memory alone — verify against the filesystem.

# Project identity
basename $(pwd)
git remote -v 2>/dev/null | head -2

# Branch and recent work
git branch --show-current 2>/dev/null
git log --oneline -10 2>/dev/null

# Uncommitted changes (critical for handoff)
git status --short 2>/dev/null
git diff --stat 2>/dev/null

# Stashed work
git stash list 2>/dev/null

# Any running processes or dev servers the user should know about
# (mention if relevant to the task)

Step 2 — Synthesize Context from the Session

Review the conversation to extract:

| Element | Question to answer | |---------|-------------------| | **Goal** | What is the user ultimately trying to accomplish? | | **Scope** | What specific task was this session focused on? | | **Completed** | What has been done? (commits, files created/edited, commands run) | | **In-progress** | What was being worked on when the handoff was requested? | | **Remaining** | What still needs to be done? | | **Decisions** | What architectural or design choices were made and why? | | **Blockers** | Any issues, bugs, or unknowns that the next session should know about? | | **Key files** | Which files are most relevant to the current task? |

Step 3 — Generate the Handoff Prompt

Produce a single Markdown code block containing the prompt. The user copies this into their next session.

---

Handoff Prompt Template

Use this structure. Adapt and omit sections as needed — a trivial task doesn't need architectural decisions. The prompt should be as short as possible while remaining complete.

Project: <name> — <one-line description> Path: <absolute path to project root> Branch: <current branch>

Goal

<What the user is trying to accomplish — the big picture.>

Context

<Brief project context the new agent needs. Tech stack, relevant architecture, anything non-obvious about the codebase.>

What's Been Done

• <Completed item 1 — be specific: files changed, commits made>
• <Completed item 2>
• ...

Current State

<What state is the codebase in right now? Clean? Dirty files? Failing tests? Mention uncommitted changes explicitly — the new agent should not accidentally discard or duplicate work.>

Dirty files:

• <path/to/file — what was changed and why>
• ...

What's Left

1. <Next concrete step — this is what the new agent should do first> 2. <Subsequent step> 3. ...

Key Decisions

• <Decision 1: what was chosen and why>
• <Decision 2>

Key Files

• `<path>` — <why this file matters for the current task>
• `<path>` — <description>

Gotchas

• <Anything surprising, non-obvious, or easy to get wrong>

````

---

## Guidelines

### Be Specific, Not Vague
- ❌ "We updated the config"
- ✅ "Added `pi-heartbeat` settings block to `settings.json.example` with all 6 fields"

### Include Dirty File Details
Uncommitted changes are the most fragile part of a handoff. List every dirty file with a brief note on what changed. If there's a large diff, summarize the intent rather than listing every line.

### State the Next Action Clearly
The first item under "What's Left" should be an unambiguous instruction the new agent can act on immediately. Not "continue the refactor" but "refactor `src/parser.ts` to use the new `TokenStream` class — the interface is defined in `src/types.ts:42`".

### Keep It Proportional
- Quick fix session → 10-15 line handoff
- Multi-file feature session → 30-50 line handoff
- Major refactor → up to 80 lines, but no more

### Don't Include
- Full file contents (the agent can read them)
- Conversation transcript or reasoning history
- Obvious project facts the agent will discover from `package.json` etc.
- Emotional context ("we struggled with this" — just state the facts)

---

## Output

1. Present the handoff prompt inside a single fenced code block so it's easy to copy
2. If there are uncommitted changes, mention this outside the code block as a reminder
3. Optionally suggest saving the prompt to a file: `pbcopy` or write to `.handoff.md`