📄 Planning Documents - The Foundation of Success
Use these templates as your starting point, customizing based on your discovery phase findings
🏗️ Master Prompt Template
ultrathink and create a comprehensive project structure for [PROJECT NAME]
Project Type: [Based on discovery: SaaS, E-commerce, Dashboard, Internal Tool]
Target Users: [From discovery phase analysis]
EXPLICIT TECH STACK (DO NOT DEVIATE):
Frontend:
- Next.js 14 (app router, not pages)
- TypeScript with strict mode
- Tailwind CSS + shadcn/ui components
- [If needed] heroui for data tables
- [If needed] aceternity for animations
- State: Zustand for client, React Query for server
- Forms: react-hook-form + zod validation
Backend:
- [From discovery] Supabase/Firebase/Custom API
- [If CMS needed] Strapi/Sanity/Contentful
- Edge Functions for serverless compute
- [From discovery] Authentication method
AI Integration (if applicable):
- LangChain for orchestration
- LangGraph for stateful workflows
- Vector DB: Supabase pgvector
Deployment:
- Frontend: Vercel
- Backend: [From discovery] Supabase/Railway/Cloud Run
- CI/CD: GitHub Actions
REQUIREMENTS FROM DISCOVERY:
1. [Specific requirement from discovery phase]
2. [Another requirement]
3. Create claude.md with project overview
4. Create plan.md with phased implementation
5. Each phase independently testable
6. Use battle-tested OSS libraries
7. Include comprehensive error handling
8. [RTL support if needed from discovery]
9. [Admin panel if needed]
10. [CMS integration if needed]
DESIGN SYSTEM (FROM DISCOVERY):
- Brand Colors: [From brand guidelines]
- Typography: [From brand guidelines]
- Style: [From moodboard]
- Components: [From UI research]
- Responsive: Mobile-first (320px min)
- RTL Support: [Yes/No based on discovery]
- Accessibility: WCAG 2.1 [AA/AAA]
USER FLOWS (FROM DISCOVERY):
1. [Primary user flow]
2. [Secondary user flow]
3. [Admin flow if applicable]
Start by creating the planning documents incorporating all discovery findings.
Add [FEATURE] to existing project:
CONTEXT FROM DISCOVERY:
- User Type: [Who will use this feature]
- Priority: [Critical/High/Medium/Low]
- Dependencies: [Related features]
Current Stack: [List your stack]
Feature Requirements:
- [Requirement from user journey mapping]
- [Technical requirement]
- [Design requirement from moodboard]
Follow existing patterns in:
- [Reference file 1]
- [Reference file 2]
Include:
- Error handling for [specific edge cases from discovery]
- Loading states
- Mobile responsiveness ([specific breakpoints])
- [RTL support if project requires]
- Tests for critical paths
- Analytics events for [KPIs from discovery]
Debug this issue:
CONTEXT:
- User Type: [Who encountered this]
- Frequency: [How often it occurs]
- Impact: [Business impact]
Error: [exact error message]
File: [path/to/file:line_number]
When: [User journey step where it occurs]
Environment: [Dev/Staging/Prod]
Code: [relevant code snippet]
Attempted Solutions:
1. [What you tried]
2. [Another attempt]
Related Discovery Context:
- [Any relevant requirement]
- [Performance constraint]
Provide root cause and solution.
📄 Planning Documents (Enhanced)
- claude.md Template
- plan.md Template
Comprehensive Project Configuration
This template incorporates all findings from your discovery phase
# Project: [Project Name]
## Executive Summary
[2-3 sentences from discovery phase findings]
## Discovery Phase Summary
- Platform Type: [Public/Private/Internal]
- Target Market: [Geographic/Demographic]
- Scale Expectations: [User numbers, data volume]
- Compliance Requirements: [GDPR/HIPAA/etc]
## Target Users & Use Cases
- Primary: [From discovery user research]
- Secondary: [From discovery]
- Key Use Cases:
1. [From user journey mapping]
2. [From user journey mapping]
## Tech Stack (EXPLICIT - LOCKED FROM DISCOVERY)
### Frontend
- Framework: Next.js 14.x (app router)
- Language: TypeScript 5.x (strict)
- Styling: Tailwind CSS 3.x + shadcn/ui
- State: Zustand + React Query
- Forms: react-hook-form + zod
- Testing: Vitest + Playwright
- [Additional from discovery]
### Backend
- Platform: [From technical discovery]
- API: [REST/GraphQL/tRPC based on needs]
- Database: [From data requirements]
- Auth: [From user management discovery]
- CMS: [If needed from content discovery]
- Testing: Jest + Supertest
### Infrastructure
- Hosting: [From performance requirements]
- CDN: [Based on geographic needs]
- Monitoring: Sentry + [Analytics choice]
- CI/CD: GitHub Actions
## Design System (FROM BRAND GUIDELINES)
- Colors: [Exact hex values from discovery]
- Typography: [Font families from brand]
- Spacing: [Grid system from design tokens]
- Components: [Component library choices]
- Style: [From moodboard research]
- RTL: [Required/Optional from discovery]
- Mobile First: 320px minimum
## User Management (FROM DISCOVERY)
- Authentication: [Methods from discovery]
- Roles: [From permission matrix]
- Permissions: [Granular permissions]
- Data Privacy: [GDPR compliance needs]
## Content Management (FROM DISCOVERY)
- CMS Type: [Headless/Traditional/None]
- Editors: [Who edits content]
- Workflow: [Publishing workflow]
- Localization: [Language requirements]
## Constraints & Guidelines
1. [From discovery phase]
2. Performance budget: [From technical discovery]
3. Browser support: [From audience analysis]
4. Accessibility: [WCAG level from discovery]
5. Security: [Compliance requirements]
6. SEO: [If public platform]
7. Analytics: [KPI tracking needs]
## Success Metrics (FROM BUSINESS REQUIREMENTS)
- Technical:
- [From performance budget]
- [From scaling requirements]
- Business:
- [From stakeholder interviews]
- [From KPI definitions]
## Development Principles
1. Ship small, ship often
2. Test critical paths (from user journey)
3. Document decisions, not code
4. Follow design system strictly
5. Accessibility-first development
Download template: Create a
plan.md file in your project root with phased implementation details.Template Structure:
Implementation Plan
Phase 0: Foundation & Setup (4-8 hours)
Objective: Establish development environment aligned with discovery findings
Environment Setup
- Initialize Next.js 14 with TypeScript strict mode
pnpm create next-app@latest --typescript --tailwind --app - Configure environment variables
- Create .env.local with all service credentials
- Create .env.example for documentation
- Set up .env.vault for team sharing
Core Dependencies
- Install discovered requirements
# Core pnpm add @supabase/supabase-js zustand @tanstack/react-query # UI from discovery pnpm add [specific libraries from moodboard] # Utils pnpm add date-fns zod react-hook-form # Dev pnpm add -D @types/node prettier eslint-config-prettier
Design System Setup
- Set up shadcn/ui with brand colors
pnpm dlx shadcn-ui@latest init - Configure Tailwind with design tokens
- Import brand fonts
- Set up color palette from discovery
- Configure spacing system
Project Structure
- Create folder structure
/app /(auth) # Auth routes /(dashboard) # Protected routes /(public) # Public routes /api # API routes /components /ui # Base components /features # Feature components /layouts # Layout components /lib /supabase # Supabase client /utils # Utilities /hooks # Custom hooks /types # TypeScript types /store # Zustand stores /styles # Global styles /public /fonts # Brand fonts /images # Optimized images
Infrastructure Setup
- Initialize Git with comprehensive .gitignore
- Set up Prettier with team config
- Configure ESLint with strict rules
- Set up Husky for pre-commit hooks
- Create initial CI/CD pipeline
- Set up Sentry for error tracking
- Configure analytics (if needed from discovery)
Phase 1: Authentication & User Management (8-12 hours)
Objective: Implement complete auth system from discovery requirements
Authentication Setup
- Implement chosen auth method from discovery
- Email/password if required
- Social logins if required
- SSO if enterprise
- Magic links if specified
Database Schema
- Create user tables
-- Based on discovery requirements CREATE TABLE profiles ( id UUID PRIMARY KEY, email TEXT UNIQUE, full_name TEXT, avatar_url TEXT, role TEXT, -- Additional fields from discovery created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ ); - Set up RLS policies
- Create indexes for performance
Auth UI Components
- Login page with brand design
- Signup with validation
- Password reset flow
- Email verification
- Two-factor auth (if required)
- Social login buttons
- Loading states
- Error handling
- Success feedback
User Profile Management
- Profile view page
- Profile edit functionality
- Avatar upload
- Account settings
- Notification preferences
- Data export (GDPR)
- Account deletion
Session Management
- Refresh token handling
- Session timeout
- Remember me functionality
- Multi-device sessions
Testing
- Unit tests for auth logic
- E2E tests for auth flows
- Security testing
Phase 2: Core Features (2-4 days per feature)
Objective: Build primary features from user journey mapping
[Feature 1 from Discovery]
- Database schema
- API endpoints
- UI components
- State management
- Error handling
- Loading states
- Tests
[Feature 2 from Discovery]
- Implementation tasks
Admin Panel (if required)
- Admin authentication
- User management
- Content management
- Analytics dashboard
- System settings
CMS Integration (if required)
- Set up chosen CMS
- Content models
- API integration
- Preview functionality
- Publishing workflow
Phase 3: UI Polish & Experience (2-3 days)
Objective: Implement design system and enhance UX
Design System Implementation
- Apply brand colors consistently
- Implement typography scale
- Add glassmorphic effects (if in moodboard)
- Consistent spacing
- Component variations
Responsive Design
- Mobile optimization (320px+)
- Tablet layouts
- Desktop enhancements
- Test on real devices
RTL Support (if required)
- Add RTL stylesheet
- Implement logical properties
- Mirror UI components
- Test with Arabic/Hebrew content
Accessibility
- Keyboard navigation
- Screen reader optimization
- ARIA labels
- Focus management
- Color contrast validation
Performance Optimization
- Implement code splitting
- Optimize images
- Add loading skeletons
- Implement virtual scrolling
- Cache strategies
User Experience
- Micro-interactions
- Smooth transitions
- Optimistic updates
- Offline support
- PWA features
Phase 4: Testing & Quality Assurance (3-5 days)
Objective: Ensure quality meets discovery requirements
Testing Coverage
- Unit tests (60% coverage)
- Integration tests (30% coverage)
- E2E tests for critical paths (10%)
- Performance testing
- Security testing
- Accessibility testing
- Cross-browser testing
- Device testing
Performance Audit
- Lighthouse audit
- Bundle analysis
- Database query optimization
- API performance
- CDN configuration
Security Audit
- Penetration testing
- OWASP compliance
- Data encryption
- API security
- Authentication vulnerabilities
SEO Optimization (if public)
- Meta tags
- Structured data
- Sitemap
- Robots.txt
- Open Graph tags
Phase 5: Deployment & Launch (2-3 days)
Objective: Deploy to production with monitoring
Pre-deployment
- Production environment setup
- Environment variables
- Database migrations
- DNS configuration
- SSL certificates
Deployment
- Deploy to Vercel/chosen platform
- Configure auto-scaling
- Set up CDN
- Configure backups
- Set up monitoring
Post-deployment
- Smoke tests
- Performance monitoring
- Error tracking
- Analytics verification
- User acceptance testing
Documentation
- API documentation
- User guide
- Admin guide
- Deployment guide
- Troubleshooting guide
Success Criteria per Phase
- Phase 0: Development environment operational
- Phase 1: Authentication system complete
- Phase 2: Core features functional
- Phase 3: UI polished and responsive
- Phase 4: All tests passing, performance targets met
- Phase 5: Successfully deployed with monitoring
Next Step
With planning documents ready, proceed to frontend implementation patterns →