Claude-executable plans have a specific format. This reference defines what makes a plan executable vs. vague. **Core principle:** A plan is Claude-executable when Claude can read PLAN.md and immediately start implementing without clarifying questions. If Claude has to guess or interpret - the task is too vague. Every task has four required fields: **files** - Exact paths created/modified - Good: `src/app/api/auth/login/route.ts` - Bad: "the auth files" **action** - Specific implementation with pitfalls to avoid - Good: "POST endpoint accepting {email, password}. Query User by email, compare with bcrypt. Return JWT in httpOnly cookie (15-min expiry). Use jose (not jsonwebtoken - CommonJS issues with Edge)." - Bad: "Add authentication" **verify** - Executable proof of completion - Good: `curl -X POST /api/auth/login` returns 200 with Set-Cookie header - Bad: "It works" **done** - Measurable acceptance criteria - Good: "Valid credentials → 200 + cookie. Invalid → 401." - Bad: "Authentication complete" **type="auto"** (default) - Claude executes autonomously ```xml Task 1: Create login endpoint src/app/api/auth/login/route.ts POST accepting {email, password}. bcrypt compare, JWT via jose, httpOnly cookie. curl returns 200 with Set-Cookie Valid → 200 + cookie. Invalid → 401. ``` **type="checkpoint:human-verify"** - Human confirms Claude's work ```xml Responsive dashboard at /dashboard 1. npm run dev 2. Visit localhost:3000/dashboard 3. Test mobile/tablet/desktop Type "approved" or describe issues ``` **type="checkpoint:decision"** - Human makes implementation choice ```xml Select auth provider Need user auth with different tradeoffs. SupabaseBuilt-in, freeEcosystem lock-in ClerkBest DXPaid after 10k Select: supabase or clerk ``` **type="checkpoint:human-action"** - Rare, only for NO API/CLI actions (email links, 2FA) **Golden rule:** If Claude CAN automate it, Claude MUST automate it. See `./checkpoints.md` for comprehensive checkpoint guidance. **Too vague:** ```xml Add authentication ??? Implement auth ??? Users can authenticate ``` Claude: "How? What type? What library? Where?" **Just right:** ```xml Create login endpoint with JWT src/app/api/auth/login/route.ts POST accepting {email, password}. Query User by email, bcrypt compare. On match: JWT via jose, httpOnly cookie (15-min). Return 200. Mismatch: 401. Use jose not jsonwebtoken (Edge compatibility). curl -X POST localhost:3000/api/auth/login -d '{"email":"test@test.com","password":"test123"}' returns 200 with Set-Cookie Valid → 200 + cookie. Invalid → 401. Missing fields → 400. ``` **Vague actions:** - "Set up infrastructure" - what infrastructure? - "Handle edge cases" - which ones? - "Add proper error handling" - what's proper? **Unverifiable completion:** - "It works correctly" - how to test? - "Code is clean" - subjective - "Tests pass" - which tests? do they exist? **Missing context:** - "Use standard approach" - which standard? - "Like the other endpoints" - Claude doesn't know your patterns Good task size: 15-60 minutes of Claude work. - Too small: "Add import for bcrypt" → combine with related task - Just right: "Create login endpoint with JWT" → focused, specific - Too big: "Implement full auth system" → split into multiple plans If phase has >3 tasks or spans multiple subsystems, split into multiple plans: `{phase}-{plan}-PLAN.md`