Create complete implementation plans with phases for new features or projects. Use when starting a new feature, planning a refactor, or designing a system ('create a plan', 'plan this feature', 'design the phases for...', 'plan the implementation'). Do NOT use for implementing code (use /implement), reviewing existing plans (use /review-plan), or quick single-file changes.
Create complete implementation plans with phases for new features or projects. Use when starting a new feature, planning a refactor, or designing a system ('create a plan', 'plan this feature', 'design the phases for...', 'plan the implementation'). Do NOT use for implementing code (use /implement), reviewing existing plans (use /review-plan), or quick single-file changes.
plan.md with all sections (phases added iteratively)
Reference reading from actual codebase for pattern accuracy
Phase files created one at a time with correct code patterns
Review via sub-agents for template + codebase compliance
Step 1: Clarify Requirements
The user has experienced 20-phase plans built on wrong assumptions — hours of work discarded because a 30-second question wasn't asked upfront. Clarification prevents this waste.
Read the task description above. If anything is ambiguous or underspecified, use AskUserQuestion to clarify before proceeding.
Questions to ask if not clear from the description:
Problem: What specific problem are we solving? What pain point does this address?
Scope: Is this a small feature, medium enhancement, or major system?
Users: Who uses this feature? (specific roles, account types)
Integrations: Does this connect to external services or APIs?
Data: What data does this create, read, update, or delete?
UI: Where does this appear in the app? New page, existing page, component?
If the description says "add voice commands" but doesn't specify which commands, ASK. If it says "improve performance" but doesn't specify what's slow, ASK. The user prefers a brief clarification dialogue over assumptions that lead to rework.
Step 2: Read Templates
The user created these templates specifically so phases don't miss required sections. Skipping template reading causes incomplete phases that require rework during implementation.
Complete ALL sections except Phase Table rows. Missing sections are caught during review (Step 9) but cost extra review cycles to fix.
Step 6: Design Phase Breakdown
Before creating phase files, plan the full decomposition.
Load Frontend Guidelines (If Applicable)
If the feature involves React components, Next.js pages, or UI work, invoke this skill BEFORE designing phases:
/vercel-react-best-practices
This loads 57 performance rules across 8 categories. Reference these when designing data fetching patterns, component architecture, and bundle optimization requirements.
Pre-Implementation Analysis
Before scoping phases, run through the checklist in .claude/rules/pre-implementation-analysis.md. Its 7 dimensions — existing patterns, blast radius, security surface, performance, maintainability, multi-tenant safety, and upstream compatibility — directly inform phase boundaries and what each phase's Prerequisites & Clarifications section should cover. Findings from this analysis (e.g. "touches auth flow", "new table needs RLS") should surface in the relevant phase files, not be left implicit.
Phase Constraints
Phases that exceed one context window cause Claude to lose earlier context mid-implementation, producing incomplete or inconsistent code. Each phase should be atomic enough for implementation in 1 context window (~15KB document, ~2-3 hour focused session).
30 small phases > 5 large phases
Wrong Approach
Right Approach
"Phase 01: Database + API + UI"
Split into 3 phases
"Phase 02: Full Feature Implementation"
Break into atomic steps
"Phase 03: Testing and Polish"
TDD is Step 0 in EACH phase
TDD Note: Both backend and frontend code require full unit tests:
Backend (services, schemas, APIs): Unit tests in __tests__/{feature}/
Frontend (React/TSX): Component tests using happy-dom (default) and @testing-library/react
The default happy-dom environment works for component tests. Only add // @vitest-environment happy-dom if explicitly overriding another environment.
Use it.todo('description') for TDD stubs
Use vi.hoisted() for mock variables needed before module evaluation
For Supabase client mocks, add .then() method for thenable/awaitable pattern
Path aliases in tests: use your project's configured path alias (e.g., @/ or ~/)
Atomic phase examples:
Phase 01: Database Schema & RLS Policies
Phase 02: Service Layer Functions
Phase 03: Server Actions with Validation
Phase 04: List View Component
Phase 05: Create Form Component
The test: Can Claude implement this phase without running out of context? If unsure, split it.
Step 7: Read Codebase References
Code blocks written from memory often don't match the real codebase — this is the #1 source of phase quality issues. Reading actual files before writing phases ensures patterns are accurate.
Identify which file types the feature will need and read one reference for each:
Feature Needs
Reference to Read
Server actions
Glob app/home/[account]/**/*server-actions*.ts → read one
Service layer
Glob app/home/[account]/**/*service*.ts → read one
Zod schemas
Glob app/home/[account]/**/*.schema.ts → read one
SQL migrations / RLS
Glob supabase/migrations/*.sql → read a recent one
React components
Glob app/home/[account]/**/_components/*.tsx → read one
Page files
Glob app/home/[account]/**/page.tsx → read one
Tests
Glob __tests__/**/*.test.ts → read one
Key patterns to extract and use in phase code blocks:
Account resolution: slug → ID via client.from('accounts').select('id').eq('slug', data.accountSlug).single()
Permission check: your RLS helper function (e.g., client.rpc('check_account_access', { ... }))
Supabase client: createClient() from @/lib/supabase/server
Service factory: createXxxService(client: SupabaseClient<Database>) wrapping a private class
Import paths: import 'server-only', @/ path alias for project root
File naming: _lib/schema/ (singular), server-actions.ts, exports ending in Action
TypeScript: consider enums or union types for constants, interface preferred for objects
After mutations: revalidatePath('/home/[account]/...')
Keep these patterns in mind for every code block you write in phase files. The review step (Step 9) will flag any code blocks that deviate from these codebase patterns.
Write the complete phase file following PHASE-TEMPLATE.md exactly.
File:plans/{folder}/phase-{NN}-{slug}.md
Include skill in Frontmatter — without it, the implementer won't know which skill to invoke and will use generic patterns instead of project-specific ones.
Code blocks in phases should match codebase patterns from Step 7 — not memory, not generic examples. Generic code blocks cause the implementer to write code that doesn't follow project conventions, creating rework. If you don't remember the exact pattern, re-read the reference file from Step 7 before writing the code block.
8c: Update Task Status
Mark the phase task as completed, move to next phase.
8d: Validate Phase Quality
After creating each phase file, run these validators to catch issues immediately (before review agents get involved). Run them via Bash — they read from stdin but only need {"cwd": "."}:
# Check for skeleton/placeholder content (catches the Phase 17 lesson)echo'{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_no_placeholders.py \
--directory plans/{folder} --extension .md
# Check TDD tasks appear before implementation tasksecho'{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_tdd_tasks.py \
--directory plans/{folder} --extension .md
# Confirm the phase file was actually createdecho'{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py \
--directory plans/{folder} --extension .md
If any validator exits non-zero, fix the issue before moving to the next phase. Placeholder content and missing TDD steps are the two most common causes of rework during implementation.
8e: Repeat
Continue until all phases are created.
Step 9: Review Complete Plan
Independent review agents catch template gaps and codebase compliance issues that self-review misses. The user depends on this step to prevent discovering problems during implementation when they're 10x more costly to fix.
Spawn one agent per file for thorough reviews. See Delegation Guide for:
Agent prompt templates for plan.md and phase reviews
Anti-patterns to avoid when delegating
Batching examples for plans of different sizes
Step 10: Flow Audit (3+ Phases)
For plans with 3 or more phases, run a flow audit to catch structural issues that per-phase reviews cannot see — circular dependencies, missing dependency declarations, wrong phase ordering, and stale artifacts.
Skip this step for 1-2 phase plans (too small for flow issues).
/audit-plan plans/{YYMMDD}-{feature-name}
This invokes /audit-plan which writes a report to {plan-folder}/reviews/planning/flow-audit.md. The /implement orchestrator gate-checks this report before starting implementation — if the overall assessment is "Major Restructuring Needed", implementation blocks.
If the audit finds Critical/High issues: Fix them in the phase files before reporting the plan as ready. Re-run /audit-plan after fixes to confirm the issues are resolved.
Step 11: Report Summary
After reviews and audit complete, provide the user with:
Folder location:plans/{YYMMDD}-{feature-name}/
Files created:
plan.md
phase-01-.md through phase-NN-.md
reviews/planning/ folder with review files
Review status:
Plan.md: template score (X/11)
Each phase: template score (X/12) + codebase score (N issues by severity)
Overall verdict: Ready/Not Ready for implementation
Critical issues (if any) that need addressing before implementation
Resuming After Context Compact
If you notice context was compacted or you're unsure of current progress:
Run TaskList to see all tasks and their status
Find the in_progress task — that's where you were
Run TaskGet {id} on that task to read full details
Continue from that task — don't restart from the beginning
Tasks persist across compacts. The task list is your source of truth for progress, not your memory.
Pattern for every work session:
TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task
Troubleshooting
Context Window Overflow
Symptom: Agent loses track of phases mid-creation, produces incomplete or inconsistent output.
Cause: Too many phases being created without task tracking, or review agents spawned without batching.
Fix: Follow Task List pattern in Step 4 — mark tasks complete as you go. For reviews, batch agents in groups of 4 per the Delegation Guide.
Missing Template Sections
Symptom: Review agents flag missing sections in plan.md or phase files.
Cause: Template not read before writing, or sections skipped during creation.
Fix: Re-read the template (references/PLAN-TEMPLATE.md or references/PHASE-TEMPLATE.md) and add the missing sections. Each section exists because omitting it caused implementation problems.
Agent Delegation Failures
Symptom: Review agents skip the /review-plan skill invocation or produce superficial reviews.
Cause: Vague delegation prompts that don't specify the skill to invoke or what success looks like.
Fix: Use the exact prompt templates from Delegation Guide. Include both the imperative command AND explanation of what the review entails.
Patterns That Prevent User-Reported Failures
The user experienced each of these failures. Understanding the harm helps you avoid them:
Pattern to Avoid
Harm When Ignored
Writing code blocks without reading codebase
Phases contain wrong patterns, caught late during implementation
Large multi-concern phases
Phases exceed context window, work gets lost mid-implementation
Skipping template sections
The user created templates so requirements aren't re-explained each time
Assuming instead of asking
Wrong plan built on false premises, hours of wasted effort
Self-reviewing the plan
Blind spots missed; /review-plan catches template AND codebase deviations
Vague delegation prompts
Agents misinterpret and skip skill invocation
Folder without date prefix
Folders become unsorted chronologically
Skipping TaskList check
Duplicates tasks if resuming after context compact
Template Locations
Plan: references/PLAN-TEMPLATE.md
Phase: references/PHASE-TEMPLATE.md
These templates are auto-loaded into your context from the skill's references/ folder. Match them section-by-section.
