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:

# 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:

# 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:

# 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

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

Quick Resume Instructions

Always include this section in context