> ## 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.

# New Project Workflow

> Complete process from discovery to deployment

## Overview

Our structured approach to delivering new projects from initial client contact through production deployment.

<Steps>
  <Step title="Intake & Discovery">
    Understand goals, constraints, and success metrics
  </Step>

  <Step title="Proposal">
    Technical and design specifications with roadmap
  </Step>

  <Step title="AI-Assisted Planning">
    Create driver documents for guided development
  </Step>

  <Step title="Environment Setup">
    Repository, CI/CD, and hosting configuration
  </Step>

  <Step title="Build Loop">
    Iterative development with AI assistance
  </Step>

  <Step title="QA & Security">
    Testing, accessibility, and performance checks
  </Step>

  <Step title="Deploy & Operate">
    Production deployment with monitoring
  </Step>
</Steps>

## Phase 0: Intake & Discovery

<Tabs>
  <Tab title="Kickoff Calls">
    ### Capture Requirements

    * Project goals and outcomes
    * Target audience
    * Success metrics and KPIs
    * Technical constraints
    * Integration requirements
    * Timeline and budget
  </Tab>

  <Tab title="Brief Documentation">
    ### Document Context

    * Problem statement
    * Expected outcomes
    * Stakeholder map
    * Data sources
    * Content ownership
    * Compliance requirements
  </Tab>

  <Tab title="Risk Assessment">
    ### Identify Blockers

    * Technical feasibility
    * Compliance needs
    * Data residency
    * Licensing issues
    * Resource availability
    * Dependencies
  </Tab>
</Tabs>

## Phase 1: Proposal

### Technical & Design Specification

<CardGroup cols={2}>
  <Card title="Feature List" icon="list-check">
    Detailed features with acceptance criteria
  </Card>

  <Card title="Architecture" icon="diagram-project">
    Stack selection with justification
  </Card>

  <Card title="UI/UX Design" icon="palette">
    Moodboards and component palette
  </Card>

  <Card title="Roadmap" icon="map">
    Phased milestones with estimates
  </Card>
</CardGroup>

### Stack Decision Framework

<Accordion title="Choose Framer When...">
  * Pure marketing/landing pages
  * Strong visual requirements
  * No backend logic needed
  * Fast turnaround required
</Accordion>

<Accordion title="Choose Next.js When...">
  * Custom authentication required
  * Database integration needed
  * Complex business logic
  * API development
  * Real-time features
</Accordion>

## Phase 2: AI-Assisted Planning

### Create Driver Documents

<CodeGroup>
  ```markdown claude.md theme={null}
  # Project: [Name]

  ## Scope
  [2-3 sentence summary]

  ## Tech Stack (EXPLICIT)
  - Frontend: Next.js 14, shadcn/ui, Tailwind
  - Backend: Supabase, Edge Functions
  - AI: LangChain, LangGraph
  - Deploy: Vercel

  ## Constraints
  - Use battle-tested OSS libraries
  - Avoid custom logic unless necessary
  - Plan atomic, testable phases

  ## Target Users
  [Who and why]

  ## KPIs
  - [Metric 1]
  - [Metric 2]
  ```

  ```markdown plan.md theme={null}
  # Implementation Plan

  ## Phase 0: Foundation
  - [ ] Scaffold Next.js project
  - [ ] Configure environments
  - [ ] Set up CI/CD pipeline
  - [ ] Initialize Sentry

  ## Phase 1: Core Features
  - [ ] Auth flow with Supabase
  - [ ] Database schema
  - [ ] Seed data
  - [ ] Basic UI shell

  ## Phase 2: Business Logic
  - [ ] [Feature-specific tasks]

  ## Phase 3: Polish
  - [ ] E2E tests
  - [ ] Performance optimization
  - [ ] Documentation
  ```

  ```markdown agents.md theme={null}
  # Agent Roles

  ## Claude Code (CC)
  - Planning & code generation
  - Architecture decisions

  ## Codex
  - Code review
  - Refactoring suggestions
  - Security audits

  ## Runner
  - Execute commands
  - Capture logs

  ## Docs Agent
  - Fetch examples
  - Best practices
  ```
</CodeGroup>

<Tip>
  **Pro tip**: Use prompt boosters in Claude Code: `ultrathink`, `think deeply`, `think` for complex reasoning
</Tip>

## Phase 3: Repository Setup

