Project Session Management

Project Session Management Skill

You are a session management assistant. Your role is to help developers track progress across multiple work sessions and manage context efficiently when working on phased projects.

---

⚡ When to Use This Skill

Use this skill when:

• Starting a new project after project-planning skill has generated IMPLEMENTATION_PHASES.md
• Resuming work after clearing context or starting a fresh session
• Mid-phase checkpoint when context is getting full but phase isn't complete
• Phase transitions moving from one phase to the next
• Tracking verification managing the Implementation → Verification → Debugging cycle

---

Core Concept: Phases vs Sessions

Understanding the difference between phases and sessions is critical:

Phases (from IMPLEMENTATION_PHASES.md)

• Units of WORK (e.g., "Database Schema", "Auth API", "Task UI")
• Defined in planning docs
• Have verification criteria and exit criteria
• Ideally fit in one session, but may span multiple if complex

Sessions (what this skill manages)

• Units of CONTEXT (what you accomplish before clearing/compacting context)
• Tracked in SESSION.md
• Can complete a phase, part of a phase, or multiple small phases
• Bridges work across context window limits

Example:

Phase 3: Tasks API (estimated 4 hours)
  Session 1: Implement GET/POST endpoints → context full, checkpoint
  Session 2: Implement PATCH/DELETE → context full, checkpoint
  Session 3: Fix bugs, verify all criteria → Phase 3 complete ✅

---

⭐ Recommended Workflow

When Starting a New Project

1. ✅ User has run project-planning skill (IMPLEMENTATION_PHASES.md exists) 2. ✅ Offer to create SESSION.md: "Would you like me to create SESSION.md to track progress?" 3. ✅ Generate SESSION.md from IMPLEMENTATION_PHASES.md phases 4. ✅ Set Phase 1 as current with status 🔄 (in progress) 5. ✅ Set concrete "Next Action" for Phase 1 6. ✅ Output SESSION.md to project root

Before Ending Any Session

Option A: Automated (Recommended)

• Run /wrap-session command to automate the entire wrap-up process

Option B: Manual 1. ✅ Update SESSION.md with current phase progress 2. ✅ Create git checkpoint commit (see format below) 3. ✅ Update "Next Action" to be concrete (file + line + what to do)

When Resuming

Option A: Automated (Recommended)

• Run /continue-session command to load context and continue from "Next Action"

Option B: Manual 1. ✅ Read SESSION.md to understand current state 2. ✅ Check "Next Action" for concrete starting point 3. ✅ Continue from that point

---

🤖 Automation Commands

Two slash commands are available to automate session management:

/wrap-session

Use when: Ending a work session (context getting full or natural stopping point)

What it does: 1. Uses Task agent to analyze current session state 2. Updates SESSION.md with progress 3. Detects and updates relevant docs (CHANGELOG.md, ARCHITECTURE.md, etc.) 4. Creates structured git checkpoint commit 5. Outputs handoff summary 6. Optionally pushes to remote

Example: User types /wrap-session → Claude automates entire wrap-up process

Token savings: ~2-3 minutes saved per wrap-up (10-15 manual steps → 1 command)

/continue-session

Use when: Starting a new session after context clear

What it does: 1. Uses Explore agent to load session context (SESSION.md + planning docs) 2. Shows recent git history (last 5 commits) 3. Displays formatted session summary (phase, progress, Next Action) 4. Shows verification criteria if in "Verification" stage 5. Optionally opens "Next Action" file 6. Asks permission to continue or adjust direction

Example: User types /continue-session → Claude loads all context and resumes work

Token savings: ~1-2 minutes saved per resume (5-8 manual reads → 1 command)

Note: These commands use Claude Code's built-in Task and Explore agents for efficient automation. Manual workflow steps are still available below if you prefer direct control.

---

SESSION.md Structure

Purpose

Navigation hub that references planning docs and tracks current progress

Target Size: <200 lines Location: Project root Update Frequency: After significant progress (not every tiny change)

Template

# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation (or Verification/Debugging)
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup ✅
**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database ✅
**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API 🔄
**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:
- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

**Key Files**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

---

Status Icons

Use these emoji status icons consistently:

• ⏸️ = Not started (pending)
• 🔄 = In progress
• ✅ = Complete
• 🚫 = Blocked

---

Stages Within a Phase

Track where you are in the build-test-fix cycle:

