Set up repository rules for Codex

Why this matters

Tomorrow an AI agent writes code in your repository. Whether that goes well is decided today, not tomorrow. An agent — like a competent new colleague on their first morning — does good work when the commands are written down, the boundaries are explicit, and there is one way to prove a change did not break anything. Without that it guesses, and its guesses look confident.

By the end of the hour, npm run check runs every check you own in one command, and a file in your repository tells any agent how to work here.

The repository is the instruction sheet

On Day 34 you learned the discipline: define one small task, review the plan, inspect the diff, run the checks, explain every changed section. That discipline needs somewhere to stand. If "the checks" means three commands you half-remember, you will skip them; if it is one command, you will run it every time.

Everything today serves one goal: make the state of the project verifiable in seconds, by you or by an agent, without anyone remembering anything.

README: how a human starts from nothing

The README answers one question: I have just cloned this repository on a clean machine — what do I type? Keep it short and keep it true. Four sections is enough:

# Calibration Tracker

Records instrument calibrations so overdue instruments are visible. One primary user.

## Requirements
- Node 20+, Docker Desktop

## Setup
    cp .env.example .env
    npm install
    docker compose up -d      # starts PostgreSQL
    npm run db:migrate
    npm run db:seed

## Commands
| Command | Does |
|---|---|
| `npm run dev` | Starts the development server |
| `npm run check` | Lint, typecheck, and tests — must pass before every commit |
| `npm run db:seed` | Resets seed data |

The test of a README is brutal and simple: follow it yourself, from a fresh clone in a different folder, typing only what it says. Anything you had to know without being told is a missing line.

Project instructions the agent reads

Codex and similar tools look for a file of project instructions in the repository — conventionally AGENTS.md at the root — and read it before working. This is where you make expectations, commands, and boundaries explicit, so the agent stops inferring them from whatever file it happened to open.

Keep it under a page. An instruction file nobody reads to the end constrains nothing.

# Project instructions

## What this is
An Express API and a React frontend over PostgreSQL. See docs/architecture.md.

## Commands
- Install: `npm install`
- Run checks: `npm run check`  (lint + typecheck + tests)
- Seed data: `npm run db:seed`

## How to work here
- One vertical slice per change. Do not refactor unrelated files.
- Present a plan and wait for approval before editing.
- After editing, run `npm run check` and paste the result.
- Summarise every changed file and why it changed.

## Never do these
- Never add a dependency without asking.
- Never edit files in db/migrations/ that are already applied; add a new migration.
- Never change docs/spec.md or docs/architecture.md — those are mine.
- Never write secrets into the repository. Config comes from .env, which is gitignored.

## Definition of done
The acceptance criteria named in the task pass, `npm run check` is green,
and the change is one commit with a message describing the behaviour.

Four things make this file work, and they are the four to reproduce in any project: what the project is, the exact commands, how to work, and the forbidden list. The forbidden list is the part beginners omit and the part that saves you — yesterday you wrote down which artifacts the agent must never touch, and this is where it goes.

One command that runs every check

You already have the pieces from earlier weeks: a linter, TypeScript, and tests. Today you wire them into one entry point so there is exactly one way to ask "is this repository healthy?"

{
  "scripts": {
    "dev": "vite",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "db:migrate": "node scripts/migrate.js",
    "db:seed": "node scripts/seed.js",
    "check": "npm run lint && npm run typecheck && npm run test"
  }
}

The && matters: each command runs only if the previous one exited 0, the success exit code you met on Day 4. The first failure stops the chain, so the first error you see is the one to fix.

npm run check

> typecheck
> tsc --noEmit

src/routes/calibrations.ts:22:5 - error TS2322: Type 'string' is not assignable to type 'number'.

That output is your evidence. "It looked right" is not evidence; a 0 exit code from npm run check is.

Seed data belongs in the same category. npm run db:seed should drop you at a known starting state — a few instruments, a couple of calibrations — so that "given an instrument exists" from your acceptance criteria is a fact rather than a hope. Without repeatable seed data, every test you run by hand starts from a slightly different world and you cannot compare results between days.

Small issues: work sized to a session

The last piece of scaffolding is how you write down the next piece of work. Take your spec's stories and cut them into issues small enough to finish, verify, and commit in one sitting. One issue equals one vertical slice equals one commit.

Use this shape, in a docs/backlog.md file or your tracker of choice:

ISSUE 3 — Record a calibration (SLICE 1)
Criteria:  Story 1, criteria 1–4 in docs/spec.md
Touches:   db/migrations, src/routes/calibrations.ts, src/web/CalibrationForm.tsx
Done when: all four criteria pass by hand on seeded data, npm run check green
Not now:   editing or deleting calibrations (Issue 7)

The Not now line does the same job as a non-goal, at issue scale: it keeps the change from growing while you are inside it. The Touches line gives you and the agent a shared expectation of diff size — if the diff touches eleven files instead of three, something went wrong and you will notice immediately.

Walkthrough: prove the repository is clean

Do this end to end. It takes ten minutes and it is the deliverable.

cd ~
git clone <your-repo-url> clean-clone-test
cd clean-clone-test

Now follow your own README exactly — no improvising, no commands from memory:

cp .env.example .env
npm install
docker compose up -d
npm run db:migrate
npm run db:seed
npm run check

Test Files  3 passed (3)
     Tests  9 passed (9)

Every place you had to deviate is a README bug. Fix the README, not your habit. Then delete the clone:

rm -rf ~/clean-clone-test

Your turn

1. Create the repository for your capstone, with .gitignore covering node_modules and .env.
2. Write the README with the four sections above. Every command must be one you have run.
3. Add the check script chaining lint, typecheck, and tests with &&. Run it and confirm the exit code with echo $?.
4. Write a seed script creating a small known dataset, exposed as npm run db:seed.
5. Write AGENTS.md with the four sections: what this is, commands, how to work here, never do these — plus a definition of done.
6. Write three issues in docs/backlog.md using the issue shape, with SLICE 1 first.
7. Do the clean-clone test from the walkthrough, fix what it exposes, then delete the clone.
8. Commit: chore: repository scaffolding, checks, and agent instructions.

Common pitfalls

• A README you never followed. Half the setup lives in your shell history. The clean-clone test is the only way to find out.
• Instructions describing intentions, not commands. "Make sure quality is high" constrains nothing. "Run npm run check and paste the output" is checkable.
• Checks that are slow or noisy. If npm run check takes four minutes or prints 200 warnings, you will stop running it. Fix or silence the noise now.
• Committing .env. Secrets in Git history are effectively permanent. Verify git status shows .env as ignored before your first commit.

Verify it yourself

Open today's reference, OpenAI's Codex CLI documentation.

1. Find how the CLI discovers project instructions: the filename it expects and where it looks. Confirm your file matches, and correct it if not.
2. Find what it says about approvals or permissions for running commands and editing files. Decide which mode you will use tomorrow and write your choice at the top of AGENTS.md.

Getting the filename and location right from the documentation — rather than from memory — is the difference between instructions that are read and a file nobody opens.