handoff-template.md

Handoff Template

Use this template structure when creating handoff documents. The smart scaffold script will pre-fill metadata sections; complete the remaining sections based on session context.

Table of Contents

• Session Metadata
• Current State Summary
• Codebase Understanding
  • Architecture Overview
  • Critical Files
  • Key Patterns Discovered
• Work Completed
  • Tasks Finished
  • Files Modified
  • Decisions Made
• Pending Work
  • Immediate Next Steps
  • Blockers/Open Questions
  • Deferred Items
• Context for Resuming Agent
  • Important Context
  • Assumptions Made
  • Potential Gotchas
• Environment State
• Related Resources
• Template Usage Notes

---

Handoff: [TASK_TITLE]

Session Metadata

• Created: [TIMESTAMP]
• Project: [PROJECT_PATH]
• Branch: [GIT_BRANCH]
• Session duration: [APPROX_DURATION]

Current State Summary

[One paragraph: What was being worked on, current status, and where things left off]

Codebase Understanding

Architecture Overview

[Key architectural insights discovered during this session - how the system is structured, main components, data flow]

Critical Files

File	Purpose	Relevance
path/to/file	What this file does	Why it matters for this task

Key Patterns Discovered

[Important patterns, conventions, or idioms found in this codebase that the next agent should follow]

Work Completed

Tasks Finished

• Task 1 - brief description of what was done
• Task 2 - brief description

Files Modified

File	Changes	Rationale
path/to/file	Description of changes	Why this change was made

Decisions Made

Decision	Options Considered	Rationale
Chose X over Y	X, Y, Z	Why X was chosen

Pending Work

Immediate Next Steps

1. [Most critical next action - what to do first]
2. [Second priority]
3. [Third priority]

Blockers/Open Questions

• Blocker: [description] - Needs: [what's required to unblock]
• Question: [unclear aspect] - Suggested: [potential resolution]

Deferred Items

• Item 1 (deferred because: [reason, e.g., out of scope, needs user input])

Context for Resuming Agent

Important Context

[Critical information the next agent MUST know to continue effectively - this is the most important section for handoff]

Assumptions Made

• Assumption 1: [what was assumed to be true]
• Assumption 2: [another assumption]

Potential Gotchas

• [Things that might trip up a new agent - edge cases, quirks, non-obvious behavior]

Environment State

Tools/Services Used

• [Tool/Service]: [relevant configuration or state]

Active Processes

• [Any background processes, dev servers, watchers that may be running]

Environment Variables

• [Key env vars that matter for this work - DO NOT include secrets/values, just names]

Related Resources

• [Link to relevant documentation]
• [Related file paths]
• [External resources consulted]

---

Template Usage Notes

When filling this template:

1. Be specific and concrete - vague descriptions don't help the next agent
2. Include file paths with line numbers where relevant (e.g., src/auth.ts:142)
3. Prioritize the "Important Context" and "Immediate Next Steps" sections
4. Don't include sensitive data (API keys, passwords, tokens)
5. Focus on WHAT and WHY, not just WHAT - rationale is crucial for handoffs