AGENTS.md — Operating Rules for AI Coding Agents

Read this file completely at the start of every session, before any other action. It applies to Claude Code, GitHub Copilot, and any other coding agent working in this repository.

1. Prime directive

The documents in docs/ are the source of truth for intent. The code is the source of truth for current reality. Your job is to keep them in agreement.

If you are asked to build something that is not described in docs/01-prd.md, stop and say so. Propose the requirement first. Do not silently invent scope.

2. Session start checklist

Before writing or changing any code, read in this order:

1. docs/11-glossary.md — so you use our words correctly
2. docs/01-prd.md — the requirement you are working on
3. docs/12-tech-stack.md — what we are actually running, and at which versions
4. docs/04-architecture.md — how the system is put together
5. docs/05-data-model.md — before touching anything persistent
6. docs/06-api-contract.md — before touching any endpoint
7. docs/08-test-plan.md — how this must be verified
8. docs/adr/ — decisions you are not allowed to quietly reverse

State which requirement ID you are working on before you begin.

3. The ID system — never break the chain

Every unit of work is anchored to an ID from the PRD.

IDs are permanent. Never renumber, never reuse a retired ID. To retire one, set its status to Deprecated — do not delete the row.

Allocate a new ID by taking max(existing) + 1 for that prefix. Check the whole repo before allocating.

4. Definition of Done

A change is not done until every box is true:

• The requirement exists in docs/01-prd.md with acceptance criteria
• All affected downstream docs are updated in the same PR
• Each touched document has a bumped version and a new Change Log row
• docs/09-traceability-matrix.md has a row linking requirement → code → test
• Automated tests exist, are tagged with the requirement ID, and pass
• Every acceptance criterion has been verified on the Vercel preview URL
• CHANGELOG.md has an entry under [Unreleased]
• No secrets, keys, or tokens are committed
• Any new dependency has a TECH- row; any new env var has a CFG- row and an .env.example entry
• No dependency or runtime version was bumped as a side effect of this work
• Accessibility and performance budgets in the PRD's NFR section still hold

5. Git conventions

Branches: <type>/<ID>-<slug> — e.g. feat/FR-014-saved-search, fix/FR-009-token-refresh, chore/CHORE-004-bump-deps.

Commits — Conventional Commits, with the ID in the scope:

feat(FR-014): add saved search persistence

Implements ENT-007 and API-021. Adds TC-058 and TC-059.

Refs: FR-014

Types: feat fix docs refactor test chore perf build ci.

A breaking change must carry a BREAKING CHANGE: footer explaining the migration path. This drives the MAJOR version bump.

One requirement per branch. One branch per PR. Never bundle.

6. Change safety rules

These exist to stop version N+1 from breaking version N.

Database

• Use expand → migrate → contract, never a destructive change in one release.
  1. Expand: add the new column/table as nullable. Deploy.
  2. Migrate: backfill, write to both, read from new. Deploy.
  3. Contract: drop the old column in a later release. Deploy.
• Every migration gets a MIG- ID and a tested rollback path.
• Never write a migration that cannot be reversed without data loss unless the PRD explicitly approves it.

Dependencies & configuration

• Never add a dependency without recording it. A new direct dependency needs a TECH- row in docs/12-tech-stack.md §3, a stated reason in the PR, and an ADR if the choice is significant or hard to reverse.
• Prefer the platform. If the framework or standard library already does it, use that instead of adding a package.
• Never introduce an environment variable without a CFG- row in docs/12-tech-stack.md §4 and a described line in .env.example.
• Never put a secret behind a browser-exposed prefix (e.g. NEXT_PUBLIC_).
• Never bump a dependency version as a side effect of feature work. Upgrades are separate PRs with their own UPG- ID.
• Never change a pinned runtime version (.nvmrc, engines, CI image) without an UPG- entry — silent drift between local, CI, and production is how "works on my machine" happens.

API

• Adding an optional field or a new endpoint is safe.
• Removing a field, renaming a field, changing a type, or adding a required request field is breaking. Version the endpoint instead (/v2/...) and deprecate the old one with a removal date recorded in docs/06-api-contract.md.

UI

• Do not change shared components in docs/03-design-system.md without checking every SCR- that consumes them.
• Use design tokens. Never hard-code a colour, spacing value, or font size.

General

• Put anything risky, slow to validate, or externally dependent behind a feature flag, defaulted off.
• Never modify a passing test to make new code pass. Fix the code, or change the requirement in the PRD first and record why.
• Never delete a test without an explicit, recorded reason.

7. Documentation editing rules

When you edit any file in docs/:

1. Update the YAML front-matter: bump version, set last_updated, adjust status if needed.
2. Append a row to that document's Change Log table, citing the requirement ID.
3. Follow the version bump rules:
   • PATCH — wording, typos, formatting only
   • MINOR — additive change (new requirement, new field, new flow)
   • MAJOR — removal or incompatible change; you must also list the downstream documents that now need review
4. Never rewrite history in a Change Log table. Only append.

8. Uncertainty protocol

You will not always know the answer. Mark it, do not guess:

• [INFERRED] — you deduced this from the code with reasonable confidence
• [ASSUMPTION] — you had to pick something to make progress; state the choice
• [NEEDS CONFIRMATION] — a human must decide; you cannot resolve this from available evidence

Never invent business rationale, target users, success metrics, compliance obligations, or SLAs. Those come from a human. Ask.

If a task requires reversing a decision recorded in an ADR, stop and propose a new superseding ADR instead of just doing it.

9. What you must never do

• Commit secrets, .env files, API keys, or credentials
• Push directly to main
• Disable, skip, or weaken a CI check to make a PR pass
• Perform a destructive database operation without an approved MIG- entry
• Delete or renumber an existing requirement ID
• Change docs/00-vision.md without explicit human instruction
• Add a dependency without a TECH- row and a stated reason
• Add an environment variable without a CFG- row and an .env.example entry
• Upgrade a dependency or runtime as a side effect of unrelated work
• Mark work complete when acceptance criteria are unverified

10. Tech stack

The stack inventory lives in docs/12-tech-stack.md. Read it at session start. Do not restate versions here — two copies of a version number means one of them is wrong, and you will trust the wrong one.

That document tells you exactly what is installed, at which versions, which environment variables exist, and what is scheduled to change. If it disagrees with the lockfile, trust the lockfile and flag the document as drifted.

Commands

Fill these in and keep them accurate — you are expected to run lint, typecheck, and tests before opening a PR.

# install
# dev
# test
# lint
# typecheck
# build