commit 460d70599aed7adc36271793bc5326255863f99f
Author: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date:   Sun Nov 30 08:25:22 2025 +0800

    Initial commit

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..6a6214f
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "project-session-management",
+  "description": "Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions. Converts IMPLEMENTATION_PHASES.md into trackable session state with phase status, progress markers, and recovery points. Use when: starting projects after planning phase, resuming work after context clears, managing multi-phase implementations, or troubleshooting lost context, missing progress tracking, or unclear next steps.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Jeremy Dawes",
+    "email": "jeremy@jezweb.net"
+  },
+  "skills": [
+    "./"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b900fb0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# project-session-management
+
+Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions. Converts IMPLEMENTATION_PHASES.md into trackable session state with phase status, progress markers, and recovery points. Use when: starting projects after planning phase, resuming work after context clears, managing multi-phase implementations, or troubleshooting lost context, missing progress tracking, or unclear next steps.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..80ec0ff
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,481 @@
+---
+name: project-session-management
+description: |
+  Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions. Converts IMPLEMENTATION_PHASES.md into trackable session state with phase status, progress markers, and recovery points.
+
+  Use when: starting projects after planning phase, resuming work after context clears, managing multi-phase implementations, or troubleshooting lost context, missing progress tracking, or unclear next steps.
+license: MIT
+---
+
+# 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
+
+```markdown
+# 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:
+
+```markdown
+**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.
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..719dc8e
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:jezweb/claude-skills:skills/project-session-management",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "075abbf55cbde3a41ef90c3970b2a830b88101d0",
+    "treeHash": "28e58b563e929758d082cb4276e4b17d7e02b20e3b7a2bccbc22aa3e3205f18c",
+    "generatedAt": "2025-11-28T10:19:05.472139Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "project-session-management",
+    "description": "Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions. Converts IMPLEMENTATION_PHASES.md into trackable session state with phase status, progress markers, and recovery points. Use when: starting projects after planning phase, resuming work after context clears, managing multi-phase implementations, or troubleshooting lost context, missing progress tracking, or unclear next steps.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "fc185f83b442e4e5d6cb26067cc55522990f0603a2a96107cedbe802c4cc8da2"
+      },
+      {
+        "path": "SKILL.md",
+        "sha256": "ae2e595491cf04ac1b7e443b0857a94fb2bc1fe29587f8d9377fdeb3d5744afc"
+      },
+      {
+        "path": "references/session-handoff-protocol.md",
+        "sha256": "c1acdd331eaed2ef47fb27a53024ad3d6bd3c1c492d7907aa20f0f023acd3759"
+      },
+      {
+        "path": "references/best-practices.md",
+        "sha256": "cc063e3786b72541a1932c0efda66de177901a2fbc075e260fbec169d0d87921"
+      },
+      {
+        "path": "scripts/resume.sh",
+        "sha256": "2debe6b04f20b17f4feba690e965225d3fd67a8df154edafbec5212b43de4a83"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "ea8adc184853c146d639cfa166b1745a3f12a23e7eaac84353732ba6f201eb97"
+      },
+      {
+        "path": "templates/checkpoint-commit-format.md",
+        "sha256": "b7584ecb65536f398fd9ca46466496c8d348042e1ff77e3d71fac73a0a05c0ea"
+      },
+      {
+        "path": "templates/CLAUDE-session-snippet.md",
+        "sha256": "790136bacba4c88da635e2bc7b090e1f7d8db4cfb811217809b9a86598cac14b"
+      },
+      {
+        "path": "templates/SESSION.md.template",
+        "sha256": "e2f72fe0effb14c5c39ac242d9caaa2fc4c9fe9656178f66d5478e76220f6286"
+      }
+    ],
+    "dirSha256": "28e58b563e929758d082cb4276e4b17d7e02b20e3b7a2bccbc22aa3e3205f18c"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/references/best-practices.md b/references/best-practices.md
new file mode 100644
index 0000000..3f07e10
--- /dev/null
+++ b/references/best-practices.md
@@ -0,0 +1,368 @@
+# 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)
+
+```markdown
+**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"
+
+```markdown
+**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
+
+```markdown
+**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)
+
+```markdown
+**Next Action**: Continue working on API
+```
+- Which API endpoint?
+- Which file?
+- What specifically needs to be done?
+
+```markdown
+**Next Action**: Fix bugs
+```
+- Which bugs?
+- Where are they?
+- No concrete starting point
+
+```markdown
+**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**:
+```markdown
+## 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**:
+```markdown
+## 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**:
+```markdown
+## 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**:
+```markdown
+## 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
+```markdown
+## 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:
+
+```markdown
+# 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:
+
+```markdown
+## 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
diff --git a/references/session-handoff-protocol.md b/references/session-handoff-protocol.md
new file mode 100644
index 0000000..d32c45d
--- /dev/null
+++ b/references/session-handoff-protocol.md
@@ -0,0 +1,318 @@
+# 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
+
+```markdown
+# 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:
+
+```markdown
+**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
diff --git a/scripts/resume.sh b/scripts/resume.sh
new file mode 100755
index 0000000..c5374d4
--- /dev/null
+++ b/scripts/resume.sh
@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# resume.sh - Quickly show current project state from SESSION.md
+# Usage: ./scripts/resume.sh
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Current Project State ===${NC}\n"
+
+# Check if SESSION.md exists
+if [ ! -f "SESSION.md" ]; then
+    echo -e "${YELLOW}⚠️  SESSION.md not found in project root${NC}"
+    echo "Run this script from your project root directory"
+    echo "Or create SESSION.md first using the project-session-management skill"
+    exit 1
+fi
+
+# Show current phase
+echo -e "${GREEN}Current Phase:${NC}"
+grep -A 15 "## .*🔄" SESSION.md | head -20 || echo "No phase currently in progress"
+echo ""
+
+# Show last checkpoint
+echo -e "${GREEN}Last Checkpoint:${NC}"
+if git log --oneline --grep="checkpoint:" -1 --format="%H %s%n%b" 2>/dev/null | head -15; then
+    echo ""
+else
+    echo "No checkpoint commits found"
+    echo ""
+fi
+
+# Show next action
+echo -e "${GREEN}Next Action:${NC}"
+grep "**Next Action**" SESSION.md | tail -1 | sed 's/\*\*Next Action\*\*: //' || echo "No next action defined"
+echo ""
+
+# Show status summary
+echo -e "${GREEN}Status Summary:${NC}"
+echo -n "✅ Completed: "
+grep -c "✅" SESSION.md || echo "0"
+echo -n "🔄 In Progress: "
+grep -c "🔄" SESSION.md || echo "0"
+echo -n "⏸️  Pending: "
+grep -c "⏸️" SESSION.md || echo "0"
+echo -n "🚫 Blocked: "
+grep -c "🚫" SESSION.md || echo "0"
+echo ""
+
+# Show planning docs
+echo -e "${GREEN}Planning Docs:${NC}"
+grep "**Planning Docs**" SESSION.md | sed 's/\*\*Planning Docs\*\*: //' || echo "Not specified"
+echo ""
+
+echo -e "${BLUE}=== End of Summary ===${NC}"
+echo ""
+echo "💡 Tip: Read SESSION.md for full details"
+echo "💡 Tip: Use 'git log --grep=\"checkpoint:\"' to see checkpoint history"
diff --git a/templates/CLAUDE-session-snippet.md b/templates/CLAUDE-session-snippet.md
new file mode 100644
index 0000000..8b45106
--- /dev/null
+++ b/templates/CLAUDE-session-snippet.md
@@ -0,0 +1,46 @@
+# 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/`**
diff --git a/templates/SESSION.md.template b/templates/SESSION.md.template
new file mode 100644
index 0000000..0145546
--- /dev/null
+++ b/templates/SESSION.md.template
@@ -0,0 +1,53 @@
+# Session State
+
+**Current Phase**: Phase 1
+**Current Stage**: Implementation
+**Last Checkpoint**: [commit-hash] (YYYY-MM-DD)
+**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`
+
+---
+
+## Phase 1: [Name] 🔄
+**Type**: [Infrastructure/Database/API/UI/Integration/Testing]
+**Started**: YYYY-MM-DD
+**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-1`
+
+**Progress**:
+- [ ] Task 1
+- [ ] Task 2 ← **CURRENT**
+- [ ] Task 3
+- [ ] Verify all criteria (see IMPLEMENTATION_PHASES.md)
+
+**Next Action**: [Concrete action: file path + line number + what to do]
+
+**Key Files**:
+- `path/to/file1.ts`
+- `path/to/file2.tsx`
+
+**Known Issues**: None
+
+---
+
+## Phase 2: [Name] ⏸️
+**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-2`
+
+## Phase 3: [Name] ⏸️
+**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`
+
+## Phase 4: [Name] ⏸️
+**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
+
+---
+
+## Notes
+
+**Status Icons**:
+- ⏸️ = Not started (pending)
+- 🔄 = In progress
+- ✅ = Complete
+- 🚫 = Blocked
+
+**Stages**:
+- Implementation → Verification → Debugging
+
+**Checkpoint Reminder**: Create git checkpoint at end of phase OR when context is getting full
diff --git a/templates/checkpoint-commit-format.md b/templates/checkpoint-commit-format.md
new file mode 100644
index 0000000..4628860
--- /dev/null
+++ b/templates/checkpoint-commit-format.md
@@ -0,0 +1,152 @@
+# 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**:
+```bash
+# 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