session-handoff

1# Handoff
2 
3Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.
4 
5## Mode Selection
6 
7Determine which mode applies:
8 
9**Creating a handoff?** User wants to save current state, pause work, or context is getting full.
10- Follow: CREATE Workflow below
11 
12**Resuming from a handoff?** User wants to continue previous work, load context, or mentions an existing handoff.
13- Follow: RESUME Workflow below
14 
15**Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
16> "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
17 
18## CREATE Workflow
19 
20### Step 1: Generate Scaffold
21 
22Run the smart scaffold script to create a pre-filled handoff document:
23 
24```bash
25python scripts/create_handoff.py [task-slug]
26```
27 
28Example: `python scripts/create_handoff.py implementing-user-auth`
29 
30**For continuation handoffs** (linking to previous work):
31```bash
32python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
33```
34 
35The script will:
36- Create `.claude/handoffs/` directory if needed
37- Generate timestamped filename
38- Pre-fill: timestamp, project path, git branch, recent commits, modified files
39- Add handoff chain links if continuing from previous
40- Output file path for editing
41 
42### Step 2: Complete the Handoff Document
43…