zhongwei/gh-jezweb-claude-skills-skills-project-session-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:22 +08:00
commit 460d70599a
10 changed files with 1565 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

368
references/best-practices.md Normal file
View 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
View 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