ai-coding-starter-kit-codex/CODEX.md

AI Coding Starter Kit - Codex Edition

A Next.js template with an AI-powered development workflow optimized for Codex CLI.

Tech Stack

• Framework: Next.js 16 (App Router), TypeScript
• Styling: Tailwind CSS + shadcn/ui (copy-paste components)
• Backend: Supabase (PostgreSQL + Auth + Storage) - optional
• Deployment: Vercel
• Validation: Zod + react-hook-form
• State: React useState / Context API

Project Structure

src/
  app/              Pages (Next.js App Router)
  components/
    ui/             shadcn/ui components (NEVER recreate these)
  hooks/            Custom React hooks
  lib/              Utilities (supabase.ts, utils.ts)
features/           Feature specifications (PROJ-X-name.md)
  INDEX.md          Feature status overview
docs/
  PRD.md            Product Requirements Document
  production/       Production guides (Sentry, security, performance)

Codex Workflow

This project uses Codex CLI for autonomous coding. Run commands with codex exec.

Development Phases

1. Requirements

codex exec "Read docs/PRD.md and features/INDEX.md. Then create a detailed feature specification for [your idea] in features/PROJ-X-feature-name.md following the structure in .codex/prompts/requirements.md"

2. Architecture

codex exec "Read the feature spec at features/PROJ-X-feature-name.md. Design the technical architecture and add a Tech Design section to the spec file. Focus on: component structure, API design, database schema, and implementation order."

3. Frontend

codex exec "Read features/INDEX.md and the feature spec. Implement the UI components using React, Next.js, Tailwind CSS, and shadcn/ui. Install missing shadcn components with: npx shadcn@latest add <component-name>. Write tests next to source files."

4. Backend

codex exec "Read the feature spec Tech Design section. Build the API endpoints, database migrations, and RLS policies. Use Supabase client from src/lib/supabase.ts. Write tests for all endpoints."

5. QA

codex exec "Read the feature spec's acceptance criteria. Test the implementation against each criterion. Run: npm test for unit tests, npm run test:e2e for E2E tests. Fix any failures."

6. Deploy

codex exec "Deploy to Vercel: vercel --prod. Run production checks: npm run build, npm run lint. Verify deployment at the provided URL."

Feature Tracking

All features tracked in features/INDEX.md. Feature specs live in features/PROJ-X-name.md.

Key Conventions

• Feature IDs: PROJ-1, PROJ-2, etc. (sequential)
• Commits: feat(PROJ-X): description, fix(PROJ-X): description
• Single Responsibility: One feature per spec file
• shadcn/ui first: NEVER create custom versions of installed shadcn components
• Tests: Unit tests co-located next to source files (useHook.test.ts next to useHook.ts)

Build & Test Commands

npm run dev          # Development server (localhost:3000)
npm run build        # Production build
npm run lint         # ESLint
npm run start        # Production server
npm test             # Vitest unit/integration tests
npm run test:e2e     # Playwright E2E tests
npm run test:all     # Both test suites

Codex Modes

Mode	Use Case
--full-auto	Autonomous work with auto-approval (recommended for feature development)
--yolo	No sandbox, no approvals (fastest, use for refactoring/quick fixes)
Default (interactive)	Ask for approval before each change

Example Workflows

Create new feature from scratch

codex exec --full-auto "Initialize the project: read docs/PRD.md to understand the project, then create a feature spec for the login feature in features/PROJ-1-login.md"

Implement and test a feature

codex exec --full-auto "Implement the feature described in features/PROJ-1-login.md. Build the UI, backend, and tests. Verify with npm test."

Review and fix issues

codex exec --full-auto "Run npm test and npm run lint. Fix all issues found."

Prompts Directory

See .codex/prompts/ for pre-built prompts for each development phase.