Plan Stack

Overview

Plan Stack is a methodology for AI-assisted development structured around three phases: plan, implement, review. This cycle reduces rework, provides Claude Code with structured context, and creates a traceable decision history.

The Core Cycle

1. Plan — Document the intended implementation before writing code
2. Implement — Execute the plan using Claude Code as the implementation tool
3. Review — Verify the implementation against the plan's success criteria

This structure prevents scope creep, catches specification errors before they become code, and accelerates debugging by establishing a reference baseline.

Plan Document Structure

Create a plan file (e.g., docs/plans/20260509_add_auth.md) prior to implementation:

# Add User Authentication

## Goal
Users can log in with email/password and stay logged in.

## Approach
- Use JWT tokens stored in httpOnly cookies
- Add /api/auth/login and /api/auth/logout endpoints
- Create auth middleware for protected routes

## Files to Change
- src/api/auth.ts (new)
- src/middleware/auth.ts (new)
- src/api/user.ts (modify)

## Success Criteria
- Login returns token on valid credentials
- Protected routes reject requests without valid token
- Tests pass

Plan-Driven Sessions

Provide the plan at session initialization:

> I'm implementing user auth. Here's my plan:
> [paste plan]
> Let's start with the login endpoint.

With the full scope visible, Claude Code can make consistent architectural decisions across files and phases.

Version Control Integration

Link commits to their corresponding plan documents:

git commit -m "Add login endpoint

Implements: docs/plans/20260509_add_auth.md (step 1)"

This produces a traceable mapping from design decisions to their implementations in the commit history.