Engineering standards

This repository ships with a .cursor/ tree that tells human developers and AI agents how to work here. Rules are standing policies; skills are procedural playbooks opened when a task matches their description. AGENTS.md at the repo root is the entry point — load the TDD and shadcn skills before touching next/.

AI architecture — data, tools, instructions

If you think AI is moving too fast, you are operating at the wrong abstraction layer. Every system reduces to three durable parts: data, tools, and instructions. Zoethales is built around that invariant layer — not around whichever multi-agent orchestration framework is fashionable this quarter.

• Invariant layer — invest in clean data, well-scoped tools, and explicit instructions; that stack outlasts model and framework churn.
• No complex multi-agent frameworks — orchestration libraries change quickly; we avoid betting the product on them.
• Robust to change — swap a parser or model without rewiring the whole system when data model and tool boundaries stay stable.
• Wrong abstraction — chasing agent-framework features is a symptom of weak data discipline or unclear tool contracts.
• SQL over NoSQL — relational schema is structured; structured data carries more context for AI agents and developers alike.

Rules vs skills

Test-driven development

TDD is the default for every feature, bug fix, and behavior change under next/. Opt out only when a human explicitly skips it for a narrow task (throwaway spike, vendored-only edit).

• Iron law: no production code without a failing test first.
• Cycle: RED (write smallest failing test) → verify RED → GREEN (minimal pass) → verify GREEN → REFACTOR (only while green).
• Bug fixes: add a regression test that reproduces the symptom before fixing.
• Legacy code: pin current behavior with tests, then add a new failing test for the desired change.
• Completion bar: make test passes; you observed RED and GREEN, not just assumed them.

Stack and commands

Key TDD rules and skills

• Rule: .cursor/rules/test-driven-development.mdc — default red → green → refactor policy.
• Rule: .cursor/rules/tdd-frontend-react-vitest.mdc — Vitest conventions for next/**/*.{ts,tsx}.
• Rule: .cursor/rules/agent-preflight-tdd.mdc — load the TDD skill at task start; verify RED/GREEN.
• Skill: .cursor/skills/test-driven-development/SKILL.md — full agent checklist and rationalization guardrails.

UI and shadcn/ui

The Next.js app uses shadcn/ui as the default foundation for controls and layout. Compose and extend primitives before introducing custom base components. The app was bootstrapped with shadcn CLI preset b3lnmLrRg and the Next App Router template.

UI conventions

• Prefer existing @/components/ui/* primitives (Button, Card, Dialog, Table, Badge, etc.).
• Add new primitives via npx shadcn@latest add --cwd next <component> — not hand-rolled copies.
• Preserve accessibility semantics, variant props, and theming from shadcn defaults.
• Custom components only when requirements cannot be met by composition.
• Load .cursor/skills/shadcn-ui-design-basis/SKILL.md before UI work; obey .cursor/rules/shadcn-ui-first.mdc.

Sagard brand palette

Product chrome extends the shadcn token set with Sagard brand colors defined in next/app/globals.css:

• font-heading — display headings (batch titles, page heroes).
• font-sans — body copy and table text.
• Layout width — max-w-6xl content column with px-6 md:px-10 padding.
• Navigation — pill-shaped tab links in site-nav.tsx (Upload, Docs).
• Status badges — outline/destructive/default variants via status-display.ts helpers.

Thoughtful targeted UI/UX design

Beyond tokens and shadcn primitives, the app follows thoughtful targeted UI/UX: each route gets a Sagard-style full-bleed scenic hero (photography + navy gradient overlay + burgundy accent rule) like sagard.com hero-full sections, while dense tools stay on a light content band below the hero.

• Upload (/) — hero-upload.png; full-height hero, upload panel below.
• Batch workflow — hero-workflow.png; compact hero, progress table below.
• Document review — hero-review.png; compact hero, side-by-side review below.
• Docs (/docs/*) — hero-docs.jpg (nature landscape only, no people); compact hero; article body is blocks only (title lives in hero).
• Scenic policy — SCENIC_HERO_IMAGE_POLICY in page-heroes.ts; nature-only assets enforced by page-heroes.test.ts.
• Portfolio roll-up — PageHero portfolio variant with coverage stats in the stats slot.

Other agent policies

Agent checklist (before claiming done)

• Loaded TDD skill; wrote failing test(s) before production code.
• Ran tests and observed RED, then GREEN.
• make test passes for touched areas.
• For UI: reused or extended shadcn/ui primitives.
• For system changes: updated matching /docs section and site-docs tests.