project-session-management

What this skill does

# 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 implem