: Specific implementation instructions, including what to avoid and WHY.
Good: "Create POST endpoint accepting {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 Edge runtime)."
Bad: "Add authentication", "Make login work"
: How to prove the task is complete.
Good: npm test passes, curl -X POST /api/auth/login returns 200 with Set-Cookie header
Bad: "It works", "Looks good"
: Acceptance criteria - measurable state of completion.
Automation-first rule: If Claude CAN do it via CLI/API, Claude MUST do it. Checkpoints are for verification AFTER automation, not for manual work.
Task Sizing
Each task should take Claude 15-60 minutes to execute.
Duration
Action
< 15 min
Too small — combine with related task
15-60 min
Right size — single focused unit of work
> 60 min
Too large — split into smaller tasks
Signals a task is too large:
Touches more than 3-5 files
Has multiple distinct "chunks" of work
You'd naturally take a break partway through
The section is more than a paragraph
Signals tasks should be combined:
One task just sets up for the next
Separate tasks touch the same file
Neither task is meaningful alone
Specificity Examples
Tasks must be specific enough for clean execution. Compare:
TOO VAGUE
JUST RIGHT
"Add authentication"
"Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh"
"Create the API"
"Create POST /api/projects endpoint accepting {name, description}, validates name length 3-50 chars, returns 201 with project object"
"Style the dashboard"
"Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons"
"Handle errors"
"Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client"
"Set up the database"
"Add User and Project models to schema.prisma with UUID ids, email unique constraint, createdAt/updatedAt timestamps, run prisma db push"
The test: Could a different Claude instance execute this task without asking clarifying questions? If not, add specificity.
TDD Detection Heuristic
For each potential task, evaluate TDD fit:
Heuristic: Can you write expect(fn(input)).toBe(output) before writing fn?
Yes: Create a dedicated TDD plan for this feature
No: Standard task in standard plan
TDD candidates (create dedicated TDD plans):
Business logic with defined inputs/outputs
API endpoints with request/response contracts
Data transformations, parsing, formatting
Validation rules and constraints
Algorithms with testable behavior
State machines and workflows
Standard tasks (remain in standard plans):
UI layout, styling, visual components
Configuration changes
Glue code connecting existing components
One-off scripts and migrations
Simple CRUD with no business logic
Why TDD gets its own plan: TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), consuming 40-50% context for a single feature. Embedding in multi-task plans degrades quality.
User Setup Detection
For tasks involving external services, identify human-required configuration:
External service indicators:
New SDK: stripe, @sendgrid/mail, twilio, openai, @supabase/supabase-js
Webhook handlers: Files in **/webhooks/**
OAuth integration: Social login, third-party auth
API keys: Code referencing process.env.SERVICE_* patterns
For each external service, determine:
Env vars needed - What secrets must be retrieved from dashboards?
Account setup - Does user need to create an account?
Dashboard config - What must be configured in external UI?
Record in user_setup frontmatter. Only include what Claude literally cannot do (account creation, secret retrieval, dashboard config).
Important: User setup info goes in frontmatter ONLY. Do NOT surface it in your planning output or show setup tables to users. The execute-plan workflow handles presenting this at the right time (after automation completes).
Dependency Graph
Building the Dependency Graph
For each task identified, record:
needs: What must exist before this task runs (files, types, prior task outputs)
creates: What this task produces (files, types, exports)
has_checkpoint: Does this task require user interaction?
Dependency Graph Construction
Example with 6 tasks:
Task A (User model): needs nothing, creates src/models/user.ts
Task B (Product model): needs nothing, creates src/models/product.ts
Task C (User API): needs Task A, creates src/api/users.ts
Task D (Product API): needs Task B, creates src/api/products.ts
Task E (Dashboard): needs Task C + D, creates src/components/Dashboard.tsx
Task F (Verify UI): checkpoint:human-verify, needs Task E
Graph:
A --> C --\
--> E --> F
B --> D --/
Wave analysis:
Wave 1: A, B (independent roots)
Wave 2: C, D (depend only on Wave 1)
Wave 3: E (depends on Wave 2)
Wave 4: F (checkpoint, depends on Wave 3)
Vertical Slices vs Horizontal Layers
Vertical slices (PREFER):
Plan 01: User feature (model + API + UI)
Plan 02: Product feature (model + API + UI)
Plan 03: Order feature (model + API + UI)
Result: All three can run in parallel (Wave 1)
Horizontal layers (AVOID):
Plan 01: Create User model, Product model, Order model
Plan 02: Create User API, Product API, Order API
Plan 03: Create User UI, Product UI, Order UI
Comprehensive "add config file" phase = 1 plan (because that's all it is)
Don't pad small work to hit a number. Don't compress complex work to look efficient.
Goal-Backward Methodology
The Process
Forward planning asks: "What should we build?"
Goal-backward planning asks: "What must be TRUE for the goal to be achieved?"
Forward planning produces tasks. Goal-backward planning produces requirements that tasks must satisfy.
Step 1: State the Goal
Take the phase goal from ROADMAP.md. This is the outcome, not the work.
Good: "Working chat interface" (outcome)
Bad: "Build chat components" (task)
If the roadmap goal is task-shaped, reframe it as outcome-shaped.
Step 2: Derive Observable Truths
Ask: "What must be TRUE for this goal to be achieved?"
List 3-7 truths from the USER's perspective. These are observable behaviors.
For "working chat interface":
User can see existing messages
User can type a new message
User can send the message
Sent message appears in the list
Messages persist across page refresh
Test: Each truth should be verifiable by a human using the application.
Step 3: Derive Required Artifacts
For each truth, ask: "What must EXIST for this to be true?"
"User can see existing messages" requires:
Message list component (renders Message[])
Messages state (loaded from somewhere)
API route or data source (provides messages)
Message type definition (shapes the data)
Test: Each artifact should be a specific file or database object.
Step 4: Derive Required Wiring
For each artifact, ask: "What must be CONNECTED for this artifact to function?"
Message list component wiring:
Imports Message type (not using any)
Receives messages prop or fetches from API
Maps over messages to render (not hardcoded)
Handles empty state (not just crashes)
Step 5: Identify Key Links
Ask: "Where is this most likely to break?"
Key links are critical connections that, if missing, cause cascading failures.
For chat interface:
Input onSubmit → API call (if broken: typing works but sending doesn't)
API save → database (if broken: appears to send but doesn't persist)
Component → real data (if broken: shows placeholder, not messages)
Plan Format
PLAN.md Structure
---
phase: XX-name
plan: NN
type: execute
wave: N # Execution wave (1, 2, 3...)
depends_on: [] # Plan IDs this plan requires
files_modified: [] # Files this plan touches
autonomous: true # false if plan has checkpoints
user_setup: [] # Human-required setup (omit if empty)
must_haves:
truths: [] # Observable behaviors
artifacts: [] # Files that must exist
key_links: [] # Critical connections
---
<objective>
[What this plan accomplishes]
Purpose: [Why this matters for the project]
Output: [What artifacts will be created]
</objective><execution_context>
@./.claude/get-shit-done/workflows/execute-plan.md
@./.claude/get-shit-done/templates/summary.md
</execution_context><context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Only reference prior plan SUMMARYs if genuinely needed
@path/to/relevant/source.ts
</context><tasks><tasktype="auto"><name>Task 1: [Action-oriented name]</name><files>path/to/file.ext</files><action>[Specific implementation]</action><>[Command or check]
[Acceptance criteria]
[Overall phase checks]
[Measurable completion]
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
Frontmatter Fields
Field
Required
Purpose
phase
Yes
Phase identifier (e.g., 01-foundation)
plan
Yes
Plan number within phase
type
Yes
execute for standard, tdd for TDD plans
wave
Yes
Execution wave number (1, 2, 3...)
depends_on
Yes
Array of plan IDs this plan requires
files_modified
Yes
Files this plan touches
autonomous
Yes
true if no checkpoints, false if has checkpoints
user_setup
No
Human-required setup items
must_haves
Yes
Goal-backward verification criteria
Wave is pre-computed: Wave numbers are assigned during planning. Execute-phase reads wave directly from frontmatter and groups plans by wave number.
Context Section Rules
Only include prior plan SUMMARY references if genuinely needed:
This plan uses types/exports from prior plan
Prior plan made decision that affects this plan
Anti-pattern: Reflexive chaining (02 refs 01, 03 refs 02...). Independent plans need NO prior SUMMARY references.
