handoff-prompt

Produce a compact, copy-pasteable prompt that a fresh Claude Code session can use to continue the current work. Do not ask clarifying questions. Output once and stop.

Token budget

The emitted handoff block MUST be ≤ 300 tokens. If you exceed budget, drop sections in this order until you fit:

1. Key decisions & gotchas
2. Compress Progress so far to the 3 most load-bearing items
3. Context references — keep only the single most relevant path

Never drop: Current task, Where we stopped, Next steps.

How to gather the content

Introspect this session — do NOT ask the user. Derive each section from what you can see:

• Current task — from the user's active goal in recent messages.
• Progress so far — from your own tool calls that changed state (Edit, Write, Bash commands that mutated anything, file creations). Cite file paths and, where useful, line numbers.
• Where we stopped — your last substantive action plus the reason you paused (end of step, blocker, awaiting user input, tool failure).
• Next steps — from any plan/spec/TODO in play, or the obvious continuation of the last action.
• Key decisions & gotchas — non-obvious choices or traps surfaced during the session. Include only if real; skip otherwise.
• Context references — check the current working directory for CLAUDE.md, AGENTS.md, and any active plan or spec file (e.g., under docs/superpowers/plans/ or docs/superpowers/specs/). Include their absolute paths. Never inline their contents.
• Open questions — only if the session has unresolved questions needing user input.

Output rules

• Emit exactly one fenced markdown code block containing the handoff. One short lead-in line is allowed (e.g., "Paste this into your next session:"). Nothing after the block.
• Omit any section that has no real content — drop the header too, don't leave it empty.
• Terse bullets. Concrete nouns (file paths, commands, line numbers). No filler prose, no restatement of obvious context.
• Write the handoff in second person, as instructions to a fresh agent.
• Reference project context files by absolute path only. Never paste their contents.

Template

Use this structure inside the fenced block, omitting empty sections:

You are continuing a previous Claude Code session. Read the sections below, then continue the work.

## Current task
<1–3 sentences>

## Progress so far
- <file:line or action — terse>

## Where we stopped
<last action + why stopped>

## Next steps
1. <concrete action>

## Key decisions & gotchas
- <non-obvious decision or trap>

## Context references
- CLAUDE.md: <abs path>
- AGENTS.md: <abs path>
- Plan/spec: <abs path>

## Open questions
- <question for the user>

Checklist before emitting

• One fenced code block, nothing trailing it
• ≤ 300 tokens inside the block
• No empty section headers
• CLAUDE.md / AGENTS.md referenced by path only (if present)
• Current task, Where we stopped, Next steps all present