Skip to content

PHILOSOPHY.md

Latest commit

 

History

History
467 lines (328 loc) · 12.7 KB

PHILOSOPHY.md

File metadata and controls

467 lines (328 loc) · 12.7 KB

Claude Code Waypoint Plugin - Philosophy

Understanding the principles behind the Claude Code Waypoint Plugin and why intentional memory management is the foundation of effective AI development.

The Core Problem

Context is Ephemeral

AI assistants like Claude have a fundamental limitation: context resets. When you hit token limits or start a new session, all conversational context is lost.

This causes:

  • Repeated explanations of preferences
  • Loss of architectural decisions and rationale
  • Inability to resume complex work
  • No learning from corrections
  • Starting from scratch every session

The Traditional "Solution" Doesn't Work

Most developers try to solve this with:

  1. README files - Static, rarely updated, miss decisions and rationale
  2. Code comments - Too granular, don't capture high-level context
  3. Re-explaining - Time-consuming, frustrating, error-prone
  4. External docs - Separate from codebase, get out of sync

None of these survive context resets or enable true AI memory.

Waypoints: The Memory Anchor

What Are Waypoints?

Waypoints are persistent memory anchors stored in your plans/ directory that survive Claude Code context resets. They follow a three-file structure:

  1. plan.md - Strategic plan (rarely changes, the "what and why")
  2. context.md - Current state with SESSION PROGRESS tracking (updated frequently)
  3. tasks.md - Actionable checklist (updated daily)

Why this metaphor? A waypoint is a marked location on a journey. Just as travelers use waypoints to navigate long routes, developers use waypoint plans to navigate complex work across multiple AI sessions.

The Waypoint Advantage

Before Waypoints:

  • Context reset loses all progress
  • Must re-explain from scratch
  • Work is interrupted, momentum lost
  • 20-30% of time wasted on re-context

With Waypoints:

  • Run /create-plan [task] → Creates three-file structure
  • Work on the task, update context.md with SESSION PROGRESS
  • Context reset happens? Run /resume [task] → Instant recovery
  • No re-explaining, no lost progress
  • Work survives session resets automatically

Our Approach: Intentional Memory Management

Principle 1: Be Selective

Not everything deserves memory.

Track signal, not noise:

  • ✅ User explicitly states preference ("always use X")
  • ✅ User corrects same pattern 2+ times (learning opportunity)
  • ✅ Important architectural decisions
  • ✅ Project-specific conventions
  • ❌ One-time experiments
  • ❌ Information already in codebase
  • ❌ Generic best practices

Why this works: AI loads only relevant context, not a dump of everything.

Principle 2: Be Transparent

Users must know what's stored.

  • Store in visible location (.claude/memory/)
  • Use human-readable format (JSON with comments)
  • Provide commands to view/clear memory
  • Log when memory is created/updated
  • Never surprise the user

Why this works: Trust. Users control what AI remembers.

Principle 3: Be Intentional

Only capture what adds value.

Ask: "Would rediscovering this cost significant time?"

  • Preferences that save time ✅
  • Decisions that provide context ✅
  • Patterns that prevent mistakes ✅
  • Hard-to-rediscover knowledge ✅
  • Routine information ❌

Why this works: High signal-to-noise ratio = useful memory.

Waypoint integration: The three-file structure makes intention explicit:

  • plan.md captures decisions and rationale (the "why")
  • context.md captures current understanding and next steps
  • tasks.md tracks what needs doing
  • All stored in plans/ directory, visible and searchable

Principle 4: Be Respectful

Never store sensitive data without explicit consent.

  • ❌ API keys, tokens, credentials
  • ❌ Personal information
  • ❌ Business-sensitive logic
  • ✅ Preferences, patterns, conventions
  • ✅ Architecture decisions, rationale

Why this works: Security and privacy first.

Auto-Activation: A Critical Enabler

Why Auto-Activation Matters

Auto-activation is the critical feature that makes memory management work:

Without auto-activation:

  • Users must manually select skills
  • Context management feels like extra work
  • Memory systems feel optional
  • Friction prevents consistent use

