Claude-executable plans have a specific format that enables Claude to implement without interpretation. This reference defines what makes a plan executable vs. vague. **Key insight:** PLAN.md IS the executable prompt. It contains everything Claude needs to execute the phase, including objective, context references, tasks, verification, success criteria, and output specification. A plan is Claude-executable when Claude can read the PLAN.md and immediately start implementing without asking clarifying questions. If Claude has to guess, interpret, or make assumptions - the task is too vague. Every PLAN.md follows this XML structure: ```markdown --- phase: XX-name type: execute domain: [optional] --- [What and why] Purpose: [...] Output: [...] Read file: .planning/PROJECT.md Read file: .planning/ROADMAP.md Read file: relevant/source/files.ts Task N: [Name] [paths] [what to do, what to avoid and WHY] [command/check] [criteria] [what Claude automated] [numbered verification steps] [how to continue - "approved" or describe issues] [what needs deciding] [why this matters] [Name][pros][cons] [Name][pros][cons] [how to indicate choice] [Overall phase checks] [Measurable completion]

[SUMMARY.md specification]

``` Every task has four required fields: **What it is**: Exact file paths that will be created or modified. **Good**: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma` **Bad**: "the auth files", "relevant components" Be specific. If you don't know the file path, figure it out first. **What it is**: Specific implementation instructions, including what to avoid and WHY. **Good**: "Create POST endpoint that accepts {email, password}, validates using bcrypt against User table, returns JWT in httpOnly cookie with 15-min expiry. Use jose library (not jsonwebtoken - CommonJS issues with Next.js Edge runtime)." **Bad**: "Add authentication", "Make login work" Include: technology choices, data structures, behavior details, pitfalls to avoid. **What it is**: How to prove the task is complete. **Good**: - `npm test` passes - `curl -X POST /api/auth/login` returns 200 with Set-Cookie header - Build completes without errors **Bad**: "It works", "Looks good", "User can log in" Must be executable - a command, a test, an observable behavior. **What it is**: Acceptance criteria - the measurable state of completion. **Good**: "Valid credentials return 200 + JWT cookie, invalid credentials return 401" **Bad**: "Authentication is complete" Should be testable without subjective judgment. Tasks have a `type` attribute that determines how they execute: **Default task type** - Claude executes autonomously. **Structure:** ```xml Task 3: Create login endpoint with JWT src/app/api/auth/login/route.ts POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header Valid credentials → 200 + cookie. Invalid → 401. ``` Use for: Everything Claude can do independently (code, tests, builds, file operations). **RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first. **Structure:** ```xml [Unavoidable manual step - email link, 2FA code] [What Claude already automated] [The ONE thing requiring human action] [What Claude can check afterward] [How to continue] ``` Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no API, 3D Secure payment flows. Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments. **Execution:** Claude automates everything with CLI/API, stops only for truly unavoidable manual steps. **Human must verify Claude's work** - Visual checks, UX testing. **Structure:** ```xml Responsive dashboard layout 1. Run: npm run dev 2. Visit: http://localhost:3000/dashboard 3. Desktop (>1024px): Verify sidebar left, content right 4. Tablet (768px): Verify sidebar collapses to hamburger 5. Mobile (375px): Verify single column, bottom nav 6. Check: No layout shift, no horizontal scroll Type "approved" or describe issues ``` Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing. **Execution:** Claude builds the feature, stops, provides testing instructions, waits for approval/feedback. **Human must make implementation choice** - Direction-setting decisions. **Structure:** ```xml Select authentication provider We need user authentication. Three approaches with different tradeoffs: Supabase Auth Built-in with Supabase, generous free tier Less customizable UI, tied to ecosystem Clerk Beautiful pre-built UI, best DX Paid after 10k MAU NextAuth.js Free, self-hosted, maximum control More setup, you manage security Select: supabase, clerk, or nextauth ``` Use for: Technology selection, architecture decisions, design choices, feature prioritization. **Execution:** Claude presents options with balanced pros/cons, waits for decision, proceeds with chosen direction. **When to use checkpoints:** - Visual/UX verification (after Claude builds) → `checkpoint:human-verify` - Implementation direction choice → `checkpoint:decision` - Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare) **When NOT to use checkpoints:** - Anything with CLI/API (Claude automates it) → `type="auto"` - Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI - Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API - File operations, tests, builds → `type="auto"` **Golden rule:** If Claude CAN automate it, Claude MUST automate it. See `./checkpoints.md` for comprehensive checkpoint guidance. Use @file references to load context for the prompt: ```markdown Read file: .planning/PROJECT.md # Project vision Read file: .planning/ROADMAP.md # Phase structure Read file: .planning/phases/02-auth/DISCOVERY.md # Discovery results Read file: src/lib/db.ts # Existing database setup Read file: src/types/user.ts # Existing type definitions ``` Reference files that Claude needs to understand before implementing. Overall phase verification (beyond individual task verification): ```markdown Before declaring phase complete: - [ ] `npm run build` succeeds without errors - [ ] `npm test` passes all tests - [ ] No TypeScript errors - [ ] Feature works end-to-end manually ``` Measurable criteria for phase completion: ```markdown - All tasks completed - All verification checks pass - No errors or warnings introduced - JWT auth flow works end-to-end - Protected routes redirect unauthenticated users ``` Specify the SUMMARY.md structure: ```markdown

After completion, create `.planning/phases/XX-name/SUMMARY.md`: # Phase X: Name Summary **[Substantive one-liner]** ## Accomplishments ## Files Created/Modified ## Decisions Made ## Issues Encountered ## Next Phase Readiness

``` ```xml Task 1: Add authentication ??? Implement auth ??? Users can authenticate ``` Claude: "How? What type? What library? Where?" ```xml Task 1: Create login endpoint with JWT src/app/api/auth/login/route.ts POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie (15-min expiry). Return 200. On mismatch, return 401. Use jose instead of jsonwebtoken (CommonJS issues with Edge). curl -X POST localhost:3000/api/auth/login -H "Content-Type: application/json" -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie header containing JWT Valid credentials → 200 + cookie. Invalid → 401. Missing fields → 400. ``` Claude can implement this immediately. Writing the actual code in the plan. Trust Claude to implement from clear instructions. - "Set up the infrastructure" - "Handle edge cases" - "Make it production-ready" - "Add proper error handling" These require Claude to decide WHAT to do. Specify it. - "It works correctly" - "User experience is good" - "Code is clean" - "Tests pass" (which tests? do they exist?) These require subjective judgment. Make it objective. - "Use the standard approach" - "Follow best practices" - "Like the other endpoints" Claude doesn't know your standards. Be explicit. Good task size: 15-60 minutes of Claude work. **Too small**: "Add import statement for bcrypt" (combine with related task) **Just right**: "Create login endpoint with JWT validation" (focused, specific) **Too big**: "Implement full authentication system" (split into multiple plans) If a task takes multiple sessions, break it down. If a task is trivial, combine with related tasks. **Note on scope:** If a phase has >3 tasks or spans multiple subsystems, split into multiple plans using the naming convention `{phase}-{plan}-PLAN.md`. See `./scope-estimation.md` for guidance.