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.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdreferences/best-practices.mdreferences/session-handoff-protocol.mdrules/session-protocol.mdscripts/resume.shtemplates/CLAUDE-session-snippet.mdtemplates/SESSION.md.templatetemplates/checkpoint-commit-format.mdname: 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.
Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions.
project-planning generates IMPLEMENTATION_PHASES.mdPhases (IMPLEMENTATION_PHASES.md): Units of WORK (e.g., "Database Schema", "Auth API"). Have verification/exit criteria. May span multiple sessions.
Sessions (SESSION.md): Units of CONTEXT. Complete before clearing/compacting context. Can complete a phase, part of a phase, or multiple small phases.
Example: Phase 3 (Tasks API) → Session 1 (GET/POST) → Session 2 (PATCH/DELETE) → Session 3 (verify) ✅
Starting New Project:
project-planning creates IMPLEMENTATION_PHASES.md, offer: "Create SESSION.md to track progress?"Ending Session:
/wrap-session (updates SESSION.md, creates checkpoint commit, outputs summary)Resuming:
/continue-session (loads context, shows summary, continues from "Next Action")/wrap-session: Analyzes state → updates SESSION.md → updates related docs → creates checkpoint commit → outputs summary → optionally pushes
/continue-session: Loads SESSION.md + planning docs → shows git history + summary → displays verification criteria (if in Verification stage) → opens "Next Action" file → asks permission to continue
Purpose: Navigation hub referencing planning docs, tracking current progress Target: <200 lines in project root Update: After significant progress (not every change)
# 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`
Use these emoji status icons consistently:
Update SESSION.md with current stage and progress. Example:
**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)
**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts
✅ Collapse completed phases (2-3 lines), concrete "Next Action" (file+line+task), reference planning docs, checkpoint at phase end or when context full
❌ No code copying, no duplicating IMPLEMENTATION_PHASES.md, no vague actions, keep <200 lines
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]
Example (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)
Next: Phase 4 - Start building Task List UI component
Checkpoint Cycle: /wrap-session creates commit → gets hash → updates SESSION.md with hash. Therefore SESSION.md is always uncommitted when resuming (BY DESIGN).
Expected uncommitted files (no warning):
Warning triggers (unexpected):
/continue-session behavior:
Context full mid-phase: Update SESSION.md → checkpoint → clear context → read SESSION.md + planning docs → continue from "Next Action"
Phase complete: Check verification criteria → mark 🔄→✅ → checkpoint → move next phase ⏸️→🔄
Troubleshooting: Update to "Debugging" stage → document "Current Issue" → when fixed, return to "Verification" or "Implementation"
project-planning generates IMPLEMENTATION_PHASES.md (the plan) → project-session-management creates SESSION.md (the tracker) → work through phases → git checkpoints → resume from SESSION.md
Planning docs (/docs): Reference material, rarely change SESSION.md (root): Living document, updates constantly
After project-planning runs:
Offer: "Would you like me to create SESSION.md to track progress through these phases? (clear current phase, progress tracking, easy resume, git checkpoint format)"
Templates: SESSION.md.template, checkpoint-commit-format.md, CLAUDE-session-snippet.md
Scripts: resume.sh (show current state)
References: session-handoff-protocol.md, best-practices.md