project-session-management

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

---

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 ✅

```

---

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

---

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.

---

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

---

Completed: 2025-10-15 | Checkpoint: abc1234

Summary: Vite + React + Tailwind v4 + D1 binding

Completed: 2025-10-18 | Checkpoint: def5678

Summary: D1 schema + migrations + seed data

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

Spec: docs/IMPLEMENTATION_PHASES.md#phase-4

```

---

Use these emoji status icons consistently:

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

---

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.

---

✅ 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)

---

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

```

---

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)

```

---

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"

---

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

---

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)

1. ✅ Expand Phase 1 with task checklist from IMPLEMENTATION_PHASES.md
2. ✅ Set concrete "Next Action" for Phase 1 first task
3. ✅ 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

```

---

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

---

• 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

---

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.