AGENTS.md (repo root)

Hermes discovers nested AGENTS.md files as it enters subdirectories, so a monorepo can layer instructions: this root file carries what is true everywhere, and each package adds its own on top.

Everywhere in this repo

• One package per PR. Cross-package changes need a stated reason in the PR description.
• Shared code changes (packages/shared/) require running the dependents' tests too: turbo run test --filter=...^shared.
• Generated files (*.gen.ts, openapi/) are never edited by hand — change the source and regenerate.

Layout

Path	What lives there	Has its own AGENTS.md
apps/web	Next.js storefront	yes — routing + styling rules
apps/api	Fastify API	yes — handler conventions
packages/shared	types + utilities	no — root rules suffice

---

apps/api/AGENTS.md (example of a nested file)

Rules here apply only under apps/api/, on top of the root rules.

• Every route gets a schema in schemas/ — request and response. Unvalidated responses have shipped bugs twice.
• Database access via the repository layer in db/repos/; no query builder calls inside handlers.
• Errors return the envelope in lib/errors.ts. Never leak a stack trace into a response body.