personal-site: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working on this Next.js personal portfolio site.

Quick Commands

npm run dev          # Start dev server (localhost:3000)
npm run format       # Format with Prettier + Biome (run before committing)
npm run lint         # Biome linting
npm run type-check   # TypeScript checking
npm test             # Vitest tests
npm run build        # Production build + static export

File-scoped (faster feedback):

npx biome check path/to/file.tsx            # Lint single file
npm test -- ComponentName                    # Test single component

Project Structure

app/                  → Pages, layouts, global CSS
app/styles/           → Modular CSS (tokens, base, components, layout, pages)
src/components/       → React components (organized by feature)
src/data/             → Static data (resume, projects, contact)
src/hooks/            → Custom React hooks
content/writing/      → Blog posts (Markdown with frontmatter)
src/data/writing.ts   → External writing links shown on `/writing`
public/images/        → Images and favicons
docs/                 → Documentation

Code Style

Do:

• Use TypeScript strict mode, functional components with hooks
• Style with CSS custom properties in app/styles/ (tokens in tokens/, components in components/)
• Keep components small and focused
• Use existing patterns from similar components
• Mark client components with 'use client'
• Follow conventional commits: feat:, fix:, chore:, docs:
• Run npm run format before committing (CI enforces this)

Don't:

• Add new dependencies without clear need
• Create god components or monolithic files
• Hard-code colors—use CSS variables (var(--color-*))
• Skip type annotations on function parameters
• Commit without running npm run format first

Git Workflow

• Create a topic branch for every task; never commit or push directly to main
• Make small, frequent conventional commits as you go (e.g., feat:, fix:, refactor:)
• Push to your remote branch after every commit to keep it in sync
• Land changes on main by merging GitHub PRs with conventional-commit titles (deploys trigger automatically from these merges)
• If multiple PRs need to land together, open an integration branch PR; do not locally merge into main. Dependency upgrades follow the workflow below
• Treat main as protected: force-pushes and history rewrites require explicit user approval