Initial commit
This commit is contained in:
Zhongwei Li
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -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": [
|
||||
"./"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -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.
|
||||
481
SKILL.md
Normal file
481
SKILL.md
Normal file
@@ -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.
|
||||
69
plugin.lock.json
Normal file
69
plugin.lock.json
Normal file
@@ -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": []
|
||||
}
|
||||
}
|
||||
368
references/best-practices.md
Normal file
368
references/best-practices.md
Normal file
@@ -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
|
||||
318
references/session-handoff-protocol.md
Normal file
318
references/session-handoff-protocol.md
Normal file
@@ -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
|
||||
63
scripts/resume.sh
Executable file
63
scripts/resume.sh
Executable file
@@ -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"
|
||||
46
templates/CLAUDE-session-snippet.md
Normal file
46
templates/CLAUDE-session-snippet.md
Normal file
@@ -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/`**
|
||||
53
templates/SESSION.md.template
Normal file
53
templates/SESSION.md.template
Normal file
@@ -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
|
||||
152
templates/checkpoint-commit-format.md
Normal file
152
templates/checkpoint-commit-format.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user