context-persistence

# Context Persistence Skill ## Purpose Ensure Claude Code can resume work seamlessly after context resets, session interruptions, or long breaks by maintaining structured documentation of current work, decisions, and progress. ## When to Use This Skill Automatically activates when you mention: - Waypoint plans, waypoint planning - Resuming work, continuing work - Session survival, context reset - Task handoff, progress tracking - Long-running features or projects - Need to document current state ## The Problem: Context Resets **What happens during a context reset**: - ❌ All conversation history lost - ❌ Current task context forgotten - ❌ Decisions and rationale gone - ❌ Progress not tracked - ❌ Have to re-explain everything **With context persistence**: - ✅ Current task documented - ✅ Decisions and rationale preserved - ✅ Progress clearly tracked - ✅ Quick resume in < 1 minute - ✅ Seamless handoff to future sessions --- ## Three-File Structure The core pattern uses **three complementary files** in `plans/active/{task-name}/`: ### 1. `{task-name}-plan.md` - The Strategic Plan **Purpose**: High-level strategy and approach **Contains**: - Feature/task overview - Requirements and acceptance criteria - Architecture approach - Implementation phases - Dependencies and constraints - Risks and mitigations **Update frequency**: Rarely (only when approach changes) **Example**: ```markdown # Authentication Implementation Plan ## Overview Add JWT-based authentication to replace session cookies for mobile app support. ## Requirements - JWT tokens with refresh mechanism - Supabase Auth integration - Protected API routes - Mobile-friendly (stateless) ## Architecture - Auth middleware in Edge Functions - Token storage in httpOnly cookies (web) + AsyncStorage (mobile) - Row-Level Security policies for data access ## Implementation Phases 1. Supabase Auth setup 2. Edge Function auth middleware 3. Frontend auth hooks 4. RLS policies 5. Migration from existing auth ## Dependencies - Supabase setup complete - Database schema finalized ``` ### 2. `{task-name}-context.md` - Current State & Progress **Purpose**: Living document of current state, decisions, and progress **Contains**: - SESSION PROGRESS (updated frequently) - Key decisions made - Important discoveries - Current blockers - Files modified - Quick resume instructions **Update frequency**: After each significant change or decision **Example**: ```markdown # Authentication Implementation Context ## SESSION PROGRESS (2025-01-15 14:30) ### ✅ COMPLETED - [x] Supabase Auth configured - [x] Created auth middleware for Edge Functions - [x] Implemented login/signup pages - [x] Added auth context provider ### 🟡 IN PROGRESS - [ ] Implementing token refresh logic (CURRENT) - Working on: lib/supabase/auth.ts - Next: Handle token expiration gracefully ### ⏳ PENDING - [ ] Add RLS policies - [ ] Migrate existing users - [ ] Add mobile auth flow - [ ] Write auth tests ### 🎯 NEXT ACTION Continue implementing refreshToken() function in lib/supabase/auth.ts - Handle expired tokens - Refresh transparently - Redirect to login if refresh fails ## KEY DECISIONS ### Decision: JWT vs. Session Cookies (2025-01-12) **Chose**: JWT tokens **Rationale**: Need stateless auth for mobile apps **Impact**: Requires token refresh mechanism ### Decision: Supabase Auth vs. Custom (2025-01-13) **Chose**: Supabase Auth **Rationale**: Built-in RLS integration, handles token refresh **Impact**: Less custom code, tighter Supabase integration ## IMPORTANT DISCOVERIES ### Token Refresh Timing Discovered tokens expire after 1 hour by default. Need to: - Refresh proactively at 50 minutes - Handle edge case of offline user - Store refresh token securely ### RLS Row vs. Column Level Supabase RLS is row-level only, not column-level. For sensitive columns, need separate tables. ## CURRENT BLOCKERS None currently. Auth flow is straightforward with Supabase. ## FILES MODIFIED ### Created - lib/supabase/auth.ts (auth utilities) - app/(auth)/login/page.tsx - app/(auth)/signup/page.tsx - components/auth/auth-provider.tsx ### Modified - lib/supabase/client.ts (added auth hooks) - middleware.ts (added auth middleware) ## QUICK RESUME To continue this work: 1. Read this file (context.md) for current state 2. Check tasks.md for checklist 3. Refer to plan.md for overall strategy 4. Current file: lib/supabase/auth.ts 5. Next: Implement refreshToken() function 6. After that: Test token refresh flow ``` ### 3. `{task-name}-tasks.md` - Actionable Checklist **Purpose**: Granular, actionable tasks with acceptance criteria **Contains**: - Detailed task breakdown - Acceptance criteria for each task - Dependencies between tasks - Task status (pending/in-progress/complete) **Update frequency**: Daily or after completing tasks **Example**: ```markdown # Authentication Implementation Tasks ## Phase 1: Supabase Setup ✅ - [x] Create Supabase project (Acceptance: Project created, credentials stored) - [x] Enable Email auth provider (Acceptance: Can sign up via email) - [x] Configure redirect URLs (Acceptance: Auth callbacks work locally + prod) - [x] Add auth schema to database (Acceptance: Users table exists) ## Phase 2: Backend Auth 🟡 - [x] Create auth utilities (Acceptance: getUser(), signIn(), signUp() functions work) - [ ] Implement token refresh **(IN PROGRESS)** - Acceptance: Tokens refresh automatically before expiry - Dependencies: Auth utilities complete - Notes: Need to handle offline case - [ ] Add auth middleware to Edge Functions - Acceptance: Protected routes return 401 if not authenticated - Dependencies: Token refresh working - [ ] Create auth helper for server components - Acceptance: Can check auth in Server Components ## Phase 3: Frontend Auth ⏳ - [x] Create auth context provider (Acceptance: Auth state available app-wide) - [x] Build login page (Acceptance: Can log in with email/password) - [x] Build signup page (Acceptance: Can create account) - [ ] Add protected route wrapper - Acceptance: Redirects to login if not authenticated - Dependencies: Auth context complete - [ ] Add loading states - Acceptance: Shows loading spinner during auth checks ## Phase 4: Security 🔒 - [ ] Add RLS policies - Acceptance: Users can only access their own data - Files: supabase/migrations/xxx_rls_policies.sql - [ ] Test auth edge cases - Expired tokens - Invalid tokens - Network failures - Concurrent sessions ## Phase 5: Migration 📦 - [ ] Create migration script for existing users - [ ] Test migration locally - [ ] Schedule maintenance window - [ ] Execute migration in production - [ ] Verify all users migrated successfully ``` --- ## SESSION PROGRESS Pattern The **SESSION PROGRESS** section is the most important part of context.md: ### Structure ```markdown ## SESSION PROGRESS (2025-01-15 14:30) ### ✅ COMPLETED [What's done - be specific] ### 🟡 IN PROGRESS [What you're working on RIGHT NOW] ### ⏳ PENDING [What's coming next] ### 🚫 BLOCKED [What's preventing progress - if any] ### 🎯 NEXT ACTION [Specific next step with file + function] ``` ### Best Practices **DO ✅**: - Update after each significant milestone - Be specific about current file/function - Include "NEXT ACTION" for easy resume - Mark completed items immediately - Note blockers as they arise **DON'T ❌**: - Leave stale progress (update regularly) - Be vague ("working on auth" → "implementing refreshToken() in auth.ts") - Forget to mark completed items - Skip the NEXT ACTION (critical for resume) ### Update Frequency | Event | Update SESSION PROGRESS? | |-------|-------------------------| | Completed a full task | ✅ Yes | | Significant decision made | ✅ Yes | | Discovered blocker | ✅ Yes | | Changed approach | ✅ Yes | | Switching to different task | ✅ Yes | | Minor code change | ❌ No | | Formatting/cleanup | ❌ No | | Reading code | ❌ No | --- ## Quick Resume Instructions Always include this section in context.md: ```markdown ## QUICK RESUME To continue this work: 1. **Read**: This file (context.md) for current state 2. **Check**: tasks.md for detailed checklist 3. **Reference**: plan.md for overall strategy 4. **Current file**: [exact file path] 5. **Current function**: [exact function/component name] 6. **Next step**: [specific action to take] 7. **After that**: [following step] 8. **Expected time**: [estimate for next step] ### If Context is Stale (> 3 days old) 1. Verify current code state matches context 2. Check for changes by others (git log) 3. Update context.md before proceeding ``` --- ## When to Create Waypoint Plans ### Always Create For ✅ Features taking > 2 hours ✅ Multi-session work ✅ Complex implementations ✅ Work likely to be interrupted ✅ Team handoffs ✅ Refactorings affecting multiple files ### Optional For ⚠️ Simple bug fixes (< 30 min) ⚠️ Documentation updates ⚠️ Minor UI tweaks ⚠️ Configuration changes ### Never Create For ❌ Trivial changes ❌ Automated tasks ❌ One-liner fixes **Rule of Thumb**: If you might forget context after lunch, create a waypoint plan. --- ## Directory Structure ``` plans/ ├── active/ # Current work │ ├── auth-implementation/ │ │ ├── auth-implementation-plan.md │ │ ├── auth-implementation-context.md │ │ └── auth-implementation-tasks.md │ ├── payments-integration/ │ │ ├── payments-integration-plan.md │ │ ├── payments-integration-context.md │ │ └── payments-integration-tasks.md │ └── README.md # Active work index ├── archived/ # Completed work │ └── [moved completed tasks] └── templates/ # Templates for new tasks ├── template-plan.md ├── template-context.md └── template-tasks.md ``` --- ## File Naming Convention **Pattern**: `{task-slug}-{type}.md` **Examples**: - `auth-implementation-plan.md` - `auth-implementation-context.md` - `auth-implementation-tasks.md` **task-slug**: - Lowercase - Hyphen-separated - Descriptive (not generic) - Max 3-4 words **Good slugs**: - `auth-implementation` - `stripe-payments` - `user-dashboard` **Bad slugs**: - `feature` (too generic) - `task-123` (meaningless) - `implement_new_authentication_system_with_jwt` (too long) --- ## Commands for Claude Code Waypoint Plugin Provide these commands: ```bash # Create new waypoint plan /create-plan [task-name] # Creates 3-file structure # Update existing waypoint /update-context # Updates SESSION PROGRESS # Resume work /resume # Shows latest context + next action /resume [task-name] # Resume specific task # Archive completed work /archive [task-name] # Moves to archived/ ``` --- ## Integration with Commands ### `/create-plan` Command Creates the three-file structure automatically: ```bash /create-plan auth-implementation Creates: - plans/active/auth-implementation/auth-implementation-plan.md - plans/active/auth-implementation/auth-implementation-context.md - plans/active/auth-implementation/auth-implementation-tasks.md ``` See the `/create-plan` command documentation for details. ### `/update-context` Command Updates SESSION PROGRESS section with prompts: ```bash /update-context Prompts: - What did you complete? - What are you currently working on? - What's the specific file/function? - What's the next action? - Any blockers? ``` ### `/resume` Command Displays context for quick resume: ```bash /resume Output: 📂 Resuming: auth-implementation 📋 CONTEXT SUMMARY: - Last updated: 2 hours ago - In progress: Implementing token refresh ✅ COMPLETED (3/8): ... 🟡 IN PROGRESS (1/8): ... ➡️ NEXT ACTION: Implement refreshToken() in lib/supabase/auth.ts ``` --- ## Best Practices ### DO ✅ 1. **Update context after significant changes** (not after every line) 2. **Be specific in NEXT ACTION** (file + function + what to do) 3. **Mark tasks complete immediately** (don't batch them) 4. **Document decisions with rationale** (the "why" not just "what") 5. **Include code snippets in context** (for complex logic) 6. **Add timestamps to SESSION PROGRESS** (know when it was updated) 7. **Archive completed tasks** (keep active/ directory clean) ### DON'T ❌ 1. **Don't let context get stale** (> 3 days without update = stale) 2. **Don't be vague** ("working on auth" tells you nothing) 3. **Don't skip NEXT ACTION** (critical for resuming) 4. **Don't forget to update after decisions** (decisions are context!) 5. **Don't duplicate info** (plan vs. context vs. tasks have different purposes) 6. **Don't commit sensitive info** (credentials, API keys) --- ## Handling Context Staleness ### Detecting Staleness Context is stale if: - Last updated > 3 days ago - Code changed significantly since update - Blocker was noted but not resolved - IN PROGRESS task completed but not marked ### Refreshing Stale Context ```markdown ## Context Refresh Checklist Before resuming stale context: - [ ] Read current code in "current file" - [ ] Check git log for changes since last update - [ ] Verify IN PROGRESS task is actually in progress - [ ] Update completed tasks - [ ] Remove resolved blockers - [ ] Update NEXT ACTION if changed - [ ] Add note: "Context refreshed on [date]" ``` --- ## Example: Complete Context Lifecycle ### Day 1: Create Waypoint Plan ```bash User: "Let's implement JWT authentication" Claude: "I'll create a waypoint plan for this task" /create-plan auth-implementation Creates 3 files with: - Plan: Overall strategy - Context: Empty SESSION PROGRESS - Tasks: Broken down checklist ``` ### Day 1: Work & Update ```markdown After 2 hours of work: ## SESSION PROGRESS (2025-01-15 14:30) ### ✅ COMPLETED - [x] Supabase Auth configured - [x] Created auth utilities ### 🟡 IN PROGRESS - [ ] Implementing login page