Managing Session Continuity

Session state mgmt: context → JSON → restore

When to Use

Session end w/ unfinished work
New session w/ sp.json exists
User: "save|load|resume session|progress|work"
/save-session-protocol or /load-session-protocol invoked

Core Workflows

WF1: Save Context

Purpose: Capture state → sp.json

Steps:

Check session state
- Protocol loaded this session? → Skip Read (overwrite)
- Protocol NOT loaded? → Read sp.json (merge)
Extract context
- Pending/in_progress: ALL from TodoWrite
- Completed: last 5 individual + consolidate older (see consolidation matrix)
- Context blocks: arch decisions, critical pitfalls, error patterns, plan file refs
- Git (if .git exists):
```
[ -d .git ] && {
  git rev-parse --abbrev-ref HEAD 2>/dev/null  # branch
  git rev-parse HEAD 2>/dev/null                # commit
}
```

Consolidate tasks (decision: 3+ = consolidate)

[ ] Same feature/area (e.g., "redesign page X")
[ ] >5 related completed tasks
[ ] No critical findings to preserve individually
[ ] >3 days since last task in group

If 3+ → group into 1 task w/ consolidated=true + summary

Consolidation format:

{
  "id": "TASK_XXX",
  "title": "Redesign homepage layout",
  "status": "completed",
  "consolidated": true,
  "consolidated_count": 12,
  "context": "Summary: Redesigned nav, hero, footer. Pitfall: CSS grid safari compat. See: docs/homepage-plan.md",
  "completed": "2025-11-26T14:00:00Z"
}

Build JSON (minified, no pretty-print)
- Schema: see JSON Format
- Task IDs: TASK_XXX (sequential, unique)
- Timestamps: ISO8601 UTC (YYYY-MM-DDTHH:MM:SSZ)
- Privacy: strip usernames from paths (~/project not /Users/john/project)
Write
- Write(sp.json) minified format
Report
- "Saved X pend, Y done (Z consolidated). Next: TASK_XXX"

WF2: Load Context

Purpose: Parse sp.json → restore state

Steps:

Read + parse
- Read(sp.json)
- Extract: metadata, tasks[], context_blocks[]

Validate git (if metadata has git fields AND .git exists)

[ -d .git ] && {
  curr=$(git rev-parse HEAD 2>/dev/null)
  curr_br=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
  [ "$curr" != "$saved_commit" ] && warn "Git state changed"
  [ "$curr_br" != "$saved_branch" ] && warn "Branch: $saved → $curr_br"
}

Build summary
- Age: calc from metadata.created
- Counts: pend/prog/done (note consolidated count)
- Next: first pend/prog
- Warnings: git drift (if any)
Present
- Concise: counts, next action, warnings

JSON Format

Schema

{
  "metadata": {
    "version": "2.0",
    "created": "2025-11-26T10:00:00Z",
    "updated": "2025-11-26T14:00:00Z",
    "git_branch": "feature/auth",
    "git_commit": "abc123f5d2e8a1b4c6e9f3a7"
  },
  "tasks": [
    {
      "id": "TASK_001",
      "title": "Fix auth middleware",
      "status": "pending",
      "priority": "P1",
      "category": "BUGFIX",
      "created": "2025-11-26T10:00:00Z",
      "completed": null,
      "consolidated": false,
      "consolidated_count": 0,
      "context": "JWT RS256 validation fails. PEM format req. See: src/auth/middleware.ts:45",
      "files": ["src/auth/middleware.ts:45", "config/jwt.ts:12"]
    },
    {
      "id": "TASK_010",
      "title": "Redesign homepage",
      "status": "completed",
      "priority": "P2",
      "category": "FEATURE",
      "created": "2025-11-20T09:00:00Z",
      "completed": "2025-11-24T18:00:00Z",
      "consolidated": true,
      "consolidated_count": 12,
      "context": "Redesigned nav, hero, footer (12 tasks). Pitfall: CSS grid Safari compat fixed with -webkit-. Plan: docs/homepage-plan.md",
      "files": ["docs/homepage-plan.md"]
    }
  ],
  "context_blocks": [
    {
      "title": "JWT Auth Setup",
      "content": "RS256 algo. Pub key: ~/config/jwt-keys/public.pem. TTL: 1h access, 7d refresh. Rotation: monthly",
      "updated": "2025-11-26T14:00:00Z",
      "related_tasks": ["TASK_001"]
    }
  ]
}

Fields

metadata (req):

version: "2.0"
created/updated: ISO8601
git_branch/git_commit: str|null

tasks (req, arr, ≥1):

id: "TASK_XXX"
title: str
status: "pending"|"in_progress"|"completed"
priority: "P1"|"P2"|"P3" (opt)
category: BUGFIX|FEATURE|CONFIG|DOCS|TEST|REFACTOR (opt)
created: ISO8601
completed: ISO8601|null
consolidated: bool (true if grouped from multiple)
consolidated_count: int (# of original tasks if consolidated)
context: str (opt, include: summary, pitfalls, plan refs, file refs)
files: arr[str] (opt, path:line format, rel or ~/)

context_blocks (opt, arr):

title: str
content: str (arch decisions, error patterns, critical pitfalls)
updated: ISO8601
related_tasks: arr[task_id] (opt)

Format Rules

Minified JSON: no whitespace, single line
Timestamps: UTC w/ Z suffix
Completed limit: ≤5 individual + consolidated groups (no hard limit on consolidated)
Privacy:
- Paths: ~/ or relative (never /Users/username/ or C:\Users\username)
- No emails, API keys, tokens, credentials, personal info
Task IDs: sequential (TASK_001, TASK_002...)

Consolidation Matrix

Decision (3+ = consolidate):

[ ] Same feature/area
[ ] >5 related completed tasks
[ ] No critical findings to preserve individually
[ ] >3 days since last task in group

If 3+ → create consolidated task:

title: feature/area name
consolidated: true
consolidated_count: N
context: summary + pitfalls + file refs
completed: last task completion ts

Keep individual (never consolidate):

Critical bugs w/ specific fixes
Tasks w/ unique pitfalls/lessons
Recent (<3 days) completed
Tasks referenced by pending work

Tool Usage

Write: sp.json (minified)
Read: sp.json (if not loaded this session) or existing (if merge needed)
Bash: git ops (only if .git exists)

Integration

Invoked by:

/save-session-protocol → WF1
/load-session-protocol → WF2

Examples

Save (fresh session):

User: "Save progress"
Claude: [Check: protocol not loaded → skip Read]
        [Extract: 3 pend, 8 done → consolidate 5 old → 3 remain]
        [Git: .git exists → capture state]
        Saved 3 pend, 3 done (5 consolidated). Next: TASK_001 - Fix auth

Load:

User: "Load session"
Claude: Loaded (2d old)
        - 3 pend, 3 done (5 consolidated into 1)
        - Next: TASK_001 - Fix auth middleware
        - Git: state changed (2 commits ahead)

Error Handling

No .git → skip git (no error)
Invalid JSON → error "Cannot load: invalid JSON"
Missing metadata → error "Cannot load: missing metadata"
Never fail silently

Output Format

Save:

Saved → sp.json
- 5 pend (2 P1, 3 P2)
- 8 done (3 individual, 1 consolidated from 12)
- Git: feature/auth @ abc123f
Next: TASK_001 - Fix JWT validation