Give Codex the same design direction in every task.
AgentKogei Installation places one Design Contract at the Project root and adds a managed Project instruction. When Codex loads that AGENTS.md, the instruction directs it to the complete visual direction in DESIGN.md.
Why Codex finds it
Project instructions form the discovery path.
Codex builds its Project instruction chain before doing work. It starts at the Project root, typically the Git root, and walks toward the current working directory.
At the Project root, Codex checks AGENTS.override.md before AGENTS.md and uses at most one instruction file there.
Codex stops adding instruction files when their combined size reaches project_doc_max_bytes, which defaults to 32 KiB.
When there is no root override and the combined instruction chain is within that limit, the managed AGENTS.md is part of the instruction chain for work beneath it.
Codex AGENTS.md documentationThe exact handoff
AGENTS.mdDESIGN.mdInterface workDESIGN.md is not a special Codex instruction filename. When the managed AGENTS.md is active, its sentence explicitly tells Codex to follow the Design Contract for user interface work.
Installation workflow
Inspect, install, then verify.
- Inspect
Choose a compatible Design System
Read its Design System Preview, complete Design Contract, compatibility, and evaluation evidence before applying it to a Project.
- Install
Run add from the Project root
The CLI retrieves the selected release, previews the files it will create or replace, and asks for approval before writing.
- Verify
Inspect both durable files
Check for a root override, confirm that DESIGN.md holds the complete release, and inspect the managed AGENTS.md block without replacing other Project instructions.
From the Project root
npx agentkogei@latest add foundationInspect the result
ls AGENTS.override.md AGENTS.md DESIGN.mdwc -c AGENTS.mdcat AGENTS.mdcat DESIGN.mdManaged reference
One explicit instruction connects the files.
AgentKogei creates AGENTS.md when it is absent. When the file already exists, it preserves the other instructions and adds or updates only its marked block.
AgentKogei does not create or change AGENTS.override.md. If a root override exists, Codex uses it instead of the managed root AGENTS.md, so resolve that Project instruction manually before relying on this handoff.
If verification omits the managed reference, also inspect the active instruction files and project_doc_max_bytes. Shorten or split oversized Project guidance, or raise the limit intentionally.
<!-- agentkogei:design-system:start -->## AgentKogei Design SystemFollow the Design System in `DESIGN.md` for all user interface work in this Project.<!-- agentkogei:design-system:end -->Fresh Codex task
Verify the direction before interface work.
Start a new Codex task from the Project root after Installation. Codex builds its instruction chain once per run, so a fresh task ensures it evaluates the current root instruction files.
Verification request
Summarize the Project instructions and the Design Contract you will follow before changing the interface.
Check the response against both files. This verifies what Codex received without asking it to mutate the Project.
Qualified Installation
Choose the direction before applying it.
- Installation writes DESIGN.md and the managed AGENTS.md reference.
- It does not install dependencies, execute code, or migrate an existing interface.
- Replacing an existing Design Contract requires explicit approval.
Run the command from the Project root. Review the CLI preview and approve the file changes only when the selected Design System fits.