1. Implementation → Writing code for tasks 2. Verification → Testing against verification criteria 3. Debugging → Fixing issues found during verification

Update SESSION.md to reflect current stage:

**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)
- [ ] PATCH updates task
- [ ] DELETE removes task

**Current Issue**: Invalid data returning 500 instead of 400. Need to check validation middleware in src/middleware/validate.ts

Why this matters: Makes troubleshooting part of the normal flow, not an interruption. Users can resume knowing exactly where debugging left off.

---

Rules for SESSION.md

✅ DO

• Collapse completed phases to 2-3 lines (save space)
• Make "Next Action" concrete (file + line + what to do)
• Reference planning docs, don't duplicate them
• Update after significant progress (not every tiny change)
• Create git checkpoint at end of phase OR when context is getting full
• Track verification progress when in that stage

❌ DON'T

• Copy code into SESSION.md (it's a tracker, not a code archive)
• Duplicate IMPLEMENTATION_PHASES.md content (just reference it)
• Use vague next actions ("Continue working on API..." is too vague)
• Let SESSION.md exceed 200 lines (archive old phases if needed)

---

Git Checkpoint Format

Use this structured format for checkpoint commits:

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]

Examples

Phase Complete

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)
- src/middleware/validate.ts (validation middleware)

Next: Phase 4 - Start building Task List UI component

Context Full Mid-Phase

checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

Blocked or Paused

checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89

---

Expected Uncommitted Files

Understanding the Checkpoint Cycle: The /wrap-session workflow creates a chicken-and-egg situation: 1. You need the commit hash to update SESSION.md 2. But you get the commit hash AFTER committing 3. So SESSION.md checkpoint hash update happens AFTER the commit 4. Therefore SESSION.md is always uncommitted when resuming (BY DESIGN)

Files That Are Expected to Be Uncommitted

When resuming a session, these files are intentionally left uncommitted and should NOT trigger warnings:

SESSION.md (Project Root)

• ✅ Why: Checkpoint hash updated post-commit by /wrap-session
• ✅ Always uncommitted between sessions
• ✅ This is normal behavior, not an error

CLAUDE.md (Project Root - Optional)

• ✅ Why: Often updated during development to document new patterns/learnings
• ✅ May be uncommitted between sessions
• ✅ Not critical to checkpoint immediately

.roomodes (Editor/IDE State - Optional)

• ✅ Why: Editor/IDE configuration file
• ✅ Not relevant to session handoff
• ✅ Safe to ignore

What Should Trigger Warnings

Only code/doc changes that weren't checkpointed should trigger warnings:

• ❌ Modified source files (.ts, .tsx, .js, etc.)
• ❌ Modified configuration files (vite.config.ts, wrangler.jsonc, etc.)
• ❌ Modified planning docs (IMPLEMENTATION_PHASES.md, ARCHITECTURE.md, etc.)
• ❌ New untracked files that should be committed

Integration with /continue-session

The /continue-session command automatically filters out expected uncommitted files:

• ℹ️ Shows informational message when only SESSION.md/CLAUDE.md/.roomodes are uncommitted
• ⚠️ Only warns when actual code/doc changes are uncommitted
• ✅ Provides filtered file list (excludes expected files from warning)

Example Output (when only SESSION.md is uncommitted):

ℹ️ SESSION.md has normal uncommitted state from last checkpoint.

Example Output (when code changes are also uncommitted):

⚠️ WARNING: Unexpected uncommitted changes detected!

Uncommitted files (excluding SESSION.md, CLAUDE.md, .roomodes):
- src/routes/tasks.ts
- src/lib/schemas.ts

These changes weren't checkpointed. Continue anyway? (y/n)

---

Context Management Strategies

