AI_template/codex-rules.md

Repository Guidelines

Project Structure & Modules

• Docs live in docs/; start with project-overview.md, phases-plan.md, then frontend/ and backend/. README.md summarizes; DOCS.md indexes English docs.
• Agent configs sit in agents/; core rules are in RULES.md. Use the feature-first layout from docs/frontend/architecture.md (app/, features/, entities/, shared/) mapped to invoicing, expenses, payroll, compliance.

Core Stack & Services

• Frontend: Next.js (TypeScript, App Router), Tailwind CSS, React Query/SWR. Backend: Node.js + TypeScript with Express/Fastify; BullMQ (Redis); Prisma or Drizzle.
• Data: Postgres (Supabase/RDS) + pgvector; include EventLog.source_agent (default balance) and Transaction.reasoning_trace JSONB for explainability.
• Ops: Dockerized deploys (Render/Fly.io/Railway). Payments: Stripe. Auth: Clerk/Auth.js. LLM: OpenAI API via one helper; model switches must be one-line.

Build, Test, and Development Commands

• Do not run npm run dev (repository rule). Use npm run build to verify compilation; rerun after meaningful changes.
• Add npm test / npm run lint when tooling is added; document scripts in README.md and here. Docs-only changes: just check links.

Coding Style & Naming

• Prefer Server Components; mark client components explicitly. Keep code feature-first; put shared utilities in shared/ and API clients in dedicated modules. Encapsulate finance/LLM integrations behind services.
• Names in English; use descriptive files. Follow framework defaults; run Prettier/ESLint if configs exist. Keep prompt logic only in the LLM helper.

Testing Guidelines

• Layered coverage: unit tests for calculations/rules; component tests for invoicing, expense upload, reconciliation; E2E for onboarding, ingestion, categorization, approval, payment.
• Name tests *.spec.ts / *.test.ts(x) alongside code or under __tests__/. Mock Stripe, tax/reporting APIs, QuickBooks webhooks, and LLM calls. Validate webhook handling and reasoning_trace persistence via backend-facing mocks.
• Document test commands and required env vars in README.md.

Commit & Pull Request Guidelines

• Use concise, imperative commit messages. PRs: state purpose/scope, affected modules/docs, validation (npm run build, tests), screenshots if UI. Link tasks/issues; note risks (provider edges, missing secrets, migrations). Update docs when behavior or decisions change.

Agent, API, & Security Notes

• Review RULES.md and relevant agent files before coding. Keep secrets out of the repo; use env vars and never commit provider keys, bank tokens, or webhook secrets.
• All LLM calls must pass through the shared helper to centralize config and logging.
• Maintain APIs for transactions, approvals, overrides, reports, rules, billing; expose read-only /api/events for downstream agents. Log TX_INGESTED, TX_CATEGORIZED, TX_APPROVED, RULE_CREATED, REPORT_GENERATED with source_agent; persist reasoning_trace for auditability.
• Keep project phase/status aligned across README.md, DOCS.md, and docs/phases-plan.md; update when phase changes.