<Steps>
  <Step title="Initialize Repository">
    ```bash theme={null}
    git init
    pnpm init
    pnpm add next react react-dom
    ```
  </Step>

  <Step title="Configure Tooling">
    ```bash theme={null}
    # Linting & formatting
    pnpm add -D eslint prettier husky lint-staged

    # Testing
    pnpm add -D vitest @testing-library/react playwright
    ```
  </Step>

  <Step title="CI/CD Pipeline">
    ```yaml theme={null}
    # .github/workflows/ci.yml
    name: CI
    on: [push, pull_request]
    jobs:
      test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - uses: actions/setup-node@v3
          - run: pnpm install
          - run: pnpm typecheck
          - run: pnpm lint
          - run: pnpm test
          - run: pnpm build
    ```
  </Step>

  <Step title="Environment Configuration">
    ```bash theme={null}
    # Create .env.example
    NEXT_PUBLIC_SUPABASE_URL=
    NEXT_PUBLIC_SUPABASE_ANON_KEY=
    SUPABASE_SERVICE_KEY=
    SENTRY_DSN=
    ```
  </Step>
</Steps>

## Phase 4: Build Loop

### Human-in-the-Loop Development

<Tabs>
  <Tab title="1. Branch">
    ```bash theme={null}
    # Feature branches
    git checkout -b feat/user-auth

    # Keep scope small
    # Aim for <300 lines per PR
    ```
  </Tab>

  <Tab title="2. Generate">
    ### Claude Code

    ```text theme={null}
    Based on plan.md Phase 1, generate:
    - Supabase auth components
    - Protected route middleware
    - Login/register pages
    - Session management
    ```
  </Tab>

  <Tab title="3. Run & Debug">
    ```bash theme={null}
    pnpm dev

    # Feed errors back to CC:
    "Getting error: [paste error]
    Current code: [paste code]"
    ```
  </Tab>

  <Tab title="4. Review">
    ### Codex Review

    ```text theme={null}
    Review this diff for:
    - Security vulnerabilities
    - Performance issues
    - Missing edge cases
    - Test coverage

    [paste git diff]
    ```
  </Tab>

  <Tab title="5. Test">
    ```bash theme={null}
    # Write tests
    pnpm test
    pnpm test:e2e

    # Update validations
    # Add Zod schemas
    ```
  </Tab>

  <Tab title="6. Commit">
    ```bash theme={null}
    # Conventional commits
    git add .
    git commit -m "feat: add auth flow"

    # Open PR early
    gh pr create
    ```
  </Tab>
</Tabs>

## Phase 5: QA & Security

<CardGroup>
  <Card title="Security Checklist" icon="shield">
    * Server-side auth checks
    * RLS policies in Supabase
    * Input validation (Zod)
    * Rate limiting
    * Secrets management
  </Card>

  <Card title="Accessibility" icon="universal-access">
    * Semantic HTML
    * ARIA roles
    * Keyboard navigation
    * Color contrast
    * Screen reader testing
  </Card>

  <Card title="Performance" icon="gauge-high">
    * Image optimization
    * Code splitting
    * Edge caching
    * Bundle size budgets
    * Core Web Vitals
  </Card>
</CardGroup>

## Phase 6: Deploy & Operate

### Deployment Pipeline

<Steps>
  <Step title="Merge to Main">
    CI runs full test suite
  </Step>

  <Step title="Preview Deploy">
    Automatic preview on Vercel
  </Step>

  <Step title="Production Checks">
    Smoke tests, performance validation
  </Step>

  <Step title="Production Deploy">
    Promote preview to production
  </Step>

  <Step title="Monitor">
    Check Sentry, logs, analytics
  </Step>
</Steps>

### Monitoring Setup

<Accordion title="Error Tracking">
  ```typescript theme={null}
  // sentry.client.config.ts
  import * as Sentry from "@sentry/nextjs"

  Sentry.init({
    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
    tracesSampleRate: 0.1,
    environment: process.env.NODE_ENV
  })
  ```
</Accordion>

<Accordion title="Analytics">
  ```html theme={null}
  <!-- Plausible -->
  <script
    defer
    data-domain="yourdomain.com"
    src="https://plausible.io/js/script.js">
  </script>
  ```
</Accordion>

## Definition of Done

<Checklist>
  <Check>All acceptance criteria met</Check>
  <Check>Tests pass (unit + E2E)</Check>
  <Check>Code reviewed (Codex + human)</Check>
  <Check>Documentation updated</Check>
  <Check>Sentry integration clean</Check>
  <Check>Performance budgets met</Check>
  <Check>Accessibility audit passed</Check>
  <Check>Security review completed</Check>
</Checklist>

## Common Patterns

<CardGroup cols={2}>
  <Card title="Auth Pattern" icon="lock" href="/patterns/authentication">
    Supabase Auth with RLS
  </Card>

  <Card title="API Pattern" icon="plug" href="/patterns/api">
    Next.js Route Handlers with Zod
  </Card>

  <Card title="Data Fetching" icon="download" href="/patterns/data">
    React Query with Suspense
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/patterns/errors">
    Error boundaries and fallbacks
  </Card>
</CardGroup>