create-plans

Hierarchical project planning optimized for solo developer + Claude

Create executable plans that Claude can run, not enterprise documentation that sits unused.

Philosophy

You are the visionary. Claude is the builder.

No teams. No stakeholders. No ceremonies. No coordination overhead.

Plans are written AS prompts (PLAN.md IS the execution prompt), not documentation that gets transformed into prompts later.

Quick Start

Skill("create-plans")

The skill will:

1. Scan for existing planning structure
2. Check for git repo (offers to initialize)
3. Present context-aware options
4. Guide you through the appropriate workflow

Planning Hierarchy

BRIEF.md          → Human vision (what and why)
    ↓
ROADMAP.md        → Phase structure (high-level plan)
    ↓
RESEARCH.md       → Research prompt (for unknowns - optional)
    ↓
FINDINGS.md       → Research output (if research done)
    ↓
PLAN.md           → THE PROMPT (Claude executes this)
    ↓
SUMMARY.md        → Outcome (existence = phase complete)

Directory Structure

All planning artifacts go in .planning/:

.planning/
├── BRIEF.md                    # Project vision
├── ROADMAP.md                  # Phase structure + tracking
└── phases/
    ├── 01-foundation/
    │   ├── PLAN.md             # THE PROMPT (execute this)
    │   ├── SUMMARY.md          # Outcome (exists = done)
    │   └── .continue-here.md   # Handoff (temporary)
    └── 02-auth/
        ├── RESEARCH.md         # Research prompt (if needed)
        ├── FINDINGS.md         # Research output
        ├── PLAN.md             # Execute prompt
        └── SUMMARY.md

Workflows

Starting a New Project

1. Invoke skill
2. Choose "Start new project"
3. Answer questions about vision/goals
4. Skill creates BRIEF.md
5. Optionally create ROADMAP.md with phases
6. Plan first phase

Planning a Phase

1. Skill reads BRIEF + ROADMAP
2. Loads domain expertise if applicable (see Domain Skills below)
3. If phase has unknowns → create RESEARCH.md first
4. Creates PLAN.md (the executable prompt)
5. You review or execute

Executing a Phase

1. Skill reads PLAN.md
2. Executes each task with verification
3. Creates SUMMARY.md when complete
4. Git commits phase completion
5. Offers to plan next phase

Pausing Work (Handoff)

1. Choose "Create handoff"
2. Skill creates .continue-here.md with full context
3. When resuming, skill loads handoff and continues

Domain Skills (Optional)

What are domain skills?

Full-fledged agent skills that exhaustively document how to build in a specific framework/platform. They make your plans concrete instead of generic.

Without domain skill:

Task: Create authentication system
Action: Implement user login

Generic. Not helpful.

With domain skill (macOS apps):

Task: Create login window
Files: Sources/Views/LoginView.swift
Action: SwiftUI view with @Bindable for User model. TextField for username/password.
SecureField for password (uses system keychain). Submit button triggers validation
logic. Use @FocusState for tab order. Add Command-L keyboard shortcut.
Verify: xcodebuild test && open App.app (check tab order, keychain storage)

Specific. Executable. Framework-appropriate.

Structure of domain skills:

~/.claude/skills/expertise/[domain]/
├── SKILL.md              # Router + essential principles
├── workflows/            # build-new-app, add-feature, debug-app, etc.
└── references/           # Exhaustive domain knowledge (often 10k+ lines)

Domain skills are dual-purpose:

1. Standalone skills - Invoke with Skill("build-macos-apps") for guided development
2. Context for create-plans - Loaded automatically when planning that domain

Example domains:

• macos-apps - Swift/SwiftUI macOS (19 references, 10k+ lines)
• iphone-apps - Swift/SwiftUI iOS
• unity-games - Unity game development
• swift-midi-apps - MIDI/audio apps
• with-agent-sdk - Claude Agent SDK apps
• nextjs-ecommerce - Next.js e-commerce

How it works:

