diff --git a/get-shit-done/references/plan-format.md b/get-shit-done/references/plan-format.md
index 89c18eb2b..91d058344 100644
--- a/get-shit-done/references/plan-format.md
+++ b/get-shit-done/references/plan-format.md
@@ -1,127 +1,397 @@
-Claude-executable plans have a specific format. This reference defines what makes a plan executable vs. vague.
+Claude-executable plans have a specific format that enables Claude to implement without interpretation. 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.
+**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: [...]
+
+
+
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@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]
+
+
+
+
+ [how to indicate choice]
+
+
+
+
+[Overall phase checks]
+
+
+
+[Measurable completion]
+
+
+
+```
+
+
+
+
Every task has four required fields:
-**files** - Exact paths created/modified
-- Good: `src/app/api/auth/login/route.ts`
-- Bad: "the auth files"
+
+**What it is**: Exact file paths that will be created or modified.
-**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"
+**Good**: `src/app/api/auth/login/route.ts`, `prisma/schema.prisma`
+**Bad**: "the auth files", "relevant components"
-**verify** - Executable proof of completion
-- Good: `curl -X POST /api/auth/login` returns 200 with Set-Cookie header
-- Bad: "It works"
+Be specific. If you don't know the file path, figure it out first.
+
-**done** - Measurable acceptance criteria
-- Good: "Valid credentials → 200 + cookie. Invalid → 401."
-- Bad: "Authentication complete"
+
+**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:**
-**type="auto"** (default) - Claude executes autonomously
```xml
- Task 1: Create login endpoint
+ Task 3: Create login endpoint with JWTsrc/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.
+ 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.
```
-**type="checkpoint:human-verify"** - Human confirms Claude's work
+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 at /dashboard
- 1. npm run dev 2. Visit localhost:3000/dashboard 3. Test mobile/tablet/desktop
+ 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
```
-**type="checkpoint:decision"** - Human makes implementation choice
+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 auth provider
- Need user auth with different tradeoffs.
+ Select authentication provider
+ We need user authentication. Three approaches with different tradeoffs:
-
-
+
+
+
- Select: supabase or clerk
+ Select: supabase, clerk, or nextauth
```
-**type="checkpoint:human-action"** - Rare, only for NO API/CLI actions (email links, 2FA)
+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
+
+@.planning/PROJECT.md # Project vision
+@.planning/ROADMAP.md # Phase structure
+@.planning/phases/02-auth/DISCOVERY.md # Discovery results
+@src/lib/db.ts # Existing database setup
+@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
+
+```
+
+
+
+
+
-**Too vague:**
```xml
- Add authentication
+ Task 1: Add authentication???Implement auth???Users can authenticate
```
-Claude: "How? What type? What library? Where?"
-**Just right:**
+Claude: "How? What type? What library? Where?"
+
+
+
+
```xml
- Create login endpoint with JWT
+ Task 1: Create login endpoint with JWTsrc/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.
+ 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.
+
+
-**Vague actions:**
-- "Set up infrastructure" - what infrastructure?
-- "Handle edge cases" - which ones?
-- "Add proper error handling" - what's proper?
+- "Set up the infrastructure"
+- "Handle edge cases"
+- "Make it production-ready"
+- "Add proper error handling"
-**Unverifiable completion:**
-- "It works correctly" - how to test?
-- "Code is clean" - subjective
-- "Tests pass" - which tests? do they exist?
+These require Claude to decide WHAT to do. Specify it.
+
-**Missing context:**
-- "Use standard approach" - which standard?
-- "Like the other endpoints" - Claude doesn't know your patterns
+
+- "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 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
+**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 phase has >3 tasks or spans multiple subsystems, split into multiple plans: `{phase}-{plan}-PLAN.md`
+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.
+