# 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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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

```bash
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
```bash
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
```bash
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
```bash
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.