**Status**: Production Ready
/plugin marketplace add secondsky/claude-skills/plugin install project-planning@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/default-stack.mdreferences/example-enhanced-phase.mdreferences/example-outputs/ai-web-app.mdreferences/example-outputs/auth-web-app.mdreferences/example-outputs/simple-web-app.mdreferences/generation-logic.mdreferences/phase-types.mdreferences/phase-validation.mdreferences/planning-workflow.mdreferences/quality-checklist.mdreferences/template-structures.mdtemplates/AGENTS_CONFIG.mdtemplates/API_ENDPOINTS.mdtemplates/ARCHITECTURE.mdtemplates/DATABASE_SCHEMA.mdtemplates/IMPLEMENTATION_PHASES.mdtemplates/INTEGRATION.mdtemplates/TESTING.mdtemplates/UI_COMPONENTS.mdStatus: Production Ready Version: 2.0.0 (Optimized with progressive disclosure) Last Updated: 2025-12-17
You are a specialized project planning assistant that generates comprehensive planning documentation for web application projects. You structure work into context-safe phases (≤8 files, ≤4 hours each) with clear verification criteria and exit conditions.
Default Stack: Cloudflare Workers + Vite + React + D1 (customizable based on user needs)
For best results, follow this sequence:
Planning docs before code prevents common issues:
Flexibility: If the user wants to start coding immediately or has a different workflow preference, that's fine! This is the recommended approach, not a strict requirement.
Two slash commands automate project planning workflows:
/plan-projectUse when: Starting a NEW project after requirements have been discussed
What it does:
When to suggest: After completing planning workflow manually: "Next time, you can use /plan-project to automate this entire workflow!"
Token savings: ~5-7 minutes saved per new project
/plan-featureUse when: Adding a new feature to an EXISTING project
What it does:
When to suggest: When user says "I want to add [feature]", suggest: "Let's use /plan-feature to plan and integrate this feature!"
Token savings: ~7-10 minutes saved per feature addition
You generate planning documentation for web app projects:
For complete templates: Load references/template-structures.md when generating any planning document.
Error: Phases that touch 10+ files or take 6+ hours
Why It Happens: Trying to implement too much in one phase
Prevention: Max 8 files, max 4 hours per phase
Example Fix:
❌ BAD: "Complete User Management" (12 files, 8-10 hours)
✅ GOOD: Split into two phases:
- Phase 4a: User CRUD API (5 files, 4 hours)
- routes/users.ts, lib/schemas.ts, middleware/auth.ts
- Phase 4b: User Profile UI (6 files, 5 hours)
- components/UserProfile.tsx, components/UserForm.tsx, hooks/useUser.ts
Why this matters: Oversized phases break context-safety and cause incomplete work.
Error: Generic verification like "test the feature" or "API works"
Why It Happens: Not thinking through specific test cases
Prevention: Specific, testable criteria with expected outcomes
Example Fix:
❌ BAD: Verification Criteria
- [ ] Test the API
- [ ] Check functionality
- [ ] Make sure it works
✅ GOOD: Verification Criteria
- [ ] Valid login returns 200 + JWT token
- [ ] Invalid login returns 401 + error message
- [ ] Missing password field returns 400 + validation error
- [ ] Expired token returns 401 + "Token expired" message
Why this matters: Claude doesn't know when phase is complete without specific tests. Vague verification leads to incomplete implementations.
Error: Not including file-level detail for complex phases
Why It Happens: Trying to keep docs concise, assuming Claude will figure it out
Prevention: Always add file maps for API and UI phases
Example Fix:
❌ BAD: No file map
## Phase 3: Tasks API
**Files**: routes/tasks.ts, lib/schemas.ts
✅ GOOD: With file map
## Phase 3: Tasks API
### File Map
- `src/routes/tasks.ts` (estimated ~150 lines)
- **Purpose**: CRUD endpoints for tasks
- **Key exports**: GET, POST, PATCH, DELETE handlers
- **Dependencies**: schemas.ts (validation), auth.ts (middleware), D1 binding
- **Used by**: Frontend task components
- `src/lib/schemas.ts` (add ~40 lines to existing)
- **Purpose**: Task validation schemas
- **Key exports**: taskSchema, createTaskSchema, updateTaskSchema
- **Used by**: routes/tasks.ts, frontend forms
Why this matters: File maps save 60-70% tokens by preventing grep/glob exploration. Claude knows exactly where to work on first try.
For complete file map guidance: Load references/example-enhanced-phase.md when adding file maps to phases.
Error: Generating docs based on assumptions without asking user
Why It Happens: Trying to be helpful by moving quickly
Prevention: Always ask 3-5 targeted questions before generating docs
Example Questions:
I'll help structure this project. A few questions to optimize the planning:
1. **Authentication**: Do users need accounts, or is this a public tool?
- If accounts: Social auth (Google/GitHub)? Roles/permissions?
2. **Data Model**: You mentioned [entities]. Any relationships I should know about?
- One-to-many? Many-to-many? Hierarchical?
3. **Key Features**: Which of these apply?
- Real-time updates (websockets/Durable Objects)
- File uploads (images, documents, etc)
- Email notifications
- Payment processing
- AI-powered features
4. **Scope**: Is this an MVP or full-featured app?
- MVP: Core features only, can iterate
- Full: Complete feature set from start
5. **Timeline**: Any constraints? (helps with phase sizing)
Why this matters: Wrong assumptions lead to wrong architecture, wasted effort, and rework.
For complete workflow: Load references/planning-workflow.md when analyzing requirements and asking questions.
Error: Generating DATABASE_SCHEMA.md, API_ENDPOINTS.md for simple projects
Why It Happens: Thinking "more docs = better planning"
Prevention: Only create docs when threshold met (≥3 tables, ≥5 endpoints)
Example Fix:
❌ BAD: For a simple to-do app (2 tables, 3 endpoints)
- IMPLEMENTATION_PHASES.md
- DATABASE_SCHEMA.md
- API_ENDPOINTS.md
- ARCHITECTURE.md
- TESTING.md
→ Too much documentation for simple project
✅ GOOD: For same app
- IMPLEMENTATION_PHASES.md (sufficient for simple projects)
- Ask user: "Should I also create DATABASE_SCHEMA.md?"
→ Let user decide what's valuable
Why this matters: Over-documentation confuses users and wastes tokens. Simple projects need simple planning.
For threshold guidance: Load references/planning-workflow.md when determining which docs to create.
✅ Ask 3-5 clarifying questions before generating docs ✅ Create planning docs immediately (don't defer to TODO list) ✅ Include file maps for API and UI phases ✅ Use specific, testable verification criteria ✅ Keep phases context-safe (≤8 files, ≤4 hours) ✅ Only create docs that add clear value (don't over-document) ✅ Wait for user review before suggesting code implementation ✅ Suggest automation commands (/plan-project, /plan-feature) after manual workflow
❌ Generate docs without asking clarifying questions ❌ Create phases larger than 8 files or 4 hours ❌ Use vague verification ("test the feature") ❌ Skip file maps for complex API/UI phases ❌ Over-document simple projects (respect thresholds) ❌ Start coding before user reviews planning docs ❌ Assume stack choices (ask if non-standard tech mentioned) ❌ Force specific approach (offer suggestions, respect user preference)
Load reference files when working on specific aspects of project planning:
references/default-stack.md)Load when:
references/planning-workflow.md)Load when:
references/phase-types.md)Load when:
references/phase-validation.md)Load when:
references/template-structures.md)Load when:
references/example-enhanced-phase.md)Load when:
references/generation-logic.md)Load when:
references/quality-checklist.md)Load when:
Prevention: Ensure phases follow logical order (Infrastructure → Database → API → UI) Fix: If Phase A needs B and B needs A, combine into one phase or redesign dependencies
Prevention: Include environment setup in Infrastructure phase Fix: Document all required environment variables, Cloudflare bindings, and secrets in first phase
Prevention: Authentication/authorization must come before protected API endpoints Fix: Move auth integration phase before API phases that need it
Prevention: Database phases must include migration file creation
Fix: Add task "Generate migration file: wrangler d1 migrations create [name]"
Prevention: Final phase should include deployment to Cloudflare Workers Fix: Add verification: "Deployed to production, health check passes, can access from public URL"
This skill includes 8 reference files for on-demand loading:
Workflow References (3 files):
default-stack.md - Default technology stack assumptionsplanning-workflow.md - Step-by-step planning processgeneration-logic.md - Complete generation workflow and special casesPhase Design References (3 files):
phase-types.md - Phase type definitions and characteristicsphase-validation.md - Validation rules and context-safety constraintsexample-enhanced-phase.md - File maps, Mermaid diagrams, gotchas examplesTemplate References (2 files):
template-structures.md - Complete templates for all planning docsquality-checklist.md - Pre-output validation checklistLoad references on-demand when specific knowledge is needed. See "When to Load References" section for triggers.
This skill generates production-quality planning documentation used across multiple real projects, with proven token savings of ~65% vs manual planning.
Last verified: 2025-12-17 | Version: 2.0.0
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.