> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weventures.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Planning Documents

> Master claude.md and plan.md templates for structured development

# 📄 Planning Documents - The Foundation of Success

<Info>
  Use these templates as your starting point, customizing based on your discovery phase findings
</Info>

## 🏗️ Master Prompt Template

<CodeGroup>
  ```text Complete Project Initialization theme={null}
  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.
  ```

  ```text Feature Addition with Context theme={null}
  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]
  ```

  ```text Debugging with Full Context theme={null}
  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.
  ```
</CodeGroup>

***

## 📄 Planning Documents (Enhanced)

<Tabs>
  <Tab title="claude.md Template">
    <Card title="Comprehensive Project Configuration" icon="file-code">
      <Note>
        This template incorporates all findings from your discovery phase
      </Note>

      ```markdown theme={null}
      # 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
      ```
    </Card>
  </Tab>

  <Tab title="plan.md Template">
    **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
      ```bash theme={null}
      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
      ```bash theme={null}
      # 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
      ```bash theme={null}
      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
      ```sql theme={null}
      -- 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
  </Tab>
</Tabs>

***

<Card title="Next Step" icon="arrow-right" href="/ai-development/prompting/frontend">
  With planning documents ready, proceed to frontend implementation patterns →
</Card>