With auto-activation:

  • Skills suggest themselves based on context
  • Users never have to remember "which skill to use"
  • Memory management happens naturally
  • Low friction, high consistency

How Auto-Activation Works

The skill-activation-prompt hook:

  1. Analyzes your prompt (keywords, intent)
  2. Checks files you're editing (path patterns)
  3. Reads file content (code patterns)
  4. Suggests relevant skills automatically
  5. You approve with one click

Result: Right knowledge at the right time, every time.

The Three-Pillar System

Pillar 1: Skills (Knowledge Bases)

Problem: AI needs domain-specific knowledge to help effectively.

Solution: Self-contained skill documents that:

  • Auto-activate based on context (the enabler)
  • Provide consistent guidance
  • Can be updated independently
  • Stay under context limits (500-line rule)

Example: When you edit a React file, frontend-dev-guidelines activates automatically with Next.js + React 19 best practices.

Why this works: Right knowledge, right time, enabled by auto-activation.

Pillar 2: Agents (Specialized Tasks)

Problem: Complex tasks require specialized, autonomous workflows.

Solution: Agents that:

  • Handle multi-step processes
  • Make decisions independently
  • Generate comprehensive outputs
  • Can be invoked on demand

Example: scaffold-customizer agent detects your tech stack and customizes all skills automatically.

Why this works: Automation of complex, repetitive expert work.

Pillar 3: Commands (Quick Actions)

Problem: Common operations shouldn't require full explanations.

Solution: Slash commands that:

  • Execute with one command
  • Have clear, consistent behavior
  • Can be chained together
  • Are discoverable

Example: /create-plan auth-implementation → instant three-file waypoint plan structure.

Why this works: Efficiency. Common operations become instant.

Waypoint Plans: The Three-File Structure

How Waypoints Enable Context Persistence

Problem: How to resume work seamlessly after context reset?

Solution: Three complementary files in plans/active/[task-name]/:

  1. plan.md - Strategic plan (rarely changes)

    • The "what and why"
    • Overall approach and architecture
    • Alternatives considered
    • Risks and mitigations

  2. context.md - Current state (updated frequently)

    • SESSION PROGRESS tracking (with timestamps)
    • Key decisions with rationale
    • Important discoveries
    • Files modified
    • NEXT ACTION for resume

  3. tasks.md - Actionable checklist (updated daily)

    • Granular tasks with acceptance criteria
    • Dependencies between tasks
    • Progress tracking

Why this works:

  • Different update cadences (plan rarely, context frequently, tasks daily)
  • Quick resume: Read context.md → know exactly where you left off
  • Survives context resets: All state persisted in files
  • < 1 minute to resume work

SESSION PROGRESS: The Secret Sauce

The SESSION PROGRESS section in context.md is critical:

## SESSION PROGRESS (2025-01-15 14:30)

### ✅ COMPLETED
[Specific completed tasks with file names]

### 🟡 IN PROGRESS
[Exact file and function being worked on]

