espennilsen/handoff

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