Create hierarchical project plans optimized for solo agentic development. Use when planning projects, phases, or tasks that Claude will execute. Produces Claude-executable plans with verification criteria, not enterprise documentation. Handles briefs, roadmaps, phase plans, and context handoffs.
Create hierarchical project plans optimized for solo agentic development. Use when planning projects, phases, or tasks that Claude will execute. Produces Claude-executable plans with verification criteria, not enterprise documentation. Handles briefs, roadmaps, phase plans, and context handoffs.
<essential_principles>
You are planning for ONE person (the user) and ONE implementer (Claude).
No teams. No stakeholders. No ceremonies. No coordination overhead.
The user is the visionary/product owner. Claude is the builder.
PLAN.md is not a document that gets transformed into a prompt.
PLAN.md IS the prompt. It contains:
- Objective (what and why)
- Context (@file references)
- Tasks (type, files, action, verify, done, checkpoints)
- Verification (overall checks)
- Success criteria (measurable)
- Output (SUMMARY.md specification)
When planning a phase, you are writing the prompt that will execute it.
Plans must complete within ~50% of context usage to maintain consistent quality.
The quality degradation curve:
0-30% context: Peak quality (comprehensive, thorough, no anxiety)
30-50% context: Good quality (engaged, manageable pressure)
Critical insight: Claude doesn't degrade at 80% - it degrades at ~40-50% when it sees context mounting and enters "completion mode." By 80%, quality has already crashed.
Solution: Aggressive atomicity - split phases into many small, focused plans.
01-03-PLAN.md - Phase 1, Plan 3 (2-3 tasks: API routes)
01-04-PLAN.md - Phase 1, Plan 4 (2-3 tasks: UI components)
**Claude automates everything that has a CLI or API.** Checkpoints are for verification and decisions, not manual work.
Plans are guides, not straitjackets. Real development always involves discoveries.
No enterprise process. No approval gates. No multi-week timelines.
Plan → Execute → Ship → Learn → Repeat.
Milestones mark shipped versions (v1.0, v1.1, v2.0).
NEVER include in plans:
- Team structures, roles, RACI matrices
- Stakeholder management, alignment meetings
- Sprint ceremonies, standups, retros
- Multi-week estimates, resource allocation
- Change management, governance processes
- Documentation for documentation's sake
Monitor token usage via system warnings.
Never charge ahead at critical decision points. Use gates:
- **AskUserQuestion**: Structured choices (2-4 options)
- **Inline questions**: Simple confirmations
- **Decision gate loop**: "Ready, or ask more questions?"
All planning artifacts are version controlled. Commit outcomes, not process.
Based on scan results, present context-aware options:
| Response | Workflow |
|----------|----------|
| "brief", "new project", "start", 1 (no structure) | `workflows/create-brief.md` |
| "roadmap", "phases", 2 (no structure) | `workflows/create-roadmap.md` |
| "phase", "plan phase", "next phase", 1 (has structure) | `workflows/plan-phase.md` |
| "chunk", "next tasks", "what's next" | `workflows/plan-chunk.md` |
| "execute", "run", "do it", "build it", 2 (has structure) | **EXIT SKILL** → Use `/run-plan ` slash command |
| "research", "investigate", "unknowns" | `workflows/research-phase.md` |
| "handoff", "pack up", "stopping", 3 (has structure) | `workflows/handoff.md` |
| "resume", "continue", 1 (has handoff) | `workflows/resume.md` |
| "transition", "complete", "done", "next" | `workflows/transition.md` |
| "milestone", "ship", "v1.0", "release" | `workflows/complete-milestone.md` |
| "guidance", "help", 4 | `workflows/get-guidance.md` |
The planning hierarchy (each level builds on previous):
Each plan is independently executable, verifiable, and scoped to 2-3 tasks maximum.
Atomic task principle: Better to have 10 small, high-quality plans than 3 large, degraded plans. Each commit should be surgical, focused, and maintainable.
Autonomous execution: Plans without checkpoints execute via subagent with fresh context - impossible to degrade.
See: references/scope-estimation.md
Checkpoint types:
checkpoint:human-verify - Human confirms Claude's automated work (visual checks, UI verification)
checkpoint:decision - Human makes implementation choice (auth provider, architecture)
Rarely needed:checkpoint:human-action - Only for actions with no CLI/API (email verification links, account approvals requiring web login with 2FA)
Critical rule: If Claude CAN do it via CLI/API/tool, Claude MUST do it. Never ask human to:
Deploy to Vercel/Railway/Fly (use CLI)
Create Stripe webhooks (use CLI/API)
Run builds/tests (use Bash)
Write .env files (use Write tool)
Create database resources (use provider CLI)
Protocol: Claude automates work → reaches checkpoint:human-verify → presents what was done → waits for confirmation → resumes
Milestone-driven: Ship v1.0 → mark milestone → plan v1.1 → ship → repeat.
Milestones mark shipped versions and enable continuous iteration.
Purpose:
Historical record in MILESTONES.md (what shipped when)
Greenfield → Brownfield transition marker
Git tags for releases
Clear completion rituals
Default approach: Extend existing roadmap with new phases.
v1.0 ships (phases 1-4) → add phases 5-6 for v1.1
Continuous phase numbering (01-99)
Milestone groupings keep roadmap organized
Archive ONLY for: Separate codebases or complete rewrites (rare).
See: references/milestone-management.md
If it sounds like corporate PM theater, delete it.
At 25% remaining: Mention context getting full
At 15% remaining: Pause, offer handoff
At 10% remaining: Auto-create handoff, stop
Never start large operations below 15% without user confirmation.
Mandatory gates:
Before writing PLAN.md (confirm breakdown)
After low-confidence research
On verification failures
After phase completion with issues
Before starting next phase with previous issues
See: references/user-gates.md
Check for repo on invocation, offer to initialize
Commit only at: initialization, phase completion, handoff
Intermediate artifacts (PLAN.md, RESEARCH.md, FINDINGS.md) NOT committed separately
Git log becomes project history
See: references/git-integration.md
</essential_principles>
<context_scan>
Run on every invocation to understand current state:
# Check git status
git rev-parse --git-dir 2>/dev/null || echo"NO_GIT_REPO"# Check for planning structurels -la .planning/ 2>/dev/null
ls -la .planning/phases/ 2>/dev/null
# Find any continue-here files
find . -name ".continue-here.md" -type f 2>/dev/null
# Check for existing artifacts
[ -f .planning/BRIEF.md ] && echo"BRIEF: exists"
[ -f .planning/ROADMAP.md ] && echo"ROADMAP: exists"
If NO_GIT_REPO detected:
Inline question: "No git repo found. Initialize one? (Recommended for version control)"
If yes: git init
Present findings before intake question.
</context_scan>
<domain_expertise>
Domain expertise lives in ~/.claude/skills/expertise/
Before creating roadmap or phase plans, determine if domain expertise should be loaded.
<scan_domains>
ls ~/.claude/skills/expertise/ 2>/dev/null
This reveals available domain expertise (e.g., macos-apps, iphone-apps, unity-games, nextjs-ecommerce).
If no domain skills found: Proceed without domain expertise (graceful degradation). The skill works fine without domain-specific context.
</scan_domains>
<inference_rules>
If user's request contains domain keywords, INFER the domain:
Detected: [domain] project → expertise/[skill-name]
Load this expertise for planning? (Y / see other options / none)
</inference_rules>
<no_inference>
If no domain obvious from request, present options:
What type of project is this?
Available domain expertise:
1. macos-apps - Native macOS with Swift/SwiftUI
2. iphone-apps - Native iOS with Swift/SwiftUI
3. unity-games - Unity game development
4. swift-midi-apps - MIDI/audio apps
5. with-agent-sdk - Claude Agent SDK apps
6. ui-design - Stunning UI/UX design & frontend development
[... any others found in expertise/]
N. None - proceed without domain expertise
C. Create domain skill first
Select:
</no_inference>
<load_domain>
When domain selected, use intelligent loading:
Based on the phase being planned (from ROADMAP), load ONLY the references mentioned for that type of work.
# Example: Planning a database phasecat ~/.claude/skills/expertise/macos-apps/references/core-data.md
cat ~/.claude/skills/expertise/macos-apps/references/swift-conventions.md
Context efficiency:
SKILL.md only: ~5k tokens
SKILL.md + selective references: ~8-12k tokens
All references (old approach): ~20-27k tokens
Announce: "Loaded [domain] expertise ([X] references for [phase-type])."
If domain skill not found: Inform user and offer to proceed without domain expertise.
If SKILL.md doesn't have references_index: Fall back to loading all references with warning about context usage.
</load_domain>
<when_to_load>
Domain expertise should be loaded BEFORE:
Creating roadmap (phases should be domain-appropriate)
Planning phases (tasks must be domain-specific)
Domain expertise is NOT needed for:
Creating brief (vision is domain-agnostic)
Resuming from handoff (context already established)
Transition between phases (just updating status)
</when_to_load>
</domain_expertise>
If handoff found:
Found handoff: .planning/phases/XX/.continue-here.md
[Summary of state from handoff]
1. Resume from handoff
2. Discard handoff, start fresh
3. Different action
If planning structure exists:
Project: [from BRIEF or directory]
Brief: [exists/missing]
Roadmap: [X phases defined]
Current: [phase status]
What would you like to do?
1. Plan next phase
2. Execute current phase
3. Create handoff (stopping for now)
4. View/update roadmap
5. Something else
If no planning structure:
No planning structure found.
What would you like to do?
1. Start new project (create brief)
2. Create roadmap from existing brief
3. Jump straight to phase planning
4. Get guidance on approach
Wait for response before proceeding.
Critical: Plan execution should NOT invoke this skill. Use /run-plan for context efficiency (skill loads ~20k tokens, /run-plan loads ~5-7k).
After reading the workflow, follow it exactly.
BRIEF.md → Human vision (you read this)
↓
ROADMAP.md → Phase structure (overview)
↓
RESEARCH.md → Research prompt (optional, for unknowns)
↓
FINDINGS.md → Research output (if research done)
↓
PLAN.md → THE PROMPT (Claude executes this)
↓
SUMMARY.md → Outcome (existence = phase complete)
Rules:
Roadmap requires Brief (or prompts to create one)
Phase plan requires Roadmap (knows phase scope)
PLAN.md IS the execution prompt
SUMMARY.md existence marks phase complete
Each level can look UP for context
<output_structure>
All planning artifacts go in .planning/:
