Handoff

Generate a HANDOFF.md in the project root that gives a fresh agent everything it needs to continue the current task without re-reading the entire conversation.

Why this matters

Context windows are finite. When a session ends or gets too long, the next agent starts cold. A good handoff document is the difference between the next agent picking up in seconds versus spending 10 minutes re-discovering what you already know. Write it as if you're briefing a colleague who is smart but has zero context about this project or task.

When triggered

1. Read the full conversation history and any files you modified or read during the session.
2. Write HANDOFF.md to the project root. If the file already exists, overwrite it completely.

What to write

Organize the document under these sections. Omit any section that genuinely has nothing to report — an empty section is worse than no section.

1. Objective

One or two sentences: what is the user trying to accomplish? State the end goal, not the intermediate steps.

2. Current Status

Where things stand right now. Be specific: "Tests pass on module X but module Y has a failing assertion on line 42" is useful; "making progress" is not.

3. What Was Done

A concise list of actions taken in this session. For each item, note the outcome:

• What you tried
• Whether it worked, partially worked, or failed
• If it failed, why (error messages, root cause if known)

This is the most valuable section for the next agent. Don't just list successes — the failures and dead ends save the next agent from repeating them.

4. Key Decisions & Reasoning

Any non-obvious choices made during the session and why. Architecture decisions, library choices, trade-offs accepted. The next agent needs to know what's intentional vs. accidental.

5. Open Issues & Blockers

Anything unresolved: bugs, unanswered questions, external dependencies, things the user needs to decide. Be specific enough that the next agent can act on these.

6. Next Steps

Concrete, actionable items the next agent should do first. Prioritize them. If there's a specific order that matters, say so and explain why.

7. Relevant Files & Paths

List files that are central to the task — files modified, config files that matter, test files to run. Use relative paths from the project root. Don't dump every file you glanced at; only include ones the next agent will actually need to open.

Writing principles

• Be specific, not vague. File names, line numbers, error messages, command outputs. Concrete details are what make a handoff useful.
• Capture the why, not just the what. "Changed the retry logic from 3 to 5 attempts because the API has intermittent 502s under load" is far more useful than "updated retry count".
• Include failures. Dead ends are valuable knowledge. If you spent time investigating something that turned out to be irrelevant, say so — it prevents the next agent from going down the same path.
• Keep it scannable. Use bullet points and short paragraphs. The next agent should be able to skim the document in under a minute and know exactly where to start.
• No filler. Don't pad sections. Don't add generic advice. Every sentence should carry information the next agent can act on.