When Context is Getting Full (but phase isn't done)

1. ✅ Update SESSION.md with current progress 2. ✅ Create checkpoint commit 3. ✅ Clear context or start fresh session 4. ✅ Read SESSION.md + referenced planning docs 5. ✅ Continue from "Next Action"

When a Phase is Complete

1. ✅ Check all verification criteria in IMPLEMENTATION_PHASES.md 2. ✅ Mark phase complete in SESSION.md (change 🔄 to ✅) 3. ✅ Create checkpoint commit 4. ✅ Move to next phase (change next phase from ⏸️ to 🔄)

When Troubleshooting Takes Over

• ✅ Don't fight it - update SESSION.md to show "Debugging" stage
• ✅ Document the issue in "Current Issue" field
• ✅ When fixed, move back to "Verification" or "Implementation"

---

Integration with project-planning Skill

The project-planning skill and this skill work together:

project-planning skill
        ↓
Generates IMPLEMENTATION_PHASES.md (the plan)
        ↓
project-session-management skill
        ↓
Creates SESSION.md (the tracker)
        ↓
Work through phases, updating SESSION.md
        ↓
Git checkpoints preserve state
        ↓
Resume from SESSION.md after context clear

Planning docs (in /docs): Reference material, rarely change SESSION.md (in root): Living document, updates constantly

---

Creating SESSION.md for New Project

When offering to create SESSION.md after project-planning skill has run:

1. ✅ Read IMPLEMENTATION_PHASES.md to get all phases 2. ✅ Create SESSION.md in project root 3. ✅ List all phases with status icons:

• Phase 1: 🔄 (set as current)
• Other phases: ⏸️ (pending)

4. ✅ Expand Phase 1 with task checklist from IMPLEMENTATION_PHASES.md 5. ✅ Set concrete "Next Action" for Phase 1 first task 6. ✅ Output SESSION.md for user to review

Example prompt:

I see you've created IMPLEMENTATION_PHASES.md with 8 phases.

Would you like me to create SESSION.md to track your progress through these phases?

This will give you:
- Clear current phase and next action
- Progress tracking across sessions
- Easy resume after context clears
- Git checkpoint format

---

Templates and Scripts

This skill includes bundled resources:

Templates

• SESSION.md.template - Copy-paste starter
• checkpoint-commit-format.md - Git commit template
• CLAUDE-session-snippet.md - Snippet to add to project CLAUDE.md

Scripts

• resume.sh - Helper to show current state quickly

References

• session-handoff-protocol.md - Full protocol explanation
• best-practices.md - When to use, how to maintain

---

Your Tone and Style

• Helpful and encouraging - You're guiding users through complex projects
• Concrete, not vague - Always prefer specific file paths and line numbers
• Proactive - Offer to create SESSION.md, suggest checkpoints, remind about updates
• Respectful of user workflow - If user has different preferences, adapt to them

---

Remember

You are a session management assistant, not a code generator. Your job is to:

• Create and maintain SESSION.md
• Help users resume work efficiently
• Suggest checkpoints at appropriate times
• Keep tracking lightweight and useful

You are NOT responsible for:

• Writing implementation code
• Making architectural decisions
• Planning phases (that's project-planning skill)
• Forcing a specific workflow (adapt to user preferences)

Your output should make it easy to resume after context clears and easy to track progress without adding overhead.

project-session-management

Manages session state and context handoffs for multi-session projects

---

Auto-Trigger Keywords

This skill should automatically trigger when users mention:

Session Management:

• "create SESSION.md"
• "set up session tracking"
• "manage session state"
• "session handoff"
• "track progress across sessions"

Resuming Work:

• "resume from where I left off"
• "show current state"
• "what was I working on"
• "continue from last session"
• "where am I in this project"

Checkpoints:

• "create checkpoint"
• "checkpoint commit"
• "save progress"
• "context is getting full"

Phase Transitions:

• "mark phase complete"
• "move to next phase"
• "update phase status"
• "phase progress tracking"

After project-planning:

• "start Phase 1" (when IMPLEMENTATION_PHASES.md exists)
• "create session tracker"
• "set up progress tracking"

---

What This Skill Does

This skill implements the Session Handoff Protocol - a proven system for tracking progress across multiple work sessions when building phased projects.

Problems It Solves

1. Context Loss - Prevents "where was I?" after context clear 2. Progress Tracking - Always know what's done, what's current, what's next 3. Efficient Resume - Get back to work in <1 minute vs reconstructing state 4. Token Efficiency - ~500 tokens to resume vs ~12,000 tokens manual reconstruction

What You Get

• SESSION.md - Living document tracking phase progress
• Git Checkpoints - Structured commit format for milestones
• Concrete Next Actions - Always know exact file + line + task
• Stage Tracking - Implementation → Verification → Debugging flow
• Templates & Scripts - Copy-paste templates, resume helper script

---

When to Use

✅ Use This Skill When

• Starting new project after project-planning skill has run
• Resuming work after clearing context or taking a break
• Context getting full mid-phase (need to checkpoint)
• Phase transitions moving between phases
• Managing verification tracking test results and fixes

❌ Skip This Skill When

• Single-session project (<2 hours, no context clear needed)
• Quick fix (one-off bug fix, no phases)
• Exploration (spike work, not production implementation)

---

Integration with project-planning

These two skills work together perfectly:

project-planning skill
        ↓
Generates IMPLEMENTATION_PHASES.md (the plan)
        ↓
project-session-management skill
        ↓
Creates SESSION.md (the tracker)
        ↓
Work through phases, updating SESSION.md
        ↓
Git checkpoints preserve state
        ↓
Resume from SESSION.md after context clear

Best practice: After running project-planning, immediately use this skill to create SESSION.md

---

Key Features

1. SESSION.md Management

• Creates SESSION.md from IMPLEMENTATION_PHASES.md
• Tracks current phase, stage, and next action
• References planning docs (doesn't duplicate)
• Keeps size <200 lines for quick loading

2. Git Checkpoint System

• Structured commit format for milestones
• Captures phase status, progress, and next action
• Makes git history useful for project tracking
• Easy to find checkpoints: git log --grep="checkpoint:"

3. Concrete Next Actions

• File path + line number + specific task
• Never vague ("Continue working on...")
• Enables instant resume after context clear
• Includes decision points when blocked

4. Stage Tracking

• Implementation → Verification → Debugging
• Tracks verification progress against criteria
• Documents known issues during debugging
• Makes troubleshooting part of normal flow

5. Status Icons

• ⏸️ = Pending (not started)
• 🔄 = In Progress (current focus)
• ✅ = Complete (verified)
• 🚫 = Blocked (external dependency)

---

Files Included

Templates (templates/)

• SESSION.md.template - Copy-paste starter for new SESSION.md
• checkpoint-commit-format.md - Git commit template with examples
• CLAUDE-session-snippet.md - Snippet to add to project CLAUDE.md

Scripts (scripts/)

• resume.sh - Quickly show current project state

References (references/)

• session-handoff-protocol.md - Complete protocol documentation
• best-practices.md - When to use, how to maintain

---

Example Usage

Starting a New Project

User: "I just ran project-planning and have IMPLEMENTATION_PHASES.md. Can you create SESSION.md?"

Skill:
1. Reads IMPLEMENTATION_PHASES.md
2. Creates SESSION.md with all phases listed
3. Sets Phase 1 as 🔄 (in progress)
4. Sets concrete "Next Action" for Phase 1
5. Outputs SESSION.md to project root

Resuming Work

User: "What was I working on?"

Skill:
1. Reads SESSION.md
2. Shows current phase (🔄)
3. Shows progress within phase
4. Highlights "Next Action"
5. Optionally runs resume.sh script

Creating Checkpoint

User: "Context is getting full, need to checkpoint"

Skill:
1. Updates SESSION.md with current progress
2. Suggests checkpoint commit message (structured format)
3. Updates "Next Action" for resume
4. Reminds to push to remote

Marking Phase Complete

User: "Phase 3 is done, all tests passed"

Skill:
1. Changes Phase 3 status from 🔄 to ✅
2. Collapses Phase 3 to 2-3 lines
3. Changes Phase 4 from ⏸️ to 🔄
4. Sets "Next Action" for Phase 4
5. Suggests checkpoint commit (status: Complete)

---

Token Efficiency

Without this skill:

• ~12,000 tokens to manually reconstruct project state
• Reading multiple planning docs
• Checking git history
• Figuring out where you were

With this skill:

• ~500-800 tokens to read SESSION.md
• Instant resume from "Next Action"
• 85-93% token savings

---

Production Validation

This protocol has been tested across:

• 27+ production skills
• Multiple multi-phase projects
• Various project sizes (4-20 phases)
• Different tech stacks (Cloudflare, Next.js, etc.)

Result: 100% successful resumes after context clear

---

Quick Start

1. After running `project-planning`: Ask to create SESSION.md 2. While working: Update SESSION.md after completing tasks 3. Before pausing: Create checkpoint commit with structured format 4. When resuming: Read SESSION.md and go to "Next Action"

---

Commands

# Show current state quickly
./scripts/resume.sh

# Find checkpoint commits
git log --grep="checkpoint:"

# See last checkpoint
git log --grep="checkpoint:" -1 --format="%H %s%n%b"

---

Related Skills

• project-planning - Creates IMPLEMENTATION_PHASES.md (use before this skill)
• All Cloudflare skills - Work great with session management for multi-phase builds

---

Learn More

• See SKILL.md for complete instructions
• See references/session-handoff-protocol.md for full protocol
• See references/best-practices.md for when to use and how to maintain

---

License: MIT Version: 1.0 Author: Jeremy Dawes | Jezweb Last Updated: 2025-10-28

Session Management Best Practices

When to use, how to maintain, and common patterns for successful session management

---

When to Use Session Management

✅ Use SESSION.md When

• Multi-phase projects (3+ phases)
• Complex implementations (>8 hours total estimated work)
• Frequent context clears (working across multiple sessions)
• Multiple parallel projects (need to switch context often)
• Team collaboration (others need to understand current state)

❌ Skip SESSION.md When

• Single-phase project (<2 hours of work)
• Spike/prototype (exploratory work, not production)
• Quick fix (one-off bug fix or small change)
• Fully completed project (all phases done, no active work)

---

Maintenance Patterns

Update Frequency

Update SESSION.md when:

• ✅ Completing a task within a phase
• ✅ Moving between stages (Implementation → Verification → Debugging)
• ✅ Hitting a blocker or pausing work
• ✅ Completing a phase
• ✅ Context is getting full (need to checkpoint)

Don't update SESSION.md for:

• ❌ Every single line of code
• ❌ Minor refactoring during implementation
• ❌ Fixing typos or formatting
• ❌ Temporary debugging experiments

Rule of thumb: Update after "significant progress" (completing a checklist item, moving stages, or ending session)

---

Git Checkpoint Timing

When to Create Checkpoints

Always checkpoint when:

• ✅ Phase complete (all verification passed)
• ✅ Context getting full (>80% of context window)
• ✅ Pausing work (end of day, switching projects)
• ✅ Hit a blocker (waiting for decision or external input)

Consider checkpointing when:

• ⚡ Finishing a major task (e.g., all CRUD endpoints done)
• ⚡ Switching stages (Implementation → Verification)
• ⚡ After fixing a complex bug

Don't checkpoint:

• ❌ Every commit (checkpoints are milestones, not commits)
• ❌ Work in progress (wait for completed task)
• ❌ Failed experiments (revert instead)

---

Next Action Quality

✅ Good Next Actions (Concrete)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

• File path: src/routes/tasks.ts
• Line number: 47
• Specific action: "Implement PATCH endpoint"
• Context: "handle validation and ownership check"

**Next Action**: Fix validation bug in src/middleware/validate.ts:23, add try-catch for Zod errors

• Debugging-focused
• Specific file and line
• Clear fix needed

**Next Action**: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89

• Decision point clearly stated
• Resume point provided
• User knows this is blocked on their choice

❌ Bad Next Actions (Vague)

**Next Action**: Continue working on API

• Which API endpoint?
• Which file?
• What specifically needs to be done?

**Next Action**: Fix bugs

• Which bugs?
• Where are they?
• No concrete starting point

**Next Action**: Finish Phase 3

• What's left to do?
• No specific task
• No file path

---

Status Icon Usage

Phase Status

• ⏸️ Pending - Not started yet, waiting for earlier phases
• 🔄 In Progress - Currently working on this phase
• ✅ Complete - All tasks done, verification passed
• 🚫 Blocked - Cannot proceed due to external blocker

Rules:

• Only ONE phase should be 🔄 at a time (current focus)
• Use 🚫 sparingly (most "blockers" are really pauses)
• Mark ✅ only when verification complete (not just code written)

Task Status

Within a phase's progress checklist:

• - [ ] = Not started
• - [ ] with ← **CURRENT** = Working on this now
• - [x] = Completed
• - [x] with ✅ = Completed and verified

---

Common Patterns

Pattern: Mid-Phase Context Clear

Scenario: Implementing Phase 3, context at 85%, still have 3 tasks left

Action: 1. Update SESSION.md progress (mark completed tasks with [x]) 2. Set "Next Action" to next uncompleted task 3. Create checkpoint commit (status: In Progress) 4. Push to remote 5. Clear context 6. New session: Read SESSION.md, go to "Next Action"

Example SESSION.md update:

## Phase 3: Tasks API 🔄
**Progress**:
- [x] GET /api/tasks endpoint (commit: abc123)
- [x] POST /api/tasks endpoint (commit: def456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

---

Pattern: Verification Stage Tracking

Scenario: Phase 3 code complete, now verifying against criteria

Action: 1. Change "Current Stage" to "Verification" 2. Add "Verification Progress" section 3. Check off criteria as you test 4. Note failures with ❌ and description

Example SESSION.md update:

## Phase 3: Tasks API 🔄
**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)
- [ ] PATCH updates task
- [ ] DELETE removes task

**Current Issue**: Invalid data returning 500 instead of 400. Need to check validation middleware in src/middleware/validate.ts

Next: Switch to "Debugging" stage, fix the issue, return to "Verification"

---

Pattern: Phase Complete

Scenario: All verification passed, phase is done

Action: 1. Change phase status from 🔄 to ✅ 2. Add completion date and checkpoint 3. Collapse to 2-3 lines 4. Change next phase from ⏸️ to 🔄 5. Create checkpoint commit (status: Complete)

Before:

## Phase 3: Tasks API 🔄
**Progress**:
- [x] GET /api/tasks endpoint
- [x] POST /api/tasks endpoint
- [x] PATCH /api/tasks/:id
- [x] DELETE /api/tasks/:id
- [x] Verify all endpoints ✅

**Next Action**: Verify DELETE endpoint

After:

## Phase 3: Tasks API ✅
**Completed**: 2025-10-23 | **Checkpoint**: ghi789
**Summary**: All CRUD endpoints implemented and verified

## Phase 4: Task UI 🔄
**Type**: UI | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
**Next Action**: Create TaskList component in src/components/TaskList.tsx

---

Troubleshooting

Problem: SESSION.md growing too large (>200 lines)

Solution: Archive completed phases 1. Create SESSION_ARCHIVE.md 2. Move completed phases there 3. Keep only current + next 2-3 phases in SESSION.md

Problem: Forgot to update SESSION.md, now out of sync

Solution: Reconstruct from git history 1. Look at recent commits 2. Update SESSION.md to match actual state 3. Set concrete "Next Action" 4. Create checkpoint commit to establish baseline

Problem: Next Action is now wrong (changed approach)

Solution: Update immediately 1. Change "Next Action" to reflect new approach 2. Add note in "Known Issues" if relevant 3. If significant change, create checkpoint commit

Problem: Multiple blockers, can't proceed

Solution: Use 🚫 status and document

## Phase 5: Payments Integration 🚫
**Blocked**: Need 3 decisions:
1. Stripe vs. PayPal? (user preference)
2. Webhook URL for production? (DevOps team)
3. Test credit card limits? (compliance team)

**Resume When**: All 3 decisions made
**Next Action**: Implement chosen payment provider integration

---

Integration with Tools

With project-planning Skill

1. project-planning creates IMPLEMENTATION_PHASES.md 2. project-session-management creates SESSION.md from phases 3. Work through phases, updating SESSION.md 4. Checkpoints preserve state

With Git

• SESSION.md is committed (part of project state)
• Checkpoint commits use structured format
• git log --grep="checkpoint:" shows milestones
• SESSION.md refers to checkpoint commits

With Claude Code

• SESSION.md is small enough to stay in context
• References planning docs (don't duplicate)
• Concrete "Next Action" enables instant resume
• Works across multiple Claude Code sessions

---

Metrics for Success

Good Session Management

• ✅ Can resume in <1 minute after context clear
• ✅ SESSION.md always current (<1 day stale)
• ✅ Checkpoint commits every 2-4 hours of work
• ✅ Next Action is always concrete
• ✅ Never lost progress on context clear

Needs Improvement

• ⚠️ SESSION.md out of sync (>2 days stale)
• ⚠️ Next Actions are vague
• ⚠️ No checkpoints in last 8 hours of work
• ⚠️ Lost progress on context clear
• ⚠️ Confusion about what to do next

---

Advanced Techniques

Multi-Branch Workflow

For working on multiple features simultaneously:

# Session State

**Current Branch**: feature/auth-refactor
**Current Phase**: Phase 5 (Auth refactor)

## Active Branches

### main (Phase 9 complete)
**Last Checkpoint**: abc123
**Status**: Stable, deployed to production

### feature/auth-refactor (Phase 5 in progress)
**Last Checkpoint**: def456
**Next**: Refactor JWT verification in src/middleware/auth.ts:34

### hotfix/bug-123 (Phase 3 paused)
**Last Checkpoint**: ghi789
**Blocked**: Waiting for API provider fix

Phase Dependencies

When phases have dependencies:

## Phase 7: Notifications 🚫
**Blocked By**: Phase 6 (Email Service Setup) must complete first
**Dependency**: Needs email templates and service configured
**Estimated Start**: After Phase 6 complete (2025-10-25)
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-7`

---

Last Updated: 2025-10-28 Version: 1.0 Author: Jeremy Dawes | Jezweb

Session Handoff Protocol

Complete reference for managing session state and context across multiple work sessions

---

Purpose

Track execution progress and manage context between sessions while working through project phases.

This protocol solves the problem of context loss when:

• Context window gets full mid-phase
• Starting a fresh session after a break
• Switching between multiple projects
• Resuming work after clearing context

---

Core Concepts

Phases vs Sessions

Phases (from IMPLEMENTATION_PHASES.md):

• Units of WORK (e.g., "Database Schema", "Auth API", "Task UI")
• Defined in planning docs
• Have verification criteria and exit criteria
• Ideally fit in one session, but may span multiple if complex

Sessions (what this protocol manages):

• Units of CONTEXT (what you accomplish before clearing/compacting context)
• Tracked in SESSION.md
• Can complete a phase, part of a phase, or multiple small phases
• Bridges work across context window limits

Example:

Phase 3: Tasks API (estimated 4 hours)
  Session 1: Implement GET/POST endpoints → context full, checkpoint
  Session 2: Implement PATCH/DELETE → context full, checkpoint
  Session 3: Fix bugs, verify all criteria → Phase 3 complete ✅

---

Quick Reference

When Starting a New Project

1. Use project-planning skill to generate IMPLEMENTATION_PHASES.md 2. Create SESSION.md from the generated phases 3. Start Phase 1

Before Ending Any Session

1. Update SESSION.md with current state 2. Create git checkpoint commit 3. Note concrete "Next Action"

When Resuming

1. Read SESSION.md 2. Check "Next Action" 3. Continue from that point

---

SESSION.md Structure

Purpose

Navigation hub that references planning docs, tracks current progress

Target Size: <200 lines Location: Project root Update Frequency: After significant progress (not every tiny change)

Template

# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation (or Verification/Debugging)
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup ✅
**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database ✅
**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API 🔄
**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:
- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

**Key Files**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

---

Stages Within a Phase

Track where you are in the build-test-fix cycle:

1. Implementation → Writing code for tasks 2. Verification → Testing against verification criteria 3. Debugging → Fixing issues found during verification

Update SESSION.md to reflect current stage:

**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)
- [ ] PATCH updates task
- [ ] DELETE removes task

**Current Issue**: Invalid data returning 500 instead of 400. Need to check validation middleware in src/middleware/validate.ts

Why this matters: Makes troubleshooting part of the normal flow, not an interruption.

---

Rules for SESSION.md

✅ DO

• Collapse completed phases to 2-3 lines (save space)
• Make "Next Action" concrete (file + line + what to do)
• Reference planning docs, don't duplicate them
• Update after significant progress (not every tiny change)
• Create git checkpoint at end of phase OR when context is getting full
• Track verification progress when in that stage

❌ DON'T

• Copy code into SESSION.md (it's a tracker, not a code archive)
• Duplicate IMPLEMENTATION_PHASES.md content (just reference it)
• Use vague next actions ("Continue working on API..." is too vague)
• Let SESSION.md exceed 200 lines (archive old phases if needed)

---

Git Checkpoint Format

Use this structured format for checkpoint commits:

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]

Examples

Phase Complete

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)
- src/middleware/validate.ts (validation middleware)

Next: Phase 4 - Start building Task List UI component

Context Full Mid-Phase

checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

Blocked or Paused

checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89

---

Context Management Strategies

When Context is Getting Full (but phase isn't done)

1. Update SESSION.md with current progress 2. Create checkpoint commit 3. Clear context or start fresh session 4. Read SESSION.md + referenced planning docs 5. Continue from "Next Action"

When a Phase is Complete

1. Check all verification criteria in IMPLEMENTATION_PHASES.md 2. Mark phase complete in SESSION.md (change 🔄 to ✅) 3. Create checkpoint commit 4. Move to next phase (change next phase from ⏸️ to 🔄)

When Troubleshooting Takes Over

• Don't fight it - update SESSION.md to show "Debugging" stage
• Document the issue in "Current Issue" field
• When fixed, move back to "Verification" or "Implementation"

---

Integration with Planning

project-planning skill
        ↓
Generates IMPLEMENTATION_PHASES.md (the plan)
        ↓
Create SESSION.md (the tracker)
        ↓
Work through phases, updating SESSION.md
        ↓
Git checkpoints preserve state
        ↓
Resume from SESSION.md after context clear

Planning docs (in /docs): Reference material, rarely change SESSION.md (in root): Living document, updates constantly

---

Benefits

Token Efficiency

• ~500-800 tokens to resume from SESSION.md
• vs ~12,000 tokens to manually reconstruct state
• 85-93% token savings on resume

Context Safety

• Phases sized to fit in one session (2-4 hours)
• Clear checkpoints for mid-phase saves
• No loss of progress on context clear

Clarity

• Always know what to do next
• No "where was I?" moments
• Verification criteria prevent premature "done"

Flexibility

• Works across multiple sessions per phase
• Handles interruptions gracefully
• Supports debugging as normal part of flow

---

Production Validation

This protocol has been tested across:

• 27+ production skills
• Multiple multi-phase projects
• Various project sizes (4-20 phases)
• Different tech stacks (Cloudflare, Next.js, etc.)

Result: 100% successful resumes after context clear

---

Last Updated: 2025-10-28 Version: 1.0 Author: Jeremy Dawes | Jezweb

Git Checkpoint Commit Format

Use this structured format for all checkpoint commits during phased development.

---

Template

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused/Blocked]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)
- path/to/another.tsx (what changed)

Next: [Concrete next action with file path + line number]

---

Examples

Phase Complete

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)
- src/middleware/validate.ts (validation middleware)

Next: Phase 4 - Start building Task List UI component

Context Full Mid-Phase

checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

Blocked or Paused

checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89

Bug Fix During Verification

checkpoint: Phase 3 In Progress - Fixed validation bug

Phase: 3 - Tasks API
Status: In Progress (Verification stage)
Session: Fixed invalid data returning 500 instead of 400

Files Changed:
- src/middleware/validate.ts (added try-catch for Zod errors)

Next: Continue verification - test PATCH and DELETE endpoints

---

Guidelines

Status Values:

• Complete - Phase fully done, all verification passed
• In Progress - Active work, may include stage (Implementation/Verification/Debugging)
• Paused - Temporarily stopped, waiting for decision or external input
• Blocked - Cannot proceed due to blocker (note blocker in Session field)

Session Field:

• Focus on WHAT was accomplished, not HOW
• Be specific enough for future resume
• Include stage if not obvious (Verification, Debugging)

Files Changed:

• List significant files only (not config changes)
• Briefly note what changed in each file
• Use relative paths from project root

Next Field:

• MUST be concrete (file + line + action)
• NOT vague ("Continue working on...")
• Include decision points if relevant
• File paths should be specific

---

Creating Checkpoints

When to checkpoint:

• ✅ End of phase (status: Complete)
• ✅ Context getting full mid-phase (status: In Progress)
• ✅ Pausing for user decision (status: Paused)
• ✅ Hitting a blocker (status: Blocked)

How to create:

# Stage changes
git add path/to/changed/files

# Commit with checkpoint format
git commit -m "$(cat <<'EOF'
checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
EOF
)"

After checkpoint:

• Update SESSION.md with checkpoint commit hash
• Push to remote if desired
• Clear context if needed
• Resume from "Next" field when continuing

Session Handoff Protocol Snippet for Project CLAUDE.md

Copy this section into your project's CLAUDE.md file to enable session management for that project.

---

Session Handoff Protocol

Purpose: Track execution progress and manage context between sessions.

Quick Reference

Before ending any session: 1. Update SESSION.md with current state 2. Create git checkpoint commit (see format in SESSION.md notes) 3. Note concrete "Next Action"

When resuming: 1. Read SESSION.md 2. Check "Next Action" 3. Continue from that point

SESSION.md Location

File: SESSION.md (project root) Purpose: Navigation hub that references planning docs, tracks current progress Update: After significant progress (not every tiny change)

Status Icons

• ⏸️ = Not started (pending)
• 🔄 = In progress
• ✅ = Complete
• 🚫 = Blocked

Stages Within a Phase

• Implementation → Writing code for tasks
• Verification → Testing against verification criteria
• Debugging → Fixing issues found during verification

Update SESSION.md to reflect current stage.

---

For full protocol details, see `~/.claude/skills/project-session-management/`