New Project Workflow

Overview

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

Intake & Discovery

Understand goals, constraints, and success metrics

Proposal

Technical and design specifications with roadmap

AI-Assisted Planning

Create driver documents for guided development

Environment Setup

Repository, CI/CD, and hosting configuration

Build Loop

Iterative development with AI assistance

QA & Security

Testing, accessibility, and performance checks

Deploy & Operate

Production deployment with monitoring

Phase 0: Intake & Discovery

Kickoff Calls
Brief Documentation
Risk Assessment

Capture Requirements

Project goals and outcomes
Target audience
Success metrics and KPIs
Technical constraints
Integration requirements
Timeline and budget

Phase 1: Proposal

Technical & Design Specification

Feature List

Detailed features with acceptance criteria

Architecture

Stack selection with justification

UI/UX Design

Moodboards and component palette

Roadmap

Phased milestones with estimates

Stack Decision Framework

Choose Framer When...

Pure marketing/landing pages
Strong visual requirements
No backend logic needed
Fast turnaround required

Choose Next.js When...

Custom authentication required
Database integration needed
Complex business logic
API development
Real-time features

Phase 2: AI-Assisted Planning

Create Driver Documents

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

# 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

# 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

Pro tip: Use prompt boosters in Claude Code: ultrathink, think deeply, think for complex reasoning

Phase 3: Repository Setup

Initialize Repository

git init
pnpm init
pnpm add next react react-dom

Configure Tooling

# Linting & formatting
pnpm add -D eslint prettier husky lint-staged

# Testing
pnpm add -D vitest @testing-library/react playwright

CI/CD Pipeline

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

Environment Configuration

# Create .env.example
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_KEY=
SENTRY_DSN=

Phase 4: Build Loop

Human-in-the-Loop Development

# Feature branches
git checkout -b feat/user-auth

# Keep scope small
# Aim for <300 lines per PR

Claude Code

Based on plan.md Phase 1, generate:
- Supabase auth components
- Protected route middleware
- Login/register pages
- Session management

pnpm dev

# Feed errors back to CC:
"Getting error: [paste error]
Current code: [paste code]"

Codex Review

Review this diff for:
- Security vulnerabilities
- Performance issues
- Missing edge cases
- Test coverage

[paste git diff]

# Write tests
pnpm test
pnpm test:e2e

# Update validations
# Add Zod schemas

# Conventional commits
git add .
git commit -m "feat: add auth flow"

# Open PR early
gh pr create

Phase 5: QA & Security

Security Checklist

Server-side auth checks
RLS policies in Supabase
Input validation (Zod)
Rate limiting
Secrets management

Accessibility

Semantic HTML
ARIA roles
Keyboard navigation
Color contrast
Screen reader testing

Performance

Image optimization
Code splitting
Edge caching
Bundle size budgets
Core Web Vitals

Phase 6: Deploy & Operate

Deployment Pipeline

Merge to Main

CI runs full test suite

Preview Deploy

Automatic preview on Vercel

Production Checks

Smoke tests, performance validation

Production Deploy

Promote preview to production

Monitor

Check Sentry, logs, analytics

Monitoring Setup

Error Tracking

// 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
})

Analytics

<!-- Plausible -->
<script
  defer
  data-domain="yourdomain.com"
  src="https://plausible.io/js/script.js">
</script>

Development Process

CI/CD

Overview

Phase 0: Intake & Discovery

Capture Requirements

Document Context

Identify Blockers

Phase 1: Proposal

Technical & Design Specification

Feature List

Architecture

UI/UX Design

Roadmap

Stack Decision Framework

Phase 2: AI-Assisted Planning

Create Driver Documents

Phase 3: Repository Setup

Phase 4: Build Loop

Human-in-the-Loop Development

Claude Code

Codex Review

Phase 5: QA & Security

Security Checklist

Accessibility

Performance

Phase 6: Deploy & Operate

Deployment Pipeline

Monitoring Setup

Definition of Done

Common Patterns

Auth Pattern

API Pattern

Data Fetching

Error Handling

​Overview

​Phase 0: Intake & Discovery

​Capture Requirements

​Document Context

​Identify Blockers

​Phase 1: Proposal

​Technical & Design Specification

Feature List

Architecture

UI/UX Design

Roadmap

​Stack Decision Framework

​Phase 2: AI-Assisted Planning

​Create Driver Documents

​Phase 3: Repository Setup

​Phase 4: Build Loop

​Human-in-the-Loop Development

​Claude Code

​Codex Review

​Phase 5: QA & Security

Security Checklist

Accessibility

Performance

​Phase 6: Deploy & Operate

​Deployment Pipeline

​Monitoring Setup

​Definition of Done

​Common Patterns

Auth Pattern

API Pattern

Data Fetching

Error Handling

Overview

Phase 0: Intake & Discovery

Capture Requirements

Document Context

Identify Blockers

Phase 1: Proposal

Technical & Design Specification

Stack Decision Framework

Phase 2: AI-Assisted Planning

Create Driver Documents

Phase 3: Repository Setup

Phase 4: Build Loop

Human-in-the-Loop Development

Claude Code

Codex Review

Phase 5: QA & Security

Phase 6: Deploy & Operate

Deployment Pipeline

Monitoring Setup

Definition of Done

Common Patterns