### ⏳ PENDING
[What's coming next]

### 🎯 NEXT ACTION
[VERY specific: file + function + action]

Why this works:

  • Timestamp shows freshness
  • Completed tasks show progress
  • IN PROGRESS shows exact current state
  • NEXT ACTION enables instant resume
  • No ambiguity

Plan-Approval Workflow

User Control Over AI Actions

Problem: AI sometimes jumps to implementation before user is ready.

Solution: Explicit approval workflow:

  1. Generate Plan - AI creates detailed proposal
  2. Wait for Approval - User reviews (approve/modify/reject)
  3. Execute or Revise - Only proceed after explicit "approve"
  4. Learn - Store decision for future reference

Why this works:

  • User maintains control
  • Prevents costly mistakes
  • Captures decision rationale
  • Builds trust over time

When to Require Approval

Always:

  • Database schema changes
  • Breaking API changes
  • File deletions
  • Architecture refactors

Sometimes:

  • Complex features (> 5 files)
  • Performance optimizations

Never:

  • Bug fixes (< 10 lines)
  • Documentation updates
  • Minor UI tweaks

Why this works: Right amount of control without slowing down simple tasks.

Learning from Corrections

The Correction Counter Pattern

How it works:

  1. First correction: Note it, don't act yet
  2. Second correction (same pattern): Mark as learned preference
  3. Auto-apply: Use this preference going forward
  4. User can reset: With /clear-memory [preference-name]

Example:

User: "Use named imports, not default"  [Count: 1]
Claude: ✓ Fixed

[Later...]
User: "Again, use named imports"  [Count: 2]
Claude: ✓ Fixed
       📚 Learned preference: Always use named imports

[Future]
Claude automatically uses named imports

Why this works:

  • Learns from behavior, not just explicit statements
  • Threshold (2 corrections) filters noise
  • User stays in control (can clear preference)
  • Gets better over time

Opinionated Scaffolds

Why Opinionated?

Problem: Generic examples don't help with real decisions.

Solution: Production-tested, opinionated tech stack:

Backend:

  • Supabase (not Firebase or AWS)
  • Edge Functions (not Lambda)
  • Resend (not SendGrid)
  • Stripe (not PayPal)

Frontend:

  • Next.js 14+ (not Create React App)
  • React 19 (latest)
  • shadcn/ui (not MUI or Chakra)
  • Tailwind CSS (not styled-components)

Why this works:

  • Decisions already made
  • Patterns proven in production
  • Conflicts resolved
  • Can still customize via scaffold-customizer

Not Using Our Stack?

No problem. The patterns work with any stack:

  1. Run scaffold-customizer agent
  2. It detects your stack
  3. Creates customization plan
  4. Replaces placeholders
  5. Verifies changes

Example: Express → NestJS, React Router → TanStack Router, etc.

Why this works: Patterns are universal, implementations are specific.

The 500-Line Rule

Why 500 Lines?

Problem: Large skills hit context limits and become unwieldy.

Solution: Modular structure:

skill-name/
  SKILL.md              # <500 lines: overview + navigation
  resources/
    topic-1.md          # <500 lines: deep dive
    topic-2.md          # <500 lines: deep dive

Progressive disclosure:

  1. Claude loads SKILL.md first
  2. Gets high-level overview
  3. Loads resources only when needed
  4. Each resource stays under context budget

Why this works:

  • Fits Claude's context window
  • Fast loading (small main file)
  • Comprehensive (resources have depth)
  • Maintainable (modular updates)

Memory Storage Philosophy

What Goes in Memory vs. Code

In Memory (.claude/memory/):

  • Decision rationale (the "why")
  • User preferences not in code
  • Correction patterns
  • Project-specific knowledge

In Code/Config:

  • Linting rules (ESLint, Prettier)
  • Type definitions
  • Constants and configuration
  • Architecture (visible in structure)

Rule: If it can be in code, put it in code. Memory captures what code can't.

Why this works: Single source of truth where possible, memory for context code can't capture.

Trust Through Transparency

Visible, Readable, Controllable

Everything stored is:

  • Visible: .claude/memory/ in project
  • Readable: Human-readable JSON
  • Controllable: /show-memory, /clear-memory commands
  • Documented: User knows what's stored

Never Surprise the User

  • Notify when learning preference: "📚 Learned preference..."
  • Show what's being stored
  • Provide way to clear memory
  • Don't persist silently

Why this works: Trust is earned through transparency and control.

Why This Matters

Traditional Development Workflow

1. Explain context to AI
2. AI helps with task
3. Context reset
4. Re-explain everything
5. Repeat...

Time wasted: 20-30% on re-explaining

With Intentional Memory Management

1. Explain context once
2. Context persists in memory
3. AI learns from corrections
4. Work resumes instantly after reset
5. Gets better over time

Time saved: 20-30% reclaimed for actual work

The Compounding Effect

Week 1: Setup and initial use Week 2: AI learns your preferences Week 3: Fewer corrections needed Week 4: AI anticipates your patterns Month 2: Context survival feels natural Month 3: Can't imagine working without it

This is not just a plugin. It's a new way of working with AI.

Built for developers who value memory, context, and intentional AI collaboration