Session Handoff

name: session-handoff description: Create comprehensive handoff documents for seamless AI agent session transfers. Use when context window approaches capacity, major task milestones are completed, work sessions are ending, or resuming work from a previous session. Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity. tags: [session, handoff, context, continuity, agents]

Session Handoff

Create and resume from comprehensive handoff documents for seamless AI agent session transfers. Solves the critical problem of context exhaustion in long-running agent sessions.

When to Use

• Context window approaching capacity after extensive work
• Major task milestone completed (good checkpoint)
• Work session ending and continuation expected
• Resuming work with "load handoff", "resume from", "continue where we left off"
• After 5+ file edits or complex debugging sessions (proactive suggestion)

Mode Selection

Determine mode from user intent:

CREATE Workflow

Step 1: Generate Handoff Document

Create the handoff file at .claude/handoffs/YYYY-MM-DD-HHMMSS-{task-slug}.md.

Step 2: Fill Required Sections

# Session Handoff: {Task Description}

## Date
{YYYY-MM-DD HH:MM}

## Current State Summary
- What was being worked on
- Current progress (percentage or phase)
- What is working vs. what is not

## Important Context
- Key decisions made and WHY
- Architecture/design choices
- Gotchas discovered
- Environment or config specifics

## Files Modified
- `path/to/file1.py` - What was changed and why
- `path/to/file2.ts` - What was changed and why

## Immediate Next Steps
1. First thing to do (most specific)
2. Second thing to do
3. Third thing to do

## Decisions Made
| Decision | Rationale | Alternatives Considered |
|---|---|---|
| Chose X over Y | Because Z | A, B, C |

## Open Questions
- Unresolved issues needing investigation
- Questions for the user

## Dependencies & Blockers
- External dependencies
- Blocked items with reason

## Commands to Run
```bash
# Commands needed to get back to working state

### Step 3: Validate Completeness

Check that the handoff document has:
- [ ] Current State Summary is specific (not vague)
- [ ] Next Steps are numbered and actionable
- [ ] All modified files are listed with change descriptions
- [ ] Decisions include rationale
- [ ] No placeholder text remaining

### Step 4: Confirm with User

Present the handoff for review before finalizing.

## RESUME Workflow

### Step 1: Find Handoffs

List available handoffs:
```bash
ls -la .claude/handoffs/*.md 2>/dev/null

Step 2: Check Staleness

Step 3: Load and Verify

1. Read the handoff document
2. Verify listed files still exist and match expectations
3. Check git log for changes since handoff date
4. If conflicts found, report to user before proceeding

Step 4: Resume Work

Begin from "Immediate Next Steps" item #1.

Step 5: Update or Chain

For continued long sessions, create a new handoff that links to the previous one:

## Continues From
- `.claude/handoffs/2026-02-27-143022-auth-refactor.md`

Handoff Chaining

For multi-session projects, handoffs form a chain:

Session 1 handoff → Session 2 handoff → Session 3 handoff
                     (continues-from)    (continues-from)

Each handoff captures its own context while linking to predecessors for full history.

Storage Convention

.claude/handoffs/
  2026-02-28-093015-api-migration.md
  2026-02-28-143022-auth-refactor.md
  2026-02-27-110000-database-schema.md

Anti-Patterns

References

• Based on softaworks/agent-toolkit session-handoff (MIT License)