project-session-management

# Project Session Management Skill

Track progress across work sessions using SESSION.md with git checkpoints and concrete next actions.

---

## When to Use

- Starting projects after `project-planning` generates IMPLEMENTATION_PHASES.md
- Resuming work after context clears
- Mid-phase checkpoints when context is full
- Phase transitions
- Tracking Implementation → Verification → Debugging cycle

---

## Phases vs Sessions

**Phases** (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) ✅

---

## Workflow

**Starting New Project**:
1. After `project-planning` creates IMPLEMENTATION_PHASES.md, offer: "Create SESSION.md to track progress?"
2. Generate SESSION.md from phases, set Phase 1 as 🔄 (in progress), set concrete "Next Action"

**Ending Session**:
- **Automated**: `/wrap-session` (updates SESSION.md, creates checkpoint commit, outputs summary)
- **Manual**: Update SESSION.md → git checkpoint → set concrete "Next Action"

**Resuming**:
- **Automated**: `/continue-session` (loads context, shows summary, continues from "Next Action")
- **Manual**: Read SESSION.md → check "Next Action" → continue

---

## Automation Commands

**`/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

---

## SESSION.md Structure

**Purpose**: Navigation hub referencing planning docs, tracking current progress
**Target**: <200 lines in project root