project-planning

What this skill does

# Project Planning Skill

Specialized planning assistant for web application projects. Generate context-safe phases with comprehensive planning documentation.

---

## ⚡ Recommended Workflow

1. **ASK** 3-5 clarifying questions (auth, data, features, scope)
2. **WAIT** for user answers
3. **CREATE** planning docs immediately (IMPLEMENTATION_PHASES.md always, others as needed)
4. **OUTPUT** all docs to user for review
5. **CONFIRM** user satisfied
6. **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:
1. **Type** - Infrastructure / Database / API / UI / Integration / Testing
2. **Estimated duration** - In hours (and minutes of human time)
3. **Files** - Specific files that will be created/modified
4. **Task list** - Ordered checklist with clear actions
5. **Verification criteria** - Checkbox list of tests to confirm phase works
6. **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

```markdown
# 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 verification
```

### DATABASE_SCHEMA.md Template

```markdown
# 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 |
|