# AGENTS.md: [Project name]

> Ready-to-fill AGENTS.md: the README for AI coding agents. It follows the
> open AGENTS.md convention (agents.md): a plain Markdown file at the
> repository root that tells any coding agent how to set up, build, test
> and change this project safely. Replace every `[bracketed]` value and
> every line marked *Example*.

<!--
Guidance: How to use this template
- Save the finished file as AGENTS.md in the repository root. Agents read the
  nearest AGENTS.md to the file they edit, so sub-packages may have their own.
- Write commands exactly as they must be typed. Agents run them literally.
- Keep it short and factual: rules, commands, paths. Put background and
  rationale in docs/ and link to it.
- Delete sections that do not apply rather than leaving them empty.
- Review it whenever the build, test or release process changes; a stale
  AGENTS.md produces confidently wrong changes.
-->

| Field | Value |
|---|---|
| Repository | [org/repo] |
| Primary language(s) | [TypeScript 5.x, Python 3.12] |
| Package manager | [pnpm 9 / npm / uv / cargo] |
| Default branch | [main] |
| Maintainers | [@owner], [@team] |
| Last reviewed | YYYY-MM-DD |

## Project overview

<!-- Guidance: Two to five sentences. What the software does, who uses it, and what must never break. Agents use this to judge the blast radius of a change. -->