1. Skill infers domain from your request ("build a macOS app" → build-macos-apps)
2. Before creating PLAN.md, reads all ~/.claude/skills/build/macos-apps/references/*.md
3. Uses that exhaustive knowledge to write framework-specific tasks
4. Result: Plans that match your actual tech stack with all the details

What if you don't have domain skills?

Skill works fine without them - proceeds with general planning. But tasks will be more generic and require more clarification during execution.

Creating a Domain Skill

Domain skills are created with create-agent-skills skill.

Process:

1. Skill("create-agent-skills") → choose "Build a new skill"
2. Name: build-[your-domain]
3. Description: "Build [framework/platform] apps. Full lifecycle - build, debug, test, optimize, ship."
4. Ask it to create exhaustive references covering:
   • Architecture patterns
   • Project scaffolding
   • Common features (data, networking, UI)
   • Testing and debugging
   • Platform-specific conventions
   • CLI workflow (how to build/run without IDE)
   • Deployment/shipping

The skill should be comprehensive - 5k-10k+ lines documenting everything about building in that domain. When create-plans loads it, the resulting PLAN.md tasks will be detailed and executable.

Quality Controls

Research prompts include systematic verification to prevent gaps:

• Verification checklists - Enumerate ALL options before researching
• Blind spots review - "What might I have missed?"
• Critical claims audit - Verify "X is not possible" with sources
• Quality reports - Distinguish verified facts from assumptions
• Streaming writes - Write incrementally to prevent token limit failures

See references/research-pitfalls.md for known mistakes and prevention.

Key Principles

Solo Developer + Claude

Planning for ONE person (you) and ONE implementer (Claude). No team coordination, stakeholder management, or enterprise processes.

Plans Are Prompts

PLAN.md IS the execution prompt. It contains objective, context (@file references), tasks (Files/Action/Verify/Done), and verification steps.

Ship Fast, Iterate Fast

Plan → Execute → Ship → Learn → Repeat. No multi-week timelines, approval gates, or sprint ceremonies.

Context Awareness

Monitors token usage:

• 25% remaining: Mentions context getting full
• 15% remaining: Pauses, offers handoff
• 10% remaining: Auto-creates handoff, stops

Never starts large operations below 15% without confirmation.

User Gates

Pauses at critical decision points:

• Before writing PLAN.md (confirm breakdown)
• After low-confidence research
• On verification failures
• When previous phase had issues

See references/user-gates.md for full gate patterns.

Git Versioning

All planning artifacts are version controlled. Commits outcomes, not process:

• Initialization commit (BRIEF + ROADMAP)
• Phase completion commits (PLAN + SUMMARY + code)
• Handoff commits (when pausing work)

Git log becomes project history.

Anti-Patterns

This skill NEVER includes:

• 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

If it sounds like corporate PM theater, it doesn't belong.

Files Reference

Structure

• references/directory-structure.md - Planning directory layout
• references/hierarchy-rules.md - How levels build on each other

Formats

• references/plan-format.md - PLAN.md structure
• references/handoff-format.md - Context handoff structure

Patterns

• references/context-scanning.md - How skill understands current state
• references/context-management.md - Token usage monitoring
• references/user-gates.md - When to pause and ask
• references/git-integration.md - Version control patterns
• references/research-pitfalls.md - Known research mistakes

Templates

• templates/brief.md - Project vision document
• templates/roadmap.md - Phase structure
• templates/phase-prompt.md - Executable phase prompt (PLAN.md)
• templates/research-prompt.md - Research prompt (RESEARCH.md)
• templates/summary.md - Phase outcome (SUMMARY.md)
• templates/continue-here.md - Context handoff

Workflows

• workflows/create-brief.md - Create project vision
• workflows/create-roadmap.md - Define phases from brief
• workflows/plan-phase.md - Create executable phase prompt
• workflows/execute-phase.md - Run phase, create summary
• workflows/research-phase.md - Create and run research
• workflows/plan-chunk.md - Plan immediate next tasks
• workflows/transition.md - Mark phase complete, advance
• workflows/handoff.md - Create context handoff for pausing
• workflows/resume.md - Load handoff, restore context
• workflows/get-guidance.md - Help decide planning approach

Example Domain Skill

See build/example-nextjs/ for a minimal domain skill showing:

• Framework-specific patterns
• Project structure conventions
• Common commands
• Phase breakdown strategies
• Task specificity guidelines

Use this as a template for creating your own domain skills.

Success Criteria

Planning skill succeeds when:

• Context scan runs before intake
• Appropriate workflow selected based on state
• PLAN.md IS the executable prompt (not separate doc)
• Hierarchy is maintained (brief → roadmap → phase)
• Handoffs preserve full context for resumption
• Context limits respected (auto-handoff at 10%)
• Quality controls prevent research gaps
• Streaming writes prevent token limit failures