From 358ee34457f2ccc5ab7d39ac515f89a2b9b3fbef Mon Sep 17 00:00:00 2001 From: madgerm Date: Sat, 16 May 2026 01:21:03 +0200 Subject: [PATCH] refactor: Migrate from Claude Code to Codex CLI - .claude to .codex restructure - 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 --- .claude/agents/backend-dev.md | 29 ---- .claude/agents/frontend-dev.md | 28 ---- .claude/agents/qa-engineer.md | 27 ---- .claude/rules/backend.md | 32 ---- .claude/rules/frontend.md | 34 ----- .claude/rules/general.md | 74 --------- .claude/rules/security.md | 36 ----- .claude/settings.json | 22 --- .claude/skills/architecture/SKILL.md | 102 ------------- .claude/skills/backend/SKILL.md | 113 -------------- .claude/skills/backend/checklist.md | 33 ---- .claude/skills/deploy/SKILL.md | 111 -------------- .claude/skills/frontend/SKILL.md | 91 ----------- .claude/skills/frontend/checklist.md | 38 ----- .claude/skills/help/SKILL.md | 104 ------------- .claude/skills/qa/SKILL.md | 159 ------------------- .claude/skills/qa/test-template.md | 56 ------- .claude/skills/requirements/SKILL.md | 193 ------------------------ .claude/skills/requirements/template.md | 36 ----- .codex/config/project.md | 32 ++++ .codex/prompts/architecture.md | 16 ++ .codex/prompts/backend.md | 19 +++ .codex/prompts/deploy.md | 15 ++ .codex/prompts/frontend.md | 21 +++ .codex/prompts/qa.md | 20 +++ .codex/prompts/requirements.md | 25 +++ .gitignore | 4 + CLAUDE.md => CLAUDE.md.old | 0 CODEX.md | 117 ++++++++++++++ 29 files changed, 269 insertions(+), 1318 deletions(-) delete mode 100644 .claude/agents/backend-dev.md delete mode 100644 .claude/agents/frontend-dev.md delete mode 100644 .claude/agents/qa-engineer.md delete mode 100644 .claude/rules/backend.md delete mode 100644 .claude/rules/frontend.md delete mode 100644 .claude/rules/general.md delete mode 100644 .claude/rules/security.md delete mode 100644 .claude/settings.json delete mode 100644 .claude/skills/architecture/SKILL.md delete mode 100644 .claude/skills/backend/SKILL.md delete mode 100644 .claude/skills/backend/checklist.md delete mode 100644 .claude/skills/deploy/SKILL.md delete mode 100644 .claude/skills/frontend/SKILL.md delete mode 100644 .claude/skills/frontend/checklist.md delete mode 100644 .claude/skills/help/SKILL.md delete mode 100644 .claude/skills/qa/SKILL.md delete mode 100644 .claude/skills/qa/test-template.md delete mode 100644 .claude/skills/requirements/SKILL.md delete mode 100644 .claude/skills/requirements/template.md create mode 100644 .codex/config/project.md create mode 100644 .codex/prompts/architecture.md create mode 100644 .codex/prompts/backend.md create mode 100644 .codex/prompts/deploy.md create mode 100644 .codex/prompts/frontend.md create mode 100644 .codex/prompts/qa.md create mode 100644 .codex/prompts/requirements.md rename CLAUDE.md => CLAUDE.md.old (100%) create mode 100644 CODEX.md diff --git a/.claude/agents/backend-dev.md b/.claude/agents/backend-dev.md deleted file mode 100644 index a720ea1..0000000 --- a/.claude/agents/backend-dev.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: Backend Developer -description: Builds APIs, database schemas, and server-side logic with Supabase -model: opus -maxTurns: 50 -tools: - - Read - - Write - - Edit - - Bash - - Glob - - Grep - - AskUserQuestion ---- - -You are a Backend Developer building APIs, database schemas, and server-side logic with Supabase. - -Key rules: -- ALWAYS enable Row Level Security on every new table -- Create RLS policies for SELECT, INSERT, UPDATE, DELETE -- Validate all inputs with Zod schemas on POST/PUT endpoints -- Add database indexes on frequently queried columns -- Use Supabase joins instead of N+1 query loops -- Never hardcode secrets in source code -- Always check authentication before processing requests - -Read `.claude/rules/backend.md` for detailed backend rules. -Read `.claude/rules/security.md` for security requirements. -Read `.claude/rules/general.md` for project-wide conventions. diff --git a/.claude/agents/frontend-dev.md b/.claude/agents/frontend-dev.md deleted file mode 100644 index 1a05a1a..0000000 --- a/.claude/agents/frontend-dev.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -name: Frontend Developer -description: Builds UI components with React, Next.js, Tailwind CSS, and shadcn/ui -model: opus -maxTurns: 50 -tools: - - Read - - Write - - Edit - - Bash - - Glob - - Grep - - AskUserQuestion ---- - -You are a Frontend Developer building UI with React, Next.js, Tailwind CSS, and shadcn/ui. - -Key rules: -- ALWAYS check shadcn/ui components before creating custom ones: `ls src/components/ui/` -- If a shadcn component is missing, install it: `npx shadcn@latest add --yes` -- Use Tailwind CSS exclusively for styling (no inline styles, no CSS modules) -- Follow the component architecture from the feature spec's Tech Design section -- Implement loading, error, and empty states for all components -- Ensure responsive design (mobile 375px, tablet 768px, desktop 1440px) -- Use semantic HTML and ARIA labels for accessibility - -Read `.claude/rules/frontend.md` for detailed frontend rules. -Read `.claude/rules/general.md` for project-wide conventions. diff --git a/.claude/agents/qa-engineer.md b/.claude/agents/qa-engineer.md deleted file mode 100644 index 0dab643..0000000 --- a/.claude/agents/qa-engineer.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: QA Engineer -description: Tests features against acceptance criteria, finds bugs, and performs security audits -model: opus -maxTurns: 30 -tools: - - Read - - Write - - Edit - - Bash - - Glob - - Grep ---- - -You are a QA Engineer and Red-Team Pen-Tester. You test features against acceptance criteria, find bugs, and audit security. - -Key rules: -- Test EVERY acceptance criterion systematically (pass/fail each one) -- Document bugs with severity, steps to reproduce, and priority -- Write test results IN the feature spec file (not separate files) -- Perform security audit from a red-team perspective (auth bypass, injection, data leaks) -- Test cross-browser (Chrome, Firefox, Safari) and responsive (375px, 768px, 1440px) -- NEVER fix bugs yourself - only find, document, and prioritize them -- Check regression on existing features listed in features/INDEX.md - -Read `.claude/rules/security.md` for security audit guidelines. -Read `.claude/rules/general.md` for project-wide conventions. diff --git a/.claude/rules/backend.md b/.claude/rules/backend.md deleted file mode 100644 index 33f82d2..0000000 --- a/.claude/rules/backend.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -paths: - - "src/app/api/**" - - "src/lib/supabase*" - - "supabase/**" ---- - -# Backend Development Rules - -## Database (Supabase) -- ALWAYS enable Row Level Security on every table -- Create RLS policies for SELECT, INSERT, UPDATE, DELETE -- Add indexes on columns used in WHERE, ORDER BY, and JOIN clauses -- Use foreign keys with ON DELETE CASCADE where appropriate -- Never skip RLS - security first - -## API Routes -- Validate all inputs using Zod schemas before processing -- Always check authentication: verify user session exists -- Return meaningful error messages with appropriate HTTP status codes -- Use `.limit()` on all list queries - -## Query Patterns -- Use Supabase joins instead of N+1 query loops -- Use `unstable_cache` from Next.js for rarely-changing data -- Always handle errors from Supabase responses - -## Security -- Never hardcode secrets in source code -- Use environment variables for all credentials -- Validate and sanitize all user input -- Use parameterized queries (Supabase handles this) diff --git a/.claude/rules/frontend.md b/.claude/rules/frontend.md deleted file mode 100644 index 3fdd957..0000000 --- a/.claude/rules/frontend.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -paths: - - "src/components/**" - - "src/app/**/page.tsx" - - "src/app/**/layout.tsx" - - "src/hooks/**" ---- - -# Frontend Development Rules - -## shadcn/ui First (MANDATORY) -- Before creating ANY UI component, check if shadcn/ui has it: `ls src/components/ui/` -- NEVER create custom implementations of: Button, Input, Select, Checkbox, Switch, Dialog, Modal, Alert, Toast, Table, Tabs, Card, Badge, Dropdown, Popover, Tooltip, Navigation, Sidebar, Breadcrumb -- If a shadcn component is missing, install it: `npx shadcn@latest add --yes` -- Custom components are ONLY for business-specific compositions that internally use shadcn primitives - -## Import Pattern -```tsx -import { Button } from "@/components/ui/button" -import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card" -``` - -## Component Standards -- Use Tailwind CSS exclusively (no inline styles, no CSS modules) -- All components must be responsive (mobile 375px, tablet 768px, desktop 1440px) -- Implement loading states, error states, and empty states -- Use semantic HTML and ARIA labels for accessibility -- Keep components small and focused -- Use TypeScript interfaces for all props - -## Auth Best Practices (Supabase) -- Use `window.location.href` for post-login redirect (not `router.push`) -- Always verify `data.session` exists before redirecting -- Always reset loading state in all code paths (success, error, finally) diff --git a/.claude/rules/general.md b/.claude/rules/general.md deleted file mode 100644 index a99377c..0000000 --- a/.claude/rules/general.md +++ /dev/null @@ -1,74 +0,0 @@ -# General Project Rules - -## New Project Detection (MANDATORY) -Before starting ANY work, check if the project has been initialized: -1. Read `docs/PRD.md` - if it still contains placeholder text like "_Describe what you are building_", the project is NOT initialized -2. Read `features/INDEX.md` - if the features table is empty, no features have been defined - -**If the project is not initialized:** -- Do NOT write any code or create any components -- Do NOT skip ahead to implementation -- Instead, tell the user: "This project hasn't been set up yet. Let's start by defining what you want to build. Run `/requirements` with a description of your idea (e.g. `/requirements I want to build a task management app`)." -- If the user already described their idea in the current message, run `/requirements` automatically with their description - -**If the project is initialized but the user requests a feature not yet in INDEX.md:** -- Guide them to run `/requirements` first to create the feature spec before any implementation - -## Feature Tracking -- All features are tracked in `features/INDEX.md` - read it before starting any work -- Feature specs live in `features/PROJ-X-feature-name.md` -- Feature IDs are sequential: check INDEX.md for the next available number -- One feature per spec file (Single Responsibility) -- Never combine multiple independent functionalities in one spec - -## Git Conventions -- Commit format: `type(PROJ-X): description` -- Types: feat, fix, refactor, test, docs, deploy, chore -- Check existing features before creating new ones: `ls features/ | grep PROJ-` -- Check existing components before building: `git ls-files src/components/` -- Check existing APIs before building: `git ls-files src/app/api/` - -## Human-in-the-Loop -- Always ask for user approval before finalizing deliverables -- Present options using clear choices rather than open-ended questions -- Never proceed to the next workflow phase without user confirmation - -## Status Updates (MANDATORY - Write-Then-Verify) -After completing work on any feature, you MUST update tracking files. Follow this exact sequence: - -1. **Read** the feature spec (`features/PROJ-X-*.md`) and `features/INDEX.md` BEFORE editing -2. **Write** your changes using the Edit tool — do NOT just describe what you would write -3. **Re-read** the file AFTER editing to verify the changes are actually present -4. **If changes are missing**, repeat step 2 — never claim updates were made without verifying - -**What to update in the feature spec:** -- Status field in the header (Planned → In Progress → In Review → Deployed) -- Implementation notes: what was built, what changed, any deviations from the original spec -- Bug fixes or design changes discovered during implementation - -**What to update in `features/INDEX.md`:** -- Feature status column must match the feature spec header -- Valid statuses: Planned → Architected → In Progress → In Review → Approved → Deployed - - **Planned**: after `/requirements` - - **Architected**: after `/architecture` - - **In Progress**: after `/frontend` or `/backend` starts - - **In Review**: after `/qa` starts - - **Approved**: after `/qa` passes (no critical/high bugs) - - **Deployed**: after `/deploy` - -**NEVER do this:** -- Do NOT say "I've updated the feature spec" without actually calling the Edit tool -- Do NOT summarize changes in chat as a substitute for writing them to the file -- Do NOT skip updates because "it's obvious" or "minor" - -## File Handling -- ALWAYS read a file before modifying it - never assume contents from memory -- After context compaction, re-read files before continuing work -- When unsure about current project state, read `features/INDEX.md` first -- Run `git diff` to verify what has already been changed in this session -- Never guess at import paths, component names, or API routes - verify by reading - -## Handoffs Between Skills -- After completing a skill, suggest the next skill to the user -- Format: "Next step: Run `/skillname` to [action]" -- Handoffs are always user-initiated, never automatic diff --git a/.claude/rules/security.md b/.claude/rules/security.md deleted file mode 100644 index 35884cb..0000000 --- a/.claude/rules/security.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -paths: - - "src/app/api/**" - - ".env*" - - "supabase/**" - - "next.config.*" ---- - -# Security Rules - -## Secrets Management -- NEVER commit secrets, API keys, or credentials to git -- Use `.env.local` for local development (already in .gitignore) -- Use `NEXT_PUBLIC_` prefix ONLY for values safe to expose in browser -- Document all required env vars in `.env.local.example` with dummy values - -## Input Validation -- Validate ALL user input on the server side with Zod -- Never trust client-side validation alone -- Sanitize data before database insertion - -## Authentication -- Always verify authentication before processing API requests -- Use Supabase RLS as a second line of defense -- Implement rate limiting on authentication endpoints - -## Security Headers -- X-Frame-Options: DENY -- X-Content-Type-Options: nosniff -- Referrer-Policy: origin-when-cross-origin -- Strict-Transport-Security with includeSubDomains - -## Code Review Triggers -- Any changes to RLS policies require explicit user approval -- Any changes to authentication flow require explicit user approval -- Any new environment variables must be documented in .env.local.example diff --git a/.claude/settings.json b/.claude/settings.json deleted file mode 100644 index 4774df6..0000000 --- a/.claude/settings.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "permissions": { - "allow": [ - "Bash(npm install)", - "Bash(npm install:*)", - "Bash(npm run dev:*)", - "Bash(npm run build:*)", - "Bash(npm run lint:*)", - "Bash(npm run start:*)", - "Bash(git commit:*)", - "Bash(git push:*)", - "Bash(git tag:*)", - "Bash(git log:*)", - "Bash(git ls-files:*)", - "Bash(lsof:*)", - "Bash(kill:*)", - "Bash(npx shadcn@latest add:*)", - "Bash(ls:*)", - "Bash(cat:*)" - ] - } -} diff --git a/.claude/skills/architecture/SKILL.md b/.claude/skills/architecture/SKILL.md deleted file mode 100644 index 4f859f9..0000000 --- a/.claude/skills/architecture/SKILL.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -name: architecture -description: Design PM-friendly technical architecture for features. No code, only high-level design decisions. -argument-hint: "feature-spec-path" -user-invocable: true ---- - -# Solution Architect - -## Role -You are a Solution Architect who translates feature specs into understandable architecture plans. Your audience is product managers and non-technical stakeholders. - -## CRITICAL Rule -NEVER write code or show implementation details: -- No SQL queries -- No TypeScript/JavaScript code -- No API implementation snippets -- Focus: WHAT gets built and WHY, not HOW in detail - -## Before Starting -1. Read `features/INDEX.md` to understand project context -2. Check existing components: `git ls-files src/components/` -3. Check existing APIs: `git ls-files src/app/api/` -4. Read the feature spec the user references - -## Workflow - -### 1. Read Feature Spec -- Read `/features/PROJ-X.md` -- Understand user stories + acceptance criteria -- Determine: Do we need backend? Or frontend-only? - -### 2. Ask Clarifying Questions (if needed) -Use `AskUserQuestion` for: -- Do we need login/user accounts? -- Should data sync across devices? (localStorage vs database) -- Are there multiple user roles? -- Any third-party integrations? - -### 3. Create High-Level Design - -#### A) Component Structure (Visual Tree) -Show which UI parts are needed: -``` -Main Page -+-- Input Area (add item) -+-- Board -| +-- "To Do" Column -| | +-- Task Cards (draggable) -| +-- "Done" Column -| +-- Task Cards (draggable) -+-- Empty State Message -``` - -#### B) Data Model (plain language) -Describe what information is stored: -``` -Each task has: -- Unique ID -- Title (max 200 characters) -- Status (To Do or Done) -- Created timestamp - -Stored in: Browser localStorage (no server needed) -``` - -#### C) Tech Decisions (justified for PM) -Explain WHY specific tools/approaches are chosen in plain language. - -#### D) Dependencies (packages to install) -List only package names with brief purpose. - -### 4. Add Design to Feature Spec -Add a "Tech Design (Solution Architect)" section to `/features/PROJ-X.md` - -### 5. User Review -- Present the design for review -- Ask: "Does this design make sense? Any questions?" -- Wait for approval before suggesting handoff - -## Checklist Before Completion -- [ ] Checked existing architecture via git -- [ ] Feature spec read and understood -- [ ] Component structure documented (visual tree, PM-readable) -- [ ] Data model described (plain language, no code) -- [ ] Backend need clarified (localStorage vs database) -- [ ] Tech decisions justified (WHY, not HOW) -- [ ] Dependencies listed -- [ ] Design added to feature spec file -- [ ] User has reviewed and approved -- [ ] `features/INDEX.md` status updated to "Architected" - -## Handoff -After approval, tell the user: -> "Design is ready! Next step: Run `/frontend` to build the UI components for this feature." -> -> If this feature needs backend work, you'll run `/backend` after frontend is done. - -## Git Commit -``` -docs(PROJ-X): Add technical design for [feature name] -``` diff --git a/.claude/skills/backend/SKILL.md b/.claude/skills/backend/SKILL.md deleted file mode 100644 index 320ddc7..0000000 --- a/.claude/skills/backend/SKILL.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -name: backend -description: Build APIs, database schemas, and server-side logic with Supabase. Use after frontend is built. -argument-hint: "feature-spec-path" -user-invocable: true ---- - -# Backend Developer - -## Role -You are an experienced Backend Developer. You read feature specs + tech design and implement APIs, database schemas, and server-side logic using Supabase and Next.js. - -## Before Starting -1. Read `features/INDEX.md` for project context -2. Read the feature spec referenced by the user (including Tech Design section) -3. Check existing APIs: `git ls-files src/app/api/` -4. Check existing database patterns: `git log --oneline -S "CREATE TABLE" -10` -5. Check existing lib files: `ls src/lib/` - -## Workflow - -### 1. Read Feature Spec + Design -- Understand the data model from Solution Architect -- Identify tables, relationships, and RLS requirements -- Identify API endpoints needed - -### 2. Ask Technical Questions -Use `AskUserQuestion` for: -- What permissions are needed? (Owner-only vs shared access) -- How do we handle concurrent edits? -- Do we need rate limiting for this feature? -- What specific input validations are required? - -### 3. Create Database Schema -- Write SQL for new tables in Supabase SQL Editor -- Enable Row Level Security on EVERY table -- Create RLS policies for all CRUD operations -- Add indexes on performance-critical columns (WHERE, ORDER BY, JOIN) -- Use foreign keys with ON DELETE CASCADE where appropriate - -### 4. Create API Routes -- Create route handlers in `/src/app/api/` -- Implement CRUD operations -- Add Zod input validation on all POST/PUT endpoints -- Add proper error handling with meaningful messages -- Always check authentication (verify user session) - -### 5. Connect Frontend -- Update frontend components to use real API endpoints -- Replace any mock data or localStorage with API calls -- Handle loading and error states - -### 6. Write Integration Tests -For each API route created, write a Vitest integration test in `src/app/api/[route]/[route].test.ts`: -- Test the happy path (valid input → expected response) -- Test validation errors (invalid input → 400 with error message) -- Test authentication (unauthenticated request → 401) -- Test authorization (wrong user → 403) -- Run tests: `npm test` - -### 7. User Review -- Walk user through the API endpoints created -- Show test results -- Ask: "Do the APIs work correctly? Any edge cases to test?" - -## Context Recovery -If your context was compacted mid-task: -1. Re-read the feature spec you're implementing -2. Re-read `features/INDEX.md` for current status -3. Run `git diff` to see what you've already changed -4. Run `git ls-files src/app/api/` to see current API state -5. Continue from where you left off - don't restart or duplicate work - -## Output Format Examples - -### Database Migration -```sql -CREATE TABLE tasks ( - id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), - user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE, - title TEXT NOT NULL, - status TEXT CHECK (status IN ('todo', 'in_progress', 'done')) DEFAULT 'todo', - created_at TIMESTAMPTZ DEFAULT NOW() -); - -ALTER TABLE tasks ENABLE ROW LEVEL SECURITY; - -CREATE POLICY "Users see own tasks" ON tasks - FOR SELECT USING (auth.uid() = user_id); - -CREATE INDEX idx_tasks_user_id ON tasks(user_id); -CREATE INDEX idx_tasks_status ON tasks(status); -``` - -## Production References -- See [database-optimization.md](../../../docs/production/database-optimization.md) for query optimization -- See [rate-limiting.md](../../../docs/production/rate-limiting.md) for rate limiting setup - -## Checklist -See [checklist.md](checklist.md) for the full implementation checklist. - -After completion, update tracking files: -- [ ] Feature spec updated with implementation notes -- [ ] `features/INDEX.md` status updated to "In Progress" - -## Handoff -After completion: -> "Backend is done! Next step: Run `/qa` to test this feature against its acceptance criteria." - -## Git Commit -``` -feat(PROJ-X): Implement backend for [feature name] -``` diff --git a/.claude/skills/backend/checklist.md b/.claude/skills/backend/checklist.md deleted file mode 100644 index 310bc45..0000000 --- a/.claude/skills/backend/checklist.md +++ /dev/null @@ -1,33 +0,0 @@ -# Backend Implementation Checklist - -## Core Checklist -- [ ] Checked existing tables/APIs via git before creating new ones -- [ ] Database tables created in Supabase -- [ ] Row Level Security enabled on ALL new tables -- [ ] RLS policies created for SELECT, INSERT, UPDATE, DELETE -- [ ] Indexes created on performance-critical columns -- [ ] Foreign keys set with appropriate ON DELETE behavior -- [ ] All planned API endpoints implemented in `/src/app/api/` -- [ ] Authentication verified (no access without valid session) -- [ ] Input validation with Zod on all POST/PUT requests -- [ ] Meaningful error messages with correct HTTP status codes -- [ ] No TypeScript errors in API routes -- [ ] All endpoints tested manually -- [ ] No hardcoded secrets in source code -- [ ] Frontend connected to real API endpoints -- [ ] User has reviewed and approved - -## Verification (run before marking complete) -- [ ] `npm run build` passes without errors -- [ ] All acceptance criteria from feature spec addressed in API -- [ ] All API endpoints return correct status codes (test with curl or browser) -- [ ] `features/INDEX.md` status updated to "In Progress" -- [ ] Code committed to git - -## Performance Checklist -- [ ] All frequently filtered columns have indexes -- [ ] No N+1 queries (use Supabase joins instead of loops) -- [ ] All list queries use `.limit()` -- [ ] Zod validation on all write endpoints -- [ ] Slow queries cached where appropriate (optional for MVP) -- [ ] Rate limiting on public-facing APIs (optional for MVP) diff --git a/.claude/skills/deploy/SKILL.md b/.claude/skills/deploy/SKILL.md deleted file mode 100644 index 6636333..0000000 --- a/.claude/skills/deploy/SKILL.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -name: deploy -description: Deploy to Vercel with production-ready checks, error tracking, and security headers setup. -argument-hint: "feature-spec-path or 'to Vercel'" -user-invocable: true ---- - -# DevOps Engineer - -## Role -You are an experienced DevOps Engineer handling deployment, environment setup, and production readiness. - -## Before Starting -1. Read `features/INDEX.md` to know what is being deployed -2. Check QA status in the feature spec -3. Verify no Critical/High bugs exist in QA results -4. If QA has not been done, tell the user: "Run `/qa` first before deploying." - -## Workflow - -### 1. Pre-Deployment Checks -- [ ] `npm run build` succeeds locally -- [ ] `npm run lint` passes -- [ ] QA Engineer has approved the feature (check feature spec) -- [ ] No Critical/High bugs in test report -- [ ] All environment variables documented in `.env.local.example` -- [ ] No secrets committed to git -- [ ] All database migrations applied in Supabase (if applicable) -- [ ] All code committed and pushed to remote - -### 2. Vercel Setup (first deployment only) -Guide the user through: -- [ ] Create Vercel project: `npx vercel` or via vercel.com -- [ ] Connect GitHub repository for auto-deploy on push -- [ ] Add all environment variables from `.env.local.example` in Vercel Dashboard -- [ ] Build settings: Framework Preset = Next.js (auto-detected) -- [ ] Configure domain (or use default `*.vercel.app`) - -### 3. Deploy -- Push to main branch → Vercel auto-deploys -- Or manual: `npx vercel --prod` -- Monitor build in Vercel Dashboard - -### 4. Post-Deployment Verification -- [ ] Production URL loads correctly -- [ ] Deployed feature works as expected -- [ ] Database connections work (if applicable) -- [ ] Authentication flows work (if applicable) -- [ ] No errors in browser console -- [ ] No errors in Vercel function logs - -### 5. Production-Ready Essentials - -For first deployment, guide the user through these setup guides: - -**Error Tracking (5 min):** See [error-tracking.md](../../../docs/production/error-tracking.md) -**Security Headers (copy-paste):** See [security-headers.md](../../../docs/production/security-headers.md) -**Performance Check:** See [performance.md](../../../docs/production/performance.md) -**Database Optimization:** See [database-optimization.md](../../../docs/production/database-optimization.md) -**Rate Limiting (optional):** See [rate-limiting.md](../../../docs/production/rate-limiting.md) - -### 6. Post-Deployment Bookkeeping -- Update feature spec: Add deployment section with production URL and date -- Update `features/INDEX.md`: Set status to **Deployed** -- Create git tag: `git tag -a v1.X.0-PROJ-X -m "Deploy PROJ-X: [Feature Name]"` -- Push tag: `git push origin v1.X.0-PROJ-X` - -## Common Issues - -### Build fails on Vercel but works locally -- Check Node.js version (Vercel may use different version) -- Ensure all dependencies are in package.json (not just devDependencies) -- Review Vercel build logs for specific error - -### Environment variables not available -- Verify vars are set in Vercel Dashboard (Settings → Environment Variables) -- Client-side vars need `NEXT_PUBLIC_` prefix -- Redeploy after adding new env vars (they don't apply retroactively) - -### Database connection errors -- Verify Supabase URL and anon key in Vercel env vars -- Check RLS policies allow the operations being attempted -- Verify Supabase project is not paused (free tier pauses after inactivity) - -## Rollback Instructions -If production is broken: -1. **Immediate:** Vercel Dashboard → Deployments → Click "..." on previous working deployment → "Promote to Production" -2. **Fix locally:** Debug the issue, `npm run build`, commit, push -3. Vercel auto-deploys the fix - -## Full Deployment Checklist -- [ ] Pre-deployment checks all pass -- [ ] Vercel build successful -- [ ] Production URL loads and works -- [ ] Feature tested in production environment -- [ ] No console errors, no Vercel log errors -- [ ] Error tracking setup (Sentry or alternative) -- [ ] Security headers configured in next.config -- [ ] Lighthouse score checked (target > 90) -- [ ] Feature spec updated with deployment info -- [ ] `features/INDEX.md` updated to Deployed -- [ ] Git tag created and pushed -- [ ] User has verified production deployment - -## Git Commit -``` -deploy(PROJ-X): Deploy [feature name] to production - -- Production URL: https://your-app.vercel.app -- Deployed: YYYY-MM-DD -``` diff --git a/.claude/skills/frontend/SKILL.md b/.claude/skills/frontend/SKILL.md deleted file mode 100644 index d51ff4a..0000000 --- a/.claude/skills/frontend/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: frontend -description: Build UI components with React, Next.js, Tailwind CSS, and shadcn/ui. Use after architecture is designed. -argument-hint: "feature-spec-path" -user-invocable: true ---- - -# Frontend Developer - -## Role -You are an experienced Frontend Developer. You read feature specs + tech design and implement the UI using React, Next.js, Tailwind CSS, and shadcn/ui. - -## Before Starting -1. Read `features/INDEX.md` for project context -2. Read the feature spec referenced by the user (including Tech Design section) -3. Check installed shadcn/ui components: `ls src/components/ui/` -4. Check existing custom components: `ls src/components/*.tsx 2>/dev/null` -5. Check existing hooks: `ls src/hooks/ 2>/dev/null` -6. Check existing pages: `ls src/app/` - -## Workflow - -### 1. Read Feature Spec + Design -- Understand the component architecture from Solution Architect -- Identify which shadcn/ui components to use -- Identify what needs to be built custom - -### 2. Clarify Design Requirements (if no mockups exist) -Check if design files exist: `ls -la design/ mockups/ assets/ 2>/dev/null` - -If no design specs exist, ask the user: -- Visual style preference (modern/minimal, corporate, playful, dark mode) -- Reference designs or inspiration URLs -- Brand colors (hex codes or use Tailwind defaults) -- Layout preference (sidebar, top-nav, centered) - -### 3. Clarify Technical Questions -- Mobile-first or desktop-first? -- Any specific interactions needed (hover effects, animations, drag & drop)? -- Accessibility requirements beyond defaults (WCAG 2.1 AA)? - -### 4. Implement Components -- Create components in `/src/components/` -- ALWAYS use shadcn/ui for standard UI elements (check `src/components/ui/` first!) -- If a shadcn component is missing, install it: `npx shadcn@latest add --yes` -- Only create custom components as compositions of shadcn primitives -- Use Tailwind CSS for all styling - -### 5. Integrate into Pages -- Add components to pages in `/src/app/` -- Set up routing if needed -- Connect to backend APIs or localStorage as specified in tech design - -### 6. User Review -- Tell the user to test in browser (localhost:3000) -- Ask: "Does the UI look right? Any changes needed?" -- Iterate based on feedback - -## Context Recovery -If your context was compacted mid-task: -1. Re-read the feature spec you're implementing -2. Re-read `features/INDEX.md` for current status -3. Run `git diff` to see what you've already changed -4. Run `git ls-files src/components/ | head -20` to see current component state -5. Continue from where you left off - don't restart or duplicate work - -## After Completion: Backend & QA Handoff - -Check the feature spec - does this feature need backend? - -**Backend needed if:** Database access, user authentication, server-side logic, API endpoints, multi-user data sync - -**No backend if:** localStorage only, no user accounts, no server communication - -If backend is needed: -> "Frontend is done! This feature needs backend work. Next step: Run `/backend` to build the APIs and database." - -If no backend needed: -> "Frontend is done! Next step: Run `/qa` to test this feature against its acceptance criteria." - -## Checklist -See [checklist.md](checklist.md) for the full implementation checklist. - -After completion, update tracking files: -- [ ] Feature spec updated with implementation notes -- [ ] `features/INDEX.md` status updated to "In Progress" - -## Git Commit -``` -feat(PROJ-X): Implement frontend for [feature name] -``` diff --git a/.claude/skills/frontend/checklist.md b/.claude/skills/frontend/checklist.md deleted file mode 100644 index 98c9e2a..0000000 --- a/.claude/skills/frontend/checklist.md +++ /dev/null @@ -1,38 +0,0 @@ -# Frontend Implementation Checklist - -Before marking frontend as complete: - -## shadcn/ui -- [ ] Checked shadcn/ui for EVERY UI component needed -- [ ] No custom duplicates of shadcn components created -- [ ] Missing shadcn components installed via `npx shadcn@latest add` - -## Existing Code -- [ ] Checked existing project components via `git ls-files src/components/` -- [ ] Reused existing components where possible - -## Design -- [ ] Design preferences clarified with user (if no mockups) -- [ ] Component architecture from Solution Architect followed - -## Implementation -- [ ] All planned components implemented -- [ ] All components use Tailwind CSS (no inline styles, no CSS modules) -- [ ] Loading states implemented (spinner/skeleton during data fetches) -- [ ] Error states implemented (user-friendly error messages) -- [ ] Empty states implemented ("No data yet" messages) - -## Quality -- [ ] Responsive: Mobile (375px), Tablet (768px), Desktop (1440px) -- [ ] Accessibility: Semantic HTML, ARIA labels, keyboard navigation -- [ ] TypeScript: No errors (`npm run build` passes) -- [ ] ESLint: No warnings (`npm run lint`) - -## Verification (run before marking complete) -- [ ] `npm run build` passes without errors -- [ ] All acceptance criteria from feature spec addressed in UI -- [ ] `features/INDEX.md` status updated to "In Progress" - -## Completion -- [ ] User has reviewed and approved the UI in browser -- [ ] Code committed to git diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md deleted file mode 100644 index b476513..0000000 --- a/.claude/skills/help/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -name: help -description: Context-aware guide that tells you where you are in the workflow and what to do next. Use anytime you're unsure. -argument-hint: "optional question" -user-invocable: true ---- - -# Project Help Guide - -You are a helpful project assistant. Your job is to analyze the current project state and tell the user exactly where they are and what to do next. - -## When Invoked - -### Step 1: Analyze Current State - -Read these files to understand where the project stands: - -1. **Check PRD:** Read `docs/PRD.md` - - Is it still the empty template? → Project not initialized yet - - Is it filled out? → Project has been set up - -2. **Check Feature Index:** Read `features/INDEX.md` - - No features listed? → No features created yet - - Features exist? → Check their statuses - -3. **Check Feature Specs:** For each feature in INDEX.md, check if: - - Tech Design section exists (added by /architecture) - - QA Test Results section exists (added by /qa) - - Deployment section exists (added by /deploy) - -4. **Check Codebase:** Quick scan of what's been built - - `ls src/components/*.tsx 2>/dev/null` → Custom components - - `ls src/app/api/ 2>/dev/null` → API routes - - `ls src/components/ui/` → Installed shadcn components - -### Step 2: Determine Next Action - -Based on the state analysis, determine what the user should do next: - -**If PRD is empty template:** -> Your project hasn't been initialized yet. -> Run `/requirements` with a description of what you want to build. -> Example: `/requirements I want to build a task management app for small teams` - -**If PRD exists but no features:** -> Your PRD is set up but no features have been created yet. -> Run `/requirements` to create your first feature specification. - -**If features exist with status "Planned" (no Tech Design):** -> Feature PROJ-X is ready for architecture design. -> Run `/architecture` to create the technical design for `features/PROJ-X-name.md` - -**If features have Tech Design but no implementation:** -> Feature PROJ-X has a tech design and is ready for implementation. -> Run `/frontend` to build the UI for `features/PROJ-X-name.md` -> (If backend is needed, run `/backend` after frontend is done) - -**If features are implemented but no QA:** -> Feature PROJ-X is implemented and ready for testing. -> Run `/qa` to test `features/PROJ-X-name.md` against its acceptance criteria. - -**If features have passed QA but aren't deployed:** -> Feature PROJ-X has passed QA and is ready for deployment. -> Run `/deploy` to deploy to production. - -**If all features are deployed:** -> All current features are deployed! You can: -> - Run `/requirements` to add a new feature -> - Check `docs/PRD.md` for planned features not yet specified - -### Step 3: Answer User Questions - -If the user asked a specific question (via arguments), answer it in the context of the current project state. Common questions: - -- "What skills are available?" → List all 6 skills with brief descriptions -- "How do I add a new feature?" → Explain `/requirements` workflow -- "How do I customize this template?" → Point to CLAUDE.md, rules/, skills/ -- "What's the project structure?" → Explain the directory layout -- "How do I deploy?" → Explain `/deploy` workflow and prerequisites - -## Output Format - -Always respond with this structure: - -### Current Project Status -_Brief summary of where the project stands_ - -### Features Overview -_Table of features and their current status (from INDEX.md)_ - -### Recommended Next Step -_The single most important thing to do next, with the exact command_ - -### Other Available Actions -_Other things the user could do right now_ - -If the user asked a specific question, answer that FIRST, then show the status overview. - -## Important -- Be concise and actionable -- Always give the exact command to run -- Reference specific file paths -- Don't explain the framework architecture in detail unless asked -- Focus on: "Here's where you are, here's what to do next" diff --git a/.claude/skills/qa/SKILL.md b/.claude/skills/qa/SKILL.md deleted file mode 100644 index 679770f..0000000 --- a/.claude/skills/qa/SKILL.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -name: qa -description: Test features against acceptance criteria, find bugs, and perform security audit. Use after implementation is done. -argument-hint: "feature-spec-path" -user-invocable: true ---- - -# QA Engineer - -## Role -You are an experienced QA Engineer AND Red-Team Pen-Tester. You test features against acceptance criteria, identify bugs, and audit for security vulnerabilities. - -## Before Starting -1. Read `features/INDEX.md` for project context -2. Read the feature spec referenced by the user -3. Check recently implemented features for regression testing: `git log --oneline --grep="PROJ-" -10` -4. Check recent bug fixes: `git log --oneline --grep="fix" -10` -5. Check recently changed files: `git log --name-only -5 --format=""` - -### Check Playwright Browser Installation -Run: `npx playwright install --dry-run 2>&1 | head -5` - -If browsers are not installed, tell the user: -> "Playwright browsers need to be installed once. I'll do this now — it downloads ~300MB of browser binaries." -> Then run: `npx playwright install chromium` -> This is a one-time setup per machine. After cloning the repo, always run this once before E2E tests. - -## Workflow - -### 1. Read Feature Spec -- Understand ALL acceptance criteria -- Understand ALL documented edge cases -- Understand the tech design decisions -- Note any dependencies on other features - -### 2. Manual Testing -Test the feature systematically in the browser: -- Test EVERY acceptance criterion (mark pass/fail) -- Test ALL documented edge cases -- Test undocumented edge cases you identify -- Cross-browser: Chrome, Firefox, Safari -- Responsive: Mobile (375px), Tablet (768px), Desktop (1440px) - -### 3. Security Audit (Red Team) -Think like an attacker: -- Test authentication bypass attempts -- Test authorization (can user X access user Y's data?) -- Test input injection (XSS, SQL injection via UI inputs) -- Test rate limiting (rapid repeated requests) -- Check for exposed secrets in browser console/network tab -- Check for sensitive data in API responses - -### 4. Regression Testing -Verify existing features still work: -- Check features listed in `features/INDEX.md` with status "Deployed" -- Test core flows of related features -- Verify no visual regressions on shared components - -### 5. Run Automated Tests -Run existing test suites before manual testing: -```bash -npm test # Vitest: integration tests for API routes -npm run test:e2e # Playwright: E2E tests from previous QA runs -``` -Note any failures — these are regressions and must be treated as High bugs. - -### 6. Write Unit Tests -Before E2E tests, identify and test isolated logic with Vitest. Place tests **co-located** next to the source file (e.g. `src/hooks/useFeature.test.ts` next to `src/hooks/useFeature.ts`): - -**What to unit test (evaluate each):** -- Custom hooks with non-trivial logic (e.g. `useKanbanStorage`: localStorage read/write, error fallback) -- Pure utility/transformation functions (e.g. drag-and-drop reorder logic) -- Form validation logic (if extracted from components) - -**What NOT to unit test:** -- Pure presentational components with no logic -- Logic already fully covered by E2E tests - -For each unit test: -- Test the happy path -- Test error paths and edge cases (e.g. corrupt input, empty state) -- Mock only external dependencies (localStorage, fetch) — not internal logic - -Run to confirm all pass: `npm test` - -### 7. Write E2E Tests -For each acceptance criterion that passed manual testing, write a Playwright test in `tests/PROJ-X-feature-name.spec.ts`: -- One `test()` per acceptance criterion -- Tests describe the user journey in plain language -- Run to confirm all pass: `npm run test:e2e` - -These tests become the permanent regression suite for this feature. - -### 8. Document Results -- Add QA Test Results section to the feature spec file (NOT a separate file) -- Use the template from [test-template.md](test-template.md) - -### 9. User Review -Present test results with clear summary: -- Total acceptance criteria: X passed, Y failed -- Bugs found: breakdown by severity -- Security audit: findings -- Production-ready recommendation: YES or NO - -Ask: "Which bugs should be fixed first?" - -## Context Recovery -If your context was compacted mid-task: -1. Re-read the feature spec you're testing -2. Re-read `features/INDEX.md` for current status -3. Check if you already added QA results to the feature spec: search for "## QA Test Results" -4. Run `git diff` to see what you've already documented -5. Continue testing from where you left off - don't re-test passed criteria - -## Bug Severity Levels -- **Critical:** Security vulnerabilities, data loss, complete feature failure -- **High:** Core functionality broken, blocking issues -- **Medium:** Non-critical functionality issues, workarounds exist -- **Low:** UX issues, cosmetic problems, minor inconveniences - -## Important -- NEVER fix bugs yourself - that is for Frontend/Backend skills -- Focus: Find, Document, Prioritize -- Be thorough and objective: report even small bugs - -## Production-Ready Decision -- **READY:** No Critical or High bugs remaining -- **NOT READY:** Critical or High bugs exist (must be fixed first) - -## Checklist -- [ ] Feature spec fully read and understood -- [ ] All acceptance criteria tested (each has pass/fail) -- [ ] All documented edge cases tested -- [ ] Additional edge cases identified and tested -- [ ] Cross-browser tested (Chrome, Firefox, Safari) -- [ ] Responsive tested (375px, 768px, 1440px) -- [ ] Security audit completed (red-team perspective) -- [ ] Regression test on related features -- [ ] Every bug documented with severity + steps to reproduce -- [ ] Screenshots added for visual bugs -- [ ] Unit tests written for non-trivial hooks and utility functions (`npm test` passes) -- [ ] E2E tests written for all passing acceptance criteria (`npm run test:e2e` passes) -- [ ] QA section added to feature spec file -- [ ] User has reviewed results and prioritized bugs -- [ ] Production-ready decision made -- [ ] `features/INDEX.md` status updated to "In Review" (at QA start) -- [ ] `features/INDEX.md` status updated to "Approved" (if production-ready) OR kept "In Review" (if bugs remain) - -## Handoff -If production-ready: -> "All tests passed! Status updated to **Approved**. Next step: Run `/deploy` to deploy this feature to production." - -If bugs found: -> "Found [N] bugs ([severity breakdown]). Status remains **In Review**. The developer needs to fix these before deployment. After fixes, run `/qa` again." - -## Git Commit -``` -test(PROJ-X): Add QA test results for [feature name] -``` diff --git a/.claude/skills/qa/test-template.md b/.claude/skills/qa/test-template.md deleted file mode 100644 index 5177901..0000000 --- a/.claude/skills/qa/test-template.md +++ /dev/null @@ -1,56 +0,0 @@ -# QA Test Results Template - -Add this section to the END of the feature spec `/features/PROJ-X.md`: - -```markdown ---- - -## QA Test Results - -**Tested:** YYYY-MM-DD -**App URL:** http://localhost:3000 -**Tester:** QA Engineer (AI) - -### Acceptance Criteria Status - -#### AC-1: [Criterion Name] -- [x] Sub-criterion passed -- [ ] BUG: Sub-criterion failed (describe what went wrong) - -#### AC-2: [Criterion Name] -- [x] All sub-criteria passed - -### Edge Cases Status - -#### EC-1: [Edge Case Name] -- [x] Handled correctly - -#### EC-2: [Edge Case Name] -- [ ] BUG: Not handled (describe expected vs actual behavior) - -### Security Audit Results -- [x] Authentication: Cannot access without login -- [x] Authorization: Users cannot access other users' data -- [x] Input validation: XSS attempts blocked -- [x] Rate limiting: Excessive requests handled -- [ ] BUG: [Security issue description] - -### Bugs Found - -#### BUG-1: [Bug Title] -- **Severity:** Critical | High | Medium | Low -- **Steps to Reproduce:** - 1. Go to [page] - 2. Do [action] - 3. Expected: [what should happen] - 4. Actual: [what actually happens] -- **Screenshot:** [if visual bug] -- **Priority:** Fix before deployment | Fix in next sprint | Nice to have - -### Summary -- **Acceptance Criteria:** X/Y passed -- **Bugs Found:** N total (C critical, H high, M medium, L low) -- **Security:** [Pass / Issues found] -- **Production Ready:** YES / NO -- **Recommendation:** [Deploy / Fix bugs first] -``` diff --git a/.claude/skills/requirements/SKILL.md b/.claude/skills/requirements/SKILL.md deleted file mode 100644 index f936e80..0000000 --- a/.claude/skills/requirements/SKILL.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -name: requirements -description: Create detailed feature specifications with user stories, acceptance criteria, and edge cases. Use when starting a new feature or initializing a new project. -argument-hint: "project-description or feature-idea" -user-invocable: true ---- - -# Requirements Engineer - -## Role -You are an experienced Requirements Engineer. Your job is to transform ideas into structured, testable specifications. - -## Before Starting -1. Read `docs/PRD.md` to check if a project has been set up -2. Read `features/INDEX.md` to see existing features - -**If the PRD is still the empty template** (contains placeholder text like "_Describe what you are building_"): -→ Go to **Init Mode** (new project setup) - -**If the PRD is already filled out:** -→ Go to **Feature Mode** (add a single feature) - ---- - -## INIT MODE: New Project Setup - -Use this mode when the user provides a project description for the first time. The goal is to create the PRD AND break the project into individual feature specs in one go. - -### Phase 1: Understand the Project -Ask the user interactive questions to clarify the big picture: -- What is the core problem this product solves? -- Who are the primary target users? -- What are the must-have features for MVP vs. nice-to-have? -- Are there existing tools/competitors? What's different here? -- Is a backend needed? (User accounts, data sync, multi-user) -- What are the constraints? (Timeline, budget, team size) - -Use `AskUserQuestion` with clear single/multiple choice options. - -### Phase 2: Create the PRD -Based on user answers, fill out `docs/PRD.md` with: -- **Vision:** Clear 2-3 sentence description of what and why -- **Target Users:** Who they are, their needs and pain points -- **Core Features (Roadmap):** Prioritized table (P0 = MVP, P1 = next, P2 = later) -- **Success Metrics:** How to measure if the product works -- **Constraints:** Timeline, budget, technical limitations -- **Non-Goals:** What is explicitly NOT being built - -### Phase 3: Break Down into Features -Apply the Single Responsibility principle to split the roadmap into individual features: -- Each feature = ONE testable, deployable unit -- Identify dependencies between features -- Suggest a recommended build order (considering dependencies) - -Present the feature breakdown to the user for review: -> "I've identified X features for your project. Here's the breakdown and recommended build order:" - -### Phase 4: Create Feature Specs -For each feature (after user approval of the breakdown): -- Create a feature spec file using [template.md](template.md) -- Save to `/features/PROJ-X-feature-name.md` -- Include user stories, acceptance criteria, and edge cases -- Document dependencies on other features - -### Phase 5: Update Tracking -- Update `features/INDEX.md` with ALL new features and their statuses -- Update the "Next Available ID" line -- Verify the PRD roadmap table matches the feature specs - -### Phase 6: User Review -Present everything for final approval: -- PRD summary -- List of all feature specs created -- Recommended build order -- Suggested first feature to start with - -### Init Mode Handoff -> "Project setup complete! I've created: -> - PRD at `docs/PRD.md` -> - X feature specs in `features/` -> -> Recommended first feature: PROJ-1 ([feature name]) -> Next step: Run `/architecture` to design the technical approach for PROJ-1." - -### Init Mode Git Commit -``` -feat: Initialize project - PRD and X feature specifications - -- Created PRD with vision, target users, and roadmap -- Created feature specs: PROJ-1 through PROJ-X -- Updated features/INDEX.md -``` - ---- - -## FEATURE MODE: Add a Single Feature - -Use this mode when the project already has a PRD and the user wants to add a new feature. - -### Phase 1: Understand the Feature -1. Check existing components: `git ls-files src/components/` -2. Check existing APIs: `git ls-files src/app/api/` -3. Ensure you are not duplicating an existing feature - -Ask the user interactive questions to clarify: -- Who are the primary users of this feature? -- What are the must-have behaviors for MVP? -- What is the expected behavior for key interactions? - -Use `AskUserQuestion` with clear single/multiple choice options. - -### Phase 2: Clarify Edge Cases -Ask about edge cases with concrete options: -- What happens on duplicate data? -- How do we handle errors? -- What are the validation rules? -- What happens when the user is offline? - -### Phase 3: Write Feature Spec -- Use the template from [template.md](template.md) -- Create the spec in `/features/PROJ-X-feature-name.md` -- Assign the next available PROJ-X ID from `features/INDEX.md` - -### Phase 4: User Review -Present the spec and ask for approval: -- "Approved" → Spec is ready for architecture -- "Changes needed" → Iterate based on feedback - -### Phase 5: Update Tracking -- Add the new feature to `features/INDEX.md` -- Set status to **Planned** -- Update the "Next Available ID" line -- Add the feature to the PRD roadmap table in `docs/PRD.md` - -### Feature Mode Handoff -> "Feature spec is ready! Next step: Run `/architecture` to design the technical approach for this feature." - -### Feature Mode Git Commit -``` -feat(PROJ-X): Add feature specification for [feature name] -``` - ---- - -## CRITICAL: Feature Granularity (Single Responsibility) - -Each feature file = ONE testable, deployable unit. - -**Never combine:** -- Multiple independent functionalities in one file -- CRUD operations for different entities -- User functions + admin functions -- Different UI areas/screens - -**Splitting rules:** -1. Can it be tested independently? → Own feature -2. Can it be deployed independently? → Own feature -3. Does it target a different user role? → Own feature -4. Is it a separate UI component/screen? → Own feature - -**Document dependencies between features:** -```markdown -## Dependencies -- Requires: PROJ-1 (User Authentication) - for logged-in user checks -``` - -## Important -- NEVER write code - that is for Frontend/Backend skills -- NEVER create tech design - that is for the Architecture skill -- Focus: WHAT should the feature do (not HOW) - -## Checklist Before Completion - -### Init Mode -- [ ] User has answered all project-level questions -- [ ] PRD filled out completely (Vision, Users, Roadmap, Metrics, Constraints, Non-Goals) -- [ ] All features split according to Single Responsibility -- [ ] Dependencies between features documented -- [ ] All feature specs created with user stories, AC, and edge cases -- [ ] `features/INDEX.md` updated with all features -- [ ] Build order recommended -- [ ] User has reviewed and approved everything - -### Feature Mode -- [ ] User has answered all feature questions -- [ ] At least 3-5 user stories defined -- [ ] Every acceptance criterion is testable (not vague) -- [ ] At least 3-5 edge cases documented -- [ ] Feature ID assigned (PROJ-X) -- [ ] File saved to `/features/PROJ-X-feature-name.md` -- [ ] `features/INDEX.md` updated -- [ ] PRD roadmap table updated with new feature -- [ ] User has reviewed and approved the spec diff --git a/.claude/skills/requirements/template.md b/.claude/skills/requirements/template.md deleted file mode 100644 index 09c3894..0000000 --- a/.claude/skills/requirements/template.md +++ /dev/null @@ -1,36 +0,0 @@ -# PROJ-X: Feature Name - -## Status: Planned -**Created:** YYYY-MM-DD -**Last Updated:** YYYY-MM-DD - -## Dependencies -- None - -## User Stories -- As a [user type], I want to [action] so that [goal] - -## Acceptance Criteria -- [ ] Criterion 1 -- [ ] Criterion 2 - -## Edge Cases -- What happens when...? -- How do we handle...? - -## Technical Requirements (optional) -- Performance: < 200ms response time -- Security: Authentication required -- Browser Support: Chrome, Firefox, Safari - ---- - - -## Tech Design (Solution Architect) -_To be added by /architecture_ - -## QA Test Results -_To be added by /qa_ - -## Deployment -_To be added by /deploy_ diff --git a/.codex/config/project.md b/.codex/config/project.md new file mode 100644 index 0000000..da5b59c --- /dev/null +++ b/.codex/config/project.md @@ -0,0 +1,32 @@ +# Codex Configuration + +## Project Settings + +This project is optimized for Codex CLI autonomous coding. + +## Key Files + +- CODEX.md - Root instructions (this file guides Codex) +- .codex/prompts/ - Pre-built prompts for each development phase +- features/INDEX.md - Feature tracking and status +- docs/PRD.md - Product Requirements Document + +## Development Workflow + +1. Requirements → 2. Architecture → 3. Frontend → 4. Backend → 5. QA → 6. Deploy + +Each phase uses `codex exec` with natural language prompts. +See CODEX.md for example commands. + +## Conventions + +- Feature IDs: PROJ-1, PROJ-2, etc. +- Commits: feat(PROJ-X): description +- Tests: co-located with source files +- shadcn/ui first: never recreate installed components + +## Recommended Flags + +- `--full-auto` for feature development (auto-approves changes) +- `--yolo` for quick refactoring (no sandbox) +- Interactive (default) for review/debugging diff --git a/.codex/prompts/architecture.md b/.codex/prompts/architecture.md new file mode 100644 index 0000000..c2d8c58 --- /dev/null +++ b/.codex/prompts/architecture.md @@ -0,0 +1,16 @@ +# Architecture Prompt Template + +Use this prompt structure with Codex: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. + +Design the technical architecture and add a "Tech Design" section to the spec with: +- Component hierarchy (list components to build) +- API endpoints (method, path, request/response shapes) +- Database schema changes (tables, columns, RLS policies) +- Implementation order (what to build first, dependencies) +- Tech stack decisions ( libraries, patterns) + +Focus on: practical, implementable, PM-friendly (no code yet). +``` diff --git a/.codex/prompts/backend.md b/.codex/prompts/backend.md new file mode 100644 index 0000000..e177eb0 --- /dev/null +++ b/.codex/prompts/backend.md @@ -0,0 +1,19 @@ +# Backend Prompt Template + +Use this prompt structure with Codex: + +``` +Read the feature spec Tech Design section at features/PROJ-X-feature-name.md. +Check existing APIs: ls src/app/api/ +Check Supabase schema: cat src/lib/supabase.ts + +[Describe what to build] + +Implementation rules: +- Use Supabase client from src/lib/supabase.ts +- Create API routes in src/app/api/[entity]/ +- Follow existing patterns for route structure +- Add RLS policies for new tables +- Write tests for all endpoints +- Run: npm test after implementation +``` diff --git a/.codex/prompts/deploy.md b/.codex/prompts/deploy.md new file mode 100644 index 0000000..a58a161 --- /dev/null +++ b/.codex/prompts/deploy.md @@ -0,0 +1,15 @@ +# Deploy Prompt Template + +Use this prompt structure with Codex: + +``` +Deploy to production: +1. Run: npm run build (must succeed) +2. Run: npm run lint (no errors) +3. Run: vercel --prod +4. Verify deployment URL +5. Run smoke tests on production + +If build fails: fix errors first, then deploy. +If lint errors: run npm run lint:fix, commit, then deploy. +``` diff --git a/.codex/prompts/frontend.md b/.codex/prompts/frontend.md new file mode 100644 index 0000000..54b68f8 --- /dev/null +++ b/.codex/prompts/frontend.md @@ -0,0 +1,21 @@ +# Frontend Prompt Template + +Use this prompt structure with Codex: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Check existing components: ls src/components/ui/ +Check installed shadcn: ls src/components/ui/ | wc -l + +[Describe what to build] + +Implementation rules: +- ALWAYS use shadcn/ui components (check src/components/ui/ first) +- If missing: npx shadcn@latest add +- Tailwind CSS for all styling +- Write unit tests next to source files (*.test.ts next to *.ts) +- Run npm run lint after changes + +If design files exist: check design/ mockups/ assets/ +Otherwise ask about: visual style, brand colors, layout preference. +``` diff --git a/.codex/prompts/qa.md b/.codex/prompts/qa.md new file mode 100644 index 0000000..97c660f --- /dev/null +++ b/.codex/prompts/qa.md @@ -0,0 +1,20 @@ +# QA Prompt Template + +Use this prompt structure with Codex: + +``` +Read the feature spec at features/PROJ-X-feature-name.md, especially: +- Acceptance criteria +- User stories +- Edge cases + +Test the implementation: +1. Run unit tests: npm test +2. Run E2E tests: npm run test:e2e +3. Manual testing if needed +4. Check each acceptance criterion +5. Verify edge cases are handled + +Report: what passed, what failed, what needs fixing. +Fix all failures before declaring done. +``` diff --git a/.codex/prompts/requirements.md b/.codex/prompts/requirements.md new file mode 100644 index 0000000..93bc58b --- /dev/null +++ b/.codex/prompts/requirements.md @@ -0,0 +1,25 @@ +# Requirements Prompt Template + +Use this prompt structure with Codex: + +``` +Read docs/PRD.md to understand the project vision and constraints. +Read features/INDEX.md to see existing features and the next available PROJ-X ID. + +[Describe the feature idea clearly] + +Create a feature specification in features/PROJ-X-feature-name.md with: +- Feature name and ID +- User stories (3-5, with: As a [role], I want [action], so that [benefit]) +- Acceptance criteria (testable, specific) +- Edge cases (error handling, edge inputs, boundary conditions) +- Dependencies (other features required) +- Implementation notes (optional) + +Update features/INDEX.md with the new feature status. +``` + +Example: +``` +codex exec "Read docs/PRD.md and features/INDEX.md. Create a feature spec for user authentication with email/password login, including: user stories for login/logout, acceptance criteria for valid/invalid credentials, edge cases for locked accounts and rate limiting." +``` diff --git a/.gitignore b/.gitignore index 1706280..c861ad7 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,7 @@ yarn-error.log* # typescript *.tsbuildinfo next-env.d.ts + +# Codex +.codex/data/ +.codex/cache/ diff --git a/CLAUDE.md b/CLAUDE.md.old similarity index 100% rename from CLAUDE.md rename to CLAUDE.md.old diff --git a/CODEX.md b/CODEX.md new file mode 100644 index 0000000..a8ab6e1 --- /dev/null +++ b/CODEX.md @@ -0,0 +1,117 @@ +# 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 . 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.