[Project name] is a [one-line description, for example "multi-tenant
invoicing API with a React admin console"]. It is used by [audience] and
runs on [platform, for example "Kubernetes in two regions"].

Critical behaviours that must never regress:

- *Example:* Invoices are immutable once issued; corrections create credit notes.
- *Example:* Every database query is scoped by `tenant_id`.
- [Behaviour that must not break]

## Setup commands

<!-- Guidance: The exact sequence from a fresh clone to a running dev environment. Include required tool versions and how to get secrets for local work. -->

Prerequisites: [Node.js 22 LTS], [pnpm 9], [Docker 27] and [any other tool].

```bash
# Install dependencies
pnpm install --frozen-lockfile

# Start local services (database, cache)
docker compose up -d db redis

# Apply migrations and seed development data
pnpm db:migrate && pnpm db:seed

# Start the development server on http://localhost:3000
pnpm dev
```

Local configuration lives in `.env.local`, created from `.env.example`.
Never commit real values.

## Build, test and lint commands

<!-- Guidance: List every command an agent should run before declaring work done. State which ones are required and how long they take, so an agent can choose a fast loop. -->

| Task | Command | Required before PR | Typical time |
|---|---|---|---|
| Typecheck | `pnpm typecheck` | Yes | 20 s |
| Lint | `pnpm lint` | Yes | 15 s |
| Unit tests | `pnpm test` | Yes | 40 s |
| Single test file | `pnpm test path/to/file.test.ts` | No | 2 s |
| End-to-end tests | `pnpm test:e2e` | When UI or routing changes | 4 min |
| Production build | `pnpm build` | Yes | 90 s |
| Format | `pnpm format` | Run, do not hand-format | 5 s |

All required commands must pass with zero errors and zero new warnings.

## Code style and conventions

<!-- Guidance: Only rules that a linter does not already enforce, plus the reasons agents most often get wrong. Point to the formatter config instead of restating it. -->

- Formatting is enforced by [Prettier / Ruff / rustfmt]; do not reformat untouched files.
- Use [named exports only; no default exports].
- File names: [kebab-case for files, PascalCase for React components].
- Errors: [throw typed errors from `src/lib/errors.ts`; never throw strings].
- Logging: [use `logger` from `src/lib/log.ts`; never `console.log` in committed code].
- Dependencies: [do not add a dependency without asking; prefer the standard library].
- *Example:* Dates are stored in UTC and formatted only at the UI edge.

## Architecture map

<!-- Guidance: A map of where things live so the agent edits the right file. Keep to the top two levels plus any directory with special rules. -->

| Path | Contains | Notes |
|---|---|---|
| `src/app/` | Routes and pages | [Server components by default] |
| `src/lib/` | Shared domain logic | [Pure functions, fully unit tested] |
| `src/db/` | Schema and migrations | [Never edit an applied migration; add a new one] |
| `src/components/` | UI components | [Use the design system; no inline styles] |
| `tests/` | Unit and E2E tests | [Mirror the `src/` layout] |
| `docs/` | Design docs and ADRs | [Update when architecture changes] |

Data flows from [entry point] through [service layer] to [storage]. See
[docs/architecture.md] for the full description.

## Testing instructions

<!-- Guidance: What "tested" means here. Agents should add or update tests with every behaviour change, and should know which fixtures and helpers exist. -->

- Every bug fix includes a test that fails before the fix and passes after.
- New modules in `src/lib/` need unit tests with [80%] line coverage.
- Use the factories in `tests/factories/`; do not hand-build fixtures.
- Tests must not call real external services; use [MSW / respx / test doubles].
- Do not delete or skip a failing test to make the suite pass. Report it instead.
- Snapshot updates (`-u`) are allowed only when the visual change is intended and described in the PR.

## PR and commit conventions

<!-- Guidance: Branch names, commit format and PR content. If you use Conventional Commits or a PR template, say so and link it. -->

- Branch from `[main]` using `[type]/[short-description]`, for example `fix/invoice-rounding`.
- Commit messages follow [Conventional Commits]: `type(scope): summary` in the imperative mood, at most 72 characters.
- One logical change per PR. Keep diffs under [400] changed lines where possible.
- PR description: what changed, why, how it was tested, and any follow-up.
- Run all required commands from the table above before opening a PR.
- Never force-push to `[main]` or rewrite shared history.

## Security and secrets

<!-- Guidance: Hard rules about credentials, personal data and risky operations. Be explicit; agents follow explicit rules more reliably than implied ones. -->

- Never print, log or commit secrets, tokens, keys or `.env` files.
- Never paste production data or personal data into prompts, fixtures or tests.
- Do not disable authentication, authorization, CSRF or input validation, even temporarily.
- Do not run commands against production systems or production databases.
- New external network calls, new dependencies and changes to CI permissions require human review.
- Report suspected vulnerabilities through [SECURITY.md], not in public issues.

## Do and don't

<!-- Guidance: A short, scannable list of the mistakes that keep happening. Update it after each review where an agent got something wrong. -->

| Do | Don't |
|---|---|
| Read the nearest AGENTS.md and the files you will change before editing | Guess APIs; search the codebase instead |
| Make the smallest change that solves the task | Refactor unrelated code in the same PR |
| Ask when a requirement is ambiguous | Invent configuration values or credentials |
| Update docs and types with the code | Leave commented-out code or debug output |
| *Example:* Use `money.ts` helpers for currency maths | *Example:* Use floating point for amounts |

## Monorepo notes

<!-- Guidance: Only for repositories with several packages. Explain how to scope commands to one package and where nested AGENTS.md files live. Delete this section for single-package repositories. -->

This repository uses [pnpm workspaces / Nx / Turborepo]. Packages live in
`packages/` and apps in `apps/`.

- Run a command in one package: `pnpm --filter [package-name] test`.
- Find a package name in its `package.json` `name` field, not the folder name.
- A nested `AGENTS.md` (for example `apps/web/AGENTS.md`) overrides this file for files below it.
- Shared types live in `packages/[shared]`; changing them requires running the full test suite.

## Further reading

<!-- Guidance: Links an agent may need on demand. Keep them relative so they work offline. -->

- [CONTRIBUTING.md](CONTRIBUTING.md) for the human contribution process.
- [docs/architecture.md](docs/architecture.md) for design background.
- [SECURITY.md](SECURITY.md) for vulnerability reporting.

## Standard and licence note

Based on the open AGENTS.md convention described at agents.md (a plain
Markdown file at the repository root, with nested files taking precedence
for their subtree) and on common industry practice for contributor
documentation. Original text written for this collection. Template
licence: MIT.