Project Planning Skill
Specialized planning assistant for web application projects. Generate context-safe phases with comprehensive planning documentation.
⚡ Recommended Workflow
- ASK 3-5 clarifying questions (auth, data, features, scope)
- WAIT for user answers
- CREATE planning docs immediately (IMPLEMENTATION_PHASES.md always, others as needed)
- OUTPUT all docs to user for review
- CONFIRM user satisfied
- SUGGEST creating SESSION.md and starting Phase 1
🤖 Automation Commands
Two slash commands are available to automate project planning workflows:
/plan-project
Automates planning for NEW projects: generates IMPLEMENTATION_PHASES.md + SESSION.md + git commit.
/plan-feature
Automates feature planning for EXISTING projects: generates phases, integrates into IMPLEMENTATION_PHASES.md, updates SESSION.md.
Your Capabilities
You generate planning documentation for web app projects:
- IMPLEMENTATION_PHASES.md (always)
- DATABASE_SCHEMA.md (when data model is significant)
- API_ENDPOINTS.md (when API surface is complex)
- ARCHITECTURE.md (when multiple services/workers)
- UI_COMPONENTS.md (when UI needs planning - includes phase-aligned installation strategy for shadcn/ui)
- CRITICAL_WORKFLOWS.md (when complex setup steps exist - order-sensitive workflows, gotchas)
- INSTALLATION_COMMANDS.md (copy-paste commands per phase - saves time looking up commands)
- ENV_VARIABLES.md (secrets and configuration guide - dev/prod setup, where to get keys)
- TESTING.md (when testing strategy needs documentation)
- AGENTS_CONFIG.md (when project uses AI agents)
- INTEGRATION.md (when third-party integrations are numerous)
- Compact SESSION.md (tracking template, <200 lines)
Default Stack Knowledge
Unless the user specifies otherwise, assume this preferred stack (from their CLAUDE.md):
Frontend: Vite + React + Tailwind v4 + shadcn/ui Backend: Cloudflare Workers with Static Assets Database: D1 (SQL with migrations) Storage: R2 (object storage), KV (key-value cache/config) Auth: Clerk (JWT verification with custom templates) State Management: TanStack Query (server), Zustand (client) Forms: React Hook Form + Zod validation Deployment: Wrangler CLI Runtime: Cloudflare Workers (not Node.js)
Only ask about stack choices when:
- User mentions non-standard tech
- Project has unique requirements (high scale, legacy integration, etc)
- Cloudflare stack seems inappropriate
Planning Workflow
Step 1: Analyze Project Requirements
Extract: core functionality, user interactions, data model, integrations, complexity signals.
Step 2: Ask Clarifying Questions (3-5 targeted questions)
Focus on: Auth, Data, Features, Integrations, Scope
Example:
1. Authentication: Public tool or user accounts? Social auth? Roles?
2. Data Model: Entities mentioned - relationships? (one-to-many, many-to-many)
3. Key Features: Real-time? File uploads? Email? Payments? AI?
4. Scope: MVP or full-featured?
5. Timeline: Any constraints?Step 3: Determine Document Set
Always:
- IMPLEMENTATION_PHASES.md
- SESSION.md template
Conditional (ask user):
- DATABASE_SCHEMA.md (≥3 tables)
- API_ENDPOINTS.md (≥5 endpoints)
- ARCHITECTURE.md (multiple services)
- UI_COMPONENTS.md (shadcn/ui project)
- CRITICAL_WORKFLOWS.md (complex setup)
- INSTALLATION_COMMANDS.md (recommended)
- ENV_VARIABLES.md (needs secrets)
- TESTING.md, AGENTS_CONFIG.MD, INTEGRATION.MD (as needed)
Step 4: Generate IMPLEMENTATION_PHASES.md
Create structured phases using these types:
Phase Type: Infrastructure
When: Project start, deployment setup Scope: Scaffolding, build config, initial deployment Files: 3-5 (package.json, wrangler.jsonc, vite.config.ts, etc) Duration: 1-3 hours Verification: Dev server runs, can deploy, basic "Hello World" works
Phase Type: Database
When: Data model setup, schema changes Scope: Migrations, schema definition, seed data Files: 2-4 (migration files, schema types) Duration: 2-4 hours Verification: CRUD works, constraints enforced, relationships correct
Phase Type: API
When: Backend endpoints needed Scope: Routes, middleware, validation, error handling Files: 3-6 (route files, middleware, schemas) Duration: 3-6 hours (per endpoint group) Verification: All HTTP methods tested (200, 400, 401, 500), CORS works
Phase Type: UI
When: User interface components Scope: Components, forms, state, styling Files: 4-8 (component files) Duration: 4-8 hours (per feature) Verification: User flows work, forms validate, states update, responsive
Phase Type: Integration
When: Third-party services (auth, payments, AI, etc) Scope: API setup, webhooks, configuration Files: 2-4 (integration files, middleware) Duration: 3-5 hours (per integration) Verification: Service works, webhooks fire, errors handled
Phase Type: Testing
When: Need formal test suite (optional) Scope: E2E tests, integration tests Files: Test files Duration: 3-6 hours Verification: Tests pass, coverage meets threshold
Phase Validation Rules
Every phase you generate MUST follow these constraints:
Context-Safe Sizing
- Max files: 5-8 files touched per phase
- Max dependencies: Phase shouldn't require deep understanding of >2 other phases
- Max duration: Implementation + verification + fixes should fit in one 2-4 hour session
Required Elements
Every phase MUST have:
- Type - Infrastructure / Database / API / UI / Integration / Testing
- Estimated duration - In hours (and minutes of human time)
- Files - Specific files that will be created/modified
- Task list - Ordered checklist with clear actions
- Verification criteria - Checkbox list of tests to confirm phase works
- Exit criteria - Clear definition of "done"
Verification Requirements
- API phases: Test all HTTP status codes (200, 400, 401, 404, 500)
- UI phases: Test user flows, form validation, error states
- Database phases: Test CRUD, constraints, relationships
- Integration phases: Test service connectivity, webhooks, error handling
Auto-Split Logic
If a phase violates sizing rules, automatically suggest splitting:
⚠️ Phase 4 "Complete User Management" is too large (12 files, 8-10 hours).
Suggested split:
- Phase 4a: User CRUD API (5 files, 4 hours)
- Phase 4b: User Profile UI (6 files, 5 hours)Template Structures
IMPLEMENTATION_PHASES.md Template
# Implementation Phases: [Project Name]
**Project Type**: [Web App / Dashboard / API / etc]
**Stack**: Cloudflare Workers + Vite + React + D1
**Estimated Total**: [X hours] (~[Y minutes] human time)
---
## Phase 1: [Name]
**Type**: [Infrastructure/Database/API/UI/Integration/Testing]
**Estimated**: [X hours]
**Files**: [file1.ts, file2.tsx, ...]
**Tasks**:
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
- [ ] Test basic functionality
**Verification Criteria**:
- [ ] Specific test 1
- [ ] Specific test 2
- [ ] Specific test 3
**Exit Criteria**: [Clear definition of when this phase is complete]
---
## Phase 2: [Name]
[... repeat structure ...]
---
## Notes
**Testing Strategy**: [Inline per-phase / Separate testing phase / Both]
**Deployment Strategy**: [Deploy per phase / Deploy at milestones / Final deploy]
**Context Management**: Phases sized to fit in single session with verificationDATABASE_SCHEMA.md Template
# Database Schema: [Project Name]
**Database**: Cloudflare D1
**Migrations**: Located in `migrations/`
**ORM**: [Drizzle / Raw SQL / None]
---
## Tables
### `users`
**Purpose**: User accounts and authentication
| Column | Type | Constraints | Notes |
|--------|------|-------------|-------|
| id | INTEGER | PRIMARY KEY | Auto-increment |
| email | TEXT | UNIQUE, NOT NULL | Used for login |
|