Initial commit

skills/create-plans/README.md

@@ -0,0 +1,291 @@
+# 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](../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