Codex Control Plane
The .codex control plane is the durable workspace layer for workflow policy
and routing. It is intentionally separate from product code so that frontend,
backend, worker, infra, docs, and workspace automation work can share one
execution model without duplicating rules inside each repo.
This page is a reference for the main surfaces and trust tiers. The canonical
source is .codex/knowledge/CONTROL_PLANE_RULES.md.
Canonical Surfaces
| Path | Owner role | Use it for |
|---|---|---|
.codex/AGENTS.md | Tier 1 entry contract | Dispatch Lock, Plan Mode boundary, default loop, specialist routing, and workspace references |
.codex/knowledge/** | Durable knowledge | Hard rules, architecture intent, glossary, and repo-specific rule summaries |
.codex/routing/** | Routed SSOTs and references | Repo cards, loop contracts, review matrix, verification selectors, branch strategy, doc sync, and commit policy |
.codex/agents/*.toml | Specialist definitions | Role descriptions and developer instructions for routed agents |
.codex/rules/** | Path-scoped repo rules | Focused backend, frontend, and worker rules by owned surface |
.codex/lint/** | Checkers and pattern SSOTs | Forbidden-pattern sweep, agent registry checks, scope checks, and commit readiness |
.codex/hooks/** | Hook implementations | Narrow backstops for secrets, migrations, control-plane scope, Markdown guards, and commit checks |
.codex/hooks.json | Hook registration | Which hook scripts run before or after tool classes |
Do not reintroduce repo-local .codex, .codex-plugin, plugin marketplace
files, dispatcher agents, vendored third-party skills, or workspace workflow
harnesses. Product repos can have thin local AGENTS.md additions, but the
workspace router remains centralized.
Trust Tiers
Control-plane documents are not all equal. The trust-tier model decides what a file is allowed to guarantee.
| Tier | Name | Examples | What it guarantees |
|---|---|---|---|
| Tier 0 | Enforcement | hooks, lint, tests, checkers | Rules that must hold even when a document is not read |
| Tier 1 | Always-loaded core | .codex/AGENTS.md, HARD_RULES_CROSS.md | Entry contract, hard stops, and where to route next |
| Tier 2 | Routed SSOT | repo cards, loop contract, review matrix, commit policy, doc sync, verification selector | Decisions that are loaded for a matching situation |
| Tier 3 | Reference | planning templates, implementation runbooks, review rubrics, sharp-edge catalogs | Helpful execution guidance that cannot be the only barrier for critical invariants |
When a repeated failure depends on someone reading prose, either demote that prose to reference guidance or promote the invariant to Tier 0 enforcement.
Custom Agents
Custom agents live as TOML files under .codex/agents/*.toml. Each definition
must provide:
name;description;model;developer_instructions.
Agent TOML is prompt guidance, not an enforcement boundary. Critical tool permissions, write scopes, security gates, and commit gates need hooks, lint, tests, checkers, or tool filters when they must hold independently.
Use .codex/lint/agent-registry-checker.sh to validate the registry shape. Do
not lint TOML agent definitions as Markdown frontmatter.
Hooks And Lint
Hooks are narrow, context-limited backstops. The current hook registration in
.codex/hooks.json includes pre-tool checks for writes and shell commands, a
post-shell Flyway worktree check, and a session-start context hook.
Lint owns broad forbidden-pattern detection. The regex source of truth is
.codex/lint/patterns/<lang>.yaml, and callers use
bash .codex/lint/sweep.sh. Agents, hooks, routing docs, and ad hoc scripts
must not carry duplicate regex copies.
Control-Plane Change Discipline
Changes to .codex policy, guardrails, review routing, commit policy, hooks,
lint enforcement, or shared SSOT references require a control-plane impact map
before planning or editing. The map records:
- canonical files;
- linked references;
- review and checker surfaces;
- work-log or commit-readiness fields when affected;
- docs or audit follow-ups.
Each touched SSOT should be marked as update, deprecate, supersede, or
explicit defer. If the map spans multiple control-plane SSOTs, keep the work
as one coordinated control-plane slice unless a concrete runtime-risk trigger
requires broader coordination.
Verification
Use these source files to verify the control-plane structure:
sed -n '1,220p' .codex/knowledge/CONTROL_PLANE_RULES.md
sed -n '1,220p' .codex/AGENTS.md
bash .codex/lint/agent-registry-checker.sh
Expected success signal: the first two commands show the current surfaces and entry gate, and the registry checker exits successfully for agent TOML files.
Related Pages
- Codex for the high-level workflow map.
- Codex Workflow Loops for execution control.
- Codex Review Routing for specialist and review coverage.