Initial commit

templates/CLAUDE-session-snippet.md

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

templates/SESSION.md.template

@@ -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

templates/checkpoint-commit-format.md

@@ -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