Codex governance: four contracts that hold in review

Codex governance is the small set of repo contracts that keep Codex CLI work reviewable: a slash catalog, a verification latch, a browser bridge note, and a model pin. Codex CLI, OpenAI's coding agent, can move fast on its own, so the job of these contracts is to make sure a reviewer can still defend the merge afterward. If that sounds like paperwork, price it against the hours you lose to an incident.

I learned this the slow way. A PR landed that looked finished, the sub-agent summary skipped half the paths it had touched, and the reviewer only noticed at merge time. Green checks were doing the talking, and the verification underneath them was thinner than anyone thought.

Let AGENTS.md own the truth

Most Codex guides chase features, and the official docs already do that job. The features page lists what the tool can do. What no vendor page can state is how your team works.

That part lives in AGENTS.md. It is the one file the agent reads to decide behavior and the one file the reviewer reads to check it, so it is where your norms belong.

Think of it as a contract both sides sign. The agent agrees to follow it, and the reviewer agrees to hold the diff against it.

Write the four contracts down

Each contract fixes a specific way trust leaks out of a fast loop. None of them is expensive. The cheap one first.

Slash catalog. Slash commands drift when nobody writes them down, and they turn into private folklore one operator knows and the rest guess at. Keep a docs/codex-commands.md linked from AGENTS.md, and point to the slash commands reference for the built-ins. The team converges on one way to run things.

Verification latch. This is the costly one. Exec shortcuts skip the tests, regressions slip back in quietly, and the green check still says everything is fine. Require a transcript snippet that shows tests ran after the code was generated. A green merge means something again.

Browser bridge note. Chrome workflows and CLI habits drift apart until the demo tells one story and CI tells another. Document the staging URLs and credential boundaries right next to the browser tasks, so the demo and the CI artifacts stop contradicting each other.

Model pin. Teams swap models casually, and a different model carries a different risk appetite, so review expectations wobble. Pin the default model and the escalation rule inside AGENTS.md. Now a lead can reason about blast radius before approving anything.

Here is the snippet I drop into AGENTS.md to anchor all four:

# AGENTS.md verification snippet

- Every Codex CLI run ends with the transcript snippet reviewers can replay.
- Pair browser evidence with the project's normal CLI checks before merge.
- If MCP servers are enabled, list allowed actions beside each connector name.

Check the PR against four gates

The point of writing contracts down is that you can grep them later. When a PR comes in, run it past these four questions before you trust the green.

Teams often ask for a "codex analytics api" to answer who ran what, with which connector, under which rule. A verification transcript answers that before any dashboard does. The receipts you want in a postmortem are exactly the ones the latch already captures.

Paste this checklist into your PR template and the gates become muscle memory:

• Scopes in the PR body match folders in the diff.
• Primary-doc links were smoke-checked after publishing edits.
• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.

The MCP specification gives your connector lists a shared vocabulary, and openai/codex plus openai/skills are where the tool keeps changing. The quickstart is a fine place to begin, but a repo that cannot state its boundaries plainly leaves the agent guessing, and guessing scales badly.

Common questions

• What is codex governance in practice?

  Codex governance is the set of repo contracts that keep Codex CLI work reviewable: a slash catalog, a verification latch, a browser bridge note, and a model pin. The rule underneath all four is that AGENTS.md owns the truth, because review bandwidth, not agent speed, is the scarce resource on a busy team.

• Where should Codex slash commands be documented?

  In a slash catalog at docs/codex-commands.md, linked from AGENTS.md. Slash commands that spread without docs become private folklore, and operators quietly diverge on how they run tasks. Once the catalog exists, the team converges on one shared way to work, and a review no longer depends on which operator happened to run the job.

• What proof should a governed Codex PR carry?

  Four things: scopes in the PR body that match the folders in the diff, primary-doc links smoke-checked after edits, owners listed for any MCP connectors mentioned, and verification output pasted or linked. The working test is simple: can a new reviewer defend the merge without replaying the chat log?

• Does codex governance slow delivery down?

  It feels like overhead until you compare it to the hours an incident costs, which is the honest baseline. Picture two clocks, one for shipping and one for explainability. When only the shipping clock runs, you pay the difference later, with interest, in review time you no longer have.

Start with the verification latch

Pick one inherited PR and read it against the four gates, noting which answers forced you to open a chat log. For the full set of contracts with the reasoning behind each, see the broader Codex CLI workflows practice or hand a platform lead our white paper.