madgerm
358ee34457
- Replaced .claude/ with .codex/ directory structure - Created CODEX.md as root instructions for Codex - Added .codex/prompts/ with templates for each development phase - Added .codex/config/project.md for project configuration - Removed .claude/agents/ (not compatible with Codex) - Updated features/INDEX.md and docs/PRD.md references
118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
# 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.
|