phaseflow/AGENTS.md

ABOUTME: Operational notes for Ralph autonomous development loops.

ABOUTME: Contains build/test commands and codebase patterns specific to PhaseFlow.

Build & Run

• Dev server: pnpm dev
• Build: pnpm build
• Start production: pnpm start

Validation

Run these after implementing to get immediate feedback:

• Tests: pnpm test:run
• Lint: pnpm lint
• Lint fix: pnpm lint:fix
• Typecheck: pnpm tsc --noEmit

Operational Notes

• Database: PocketBase at POCKETBASE_URL env var
• Garmin tokens encrypted with AES-256 using ENCRYPTION_KEY (32 chars)
• Path aliases: @/* maps to ./src/*
• Pre-commit hooks: Biome lint + Vitest tests via Lefthook

Codebase Patterns

• TDD required: Write tests before implementation
• All files start with 2-line ABOUTME comments
• No mock mode: Use real data and APIs only
• Never use --no-verify for git commits
• Commit format: Descriptive message + Claude footer

Tech Stack

Layer	Choice
Framework	Next.js 16 (App Router)
Runtime	Node.js 24
Database	PocketBase
Validation	Zod
Testing	Vitest + jsdom
Linting	Biome

File Structure

• src/app/ - Next.js pages and API routes
• src/components/ - React UI components
• src/lib/ - Business logic utilities
• src/types/ - TypeScript type definitions
• specs/ - Feature specifications for Ralph