AGENTS.md for Codex: Rules That Survive the Monorepo

Codex builds the instruction chain once when a run starts. A launched TUI session normally counts as one run, so the working directory and the files present at startup are part of the result.

Choose the destination by function. Guidance belongs in the active chain only when Codex needs it to select the next action, boundary, authority, or proof.

The root should remain true for almost every package. Replace every example command with one that actually exists; a false command turns each task into a setup investigation.

Treat the sections below as responsibilities rather than a mandatory schema. Standard Markdown is enough. Keep the repository map stable, point to changing detail, and make the completion contract specific enough that a reviewer can distinguish a finished task from an unverified edit.

# Repository guide

## Repository map
- `apps/` contains deployable applications.
- `packages/` contains shared libraries.
- `docs/` is the source of truth for architecture and decisions.

## Read before editing
- Architecture: `docs/ARCHITECTURE.md`
- Current plans: `docs/plans/`
- Read the nearest nested `AGENTS.md`.

## Authoritative commands
- Install: `npm ci`
- Focused validation: run the changed package's test script.
- Full gate: `npm run check`

## Boundaries
- Do not edit generated files; update their source.
- Ask before adding a production dependency or changing a public API.
- Never commit credentials, local env files, or build output.

## Completion contract
- Add or update tests for changed behavior.
- Run focused checks, then the full gate once.
- Report changed files, validation, and unresolved risks.

If one task genuinely spans peer packages, start at their nearest shared ancestor and link each package's authoritative documents. Do not paste every local manual into the root merely to make one broad session possible.

find . -type f \
+  \( -name 'AGENTS.md' -o -name 'AGENTS.override.md' \) \
+  -print

wc -c AGENTS.md \
+  services/AGENTS.md \
+  services/payments/AGENTS.override.md

The byte total is a preflight estimate; global guidance and configuration still matter. Use it to catch accidental growth, not to optimize toward the 32 KiB ceiling.

1. 01

   Does every command exist and run from the directory implied by the rule?

2. 02

   Does a deeper file replace a broad rule explicitly, or merely contradict it?

3. 03

   Is any paragraph duplicated from an inherited file?

4. 04

   Could a source document or executable check replace this prose?

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Eliminate structural causes before adding prose. More text cannot repair a file that was shadowed, truncated, outside the startup path, or stale for the active run.

1. 01
   Confirm the root and CWD

   The expected nested file must be on the active root-to-CWD path.

2. 02
   Look for an override

   A same-directory AGENTS.override.md wins over AGENTS.md.

3. 03
   Check the filename

   Custom names are ignored unless configured as fallbacks.

4. 04
   Check content and size

   Empty files are skipped; the combined chain can hit its byte ceiling.

5. 05
   Restart the run

   The current session does not continuously rebuild instructions.

6. 06
   Ask for a summary

   Separate a discovery failure from vague or conflicting guidance.

7. 07
   Test one behavior

   Use a command, boundary, example, and proof—not a general aspiration.

If discovery succeeds but behavior remains inconsistent, name the scope, trigger, required action, and proof. “After changing database migrations, run make test-migrations” is testable; “test database changes carefully” is not.

Native Codex owns instruction discovery, precedence, fallback filenames, and the combined byte limit. Supercode does not change those rules.

If those layers match the repository, install Supercode for Codex. Keep the contract explicit: AGENTS.md routes persistent working agreements, documentation holds durable knowledge, and executable checks prove compliance.

• The root file is a map and working agreement, not a copied manual.
• Every command exists and runs from the documented directory.
• Every nested file contains local differences rather than inherited text.
• Overrides are intentional, visible, and removed when temporary work ends.
• Long explanations point to versioned source documents.
• Mechanical rules are enforced by tools and name their validation command.
• The relevant root-to-CWD chain stays comfortably below its byte ceiling.
• A new Codex run can summarize the expected chain and local overrides.
• A representative task proves the guidance changes observable behavior.
• Rules likely to drift have an owner or review trigger.

The goal is not to tell Codex everything. Give the current task the smallest reliable path to the right knowledge, commands, boundaries, and proof.