// Blog / operational checklist
Codex repo onboarding checklist for .knowledge
The useful setup tool is not a longer prompt. It is a repeatable checklist Codex can verify inside the repository.
// direct answer
Short answer
A Codex onboarding checklist should confirm the .knowledge entrypoint exists, agent integrations are installed, routing and trust reports are current, and low-confidence modules are rechecked from source before edits.
Give Codex a repeatable repo-local onboarding path before asking it to change behavior.
// the problem
Repository setup is easy to lose between sessions
Codex can read and edit the local workspace, but a repo with no first-read path still forces the agent to infer structure from scattered files.
Instructions may live in chat, local notes, or an old README section. That makes onboarding hard to repeat across sessions.
The first useful fix is not a longer prompt. It is a small, repo-local checklist with commands and files the agent can verify.
// repeatable setup
Keep the onboarding checklist in the repository
Place .knowledge in the repository root, then make Quick-Start.md the first operational read.
Install the agent integrations so Codex, Claude Code, OpenCode, and other tools can find the same routing layer.
Run import once, then use release checks when meaningful work changes the repo or the knowledge state.
// concrete example
Before first behavior edit
Ask Codex to read .knowledge/Quick-Start.md, then read the Routing Bundle and the relevant module summary for the task.
Copy-paste prompt: Read .knowledge/Quick-Start.md, then verify routing_bundle.json, trust_report.json, and the target source/tests before editing.
If the module summary needs review, open the relevant source files and tests before planning the edit.
// files you can inspect
Files that guide Codex
Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.
.knowledge/Quick-Start.md
This file tells the agent how to enter the knowledge layer without relying on chat memory.
- Starting a new Codex session
- Finding maintenance commands
- Replacing task-specific source review
- Assuming every summary is trusted
.knowledge/maintenance/routing_bundle.json
Codex needs this compact map before planning work across a large repository.
- Choosing modules
- Finding stale or suspect context
- Making claims about runtime behavior
.knowledge/maintenance/trust_report.json
The trust report shows whether knowledge is ready for routing or must be rechecked from source.
- Deciding how cautious to be
- Finding low-confidence modules
- Approving code without tests
.agents/skills/*/SKILL.md
Installed skills give Codex reusable workflows instead of one-off instructions.
- Repeatable local workflows
- Knowledge maintenance commands
- Hiding product-specific requirements from the repo
AGENTS.md
The installer creates or updates AGENTS.md with .knowledge first-read rules for Codex.
- Repository starting instructions
- Onboarding future Codex sessions
- Replacing current source and tests
// commands to try
Commands and expected checks
node .knowledge/tools/install-agent-integrations.js - what it does
- Codex, Claude Code, OpenCode, and command entrypoints are installed or refreshed.
- where to look
- .agents/skills/ and .knowledge/agent-integrations/
node .knowledge/tools/flow.js import - what it does
- The initial repository map and module summaries are created or refreshed.
- where to look
- .knowledge/project_index.json and .knowledge/modules/
node .knowledge/tools/flow.js release --no-color - what it does
- Routing, trust, freshness, search, metrics, PR summary, and Inspector outputs are checked.
- where to look
- .knowledge/maintenance/quality_report.json
node .knowledge/tools/build-visual-inspector.js - what it does
- The local static Inspector is regenerated.
- where to look
- .knowledge/inspector/index.html
Before asking Codex to change behavior
// practical reference
Pass / fail setup checklist
| Check | Pass | Fail / next move |
|---|---|---|
| Quick-Start exists | Use it as the first operational read. | Create or restore the .knowledge entrypoint. |
| Routing bundle exists | Use it to choose source files. | Run import or release before planning. |
| Trust report is current | Plan with its trust labels. | Treat summaries as advisory and re-read source. |
| AGENTS.md exists | Codex has repository-owned starting instructions. | Run install-agent-integrations. |
| Agent integrations installed | Use reusable Codex skills and commands. | Run install-agent-integrations before handoff. |
// quick FAQ
FAQ
Should Codex always run the full release flow before editing?
No. Use the release flow when setup, knowledge state, or meaningful repository changes need to be refreshed. For small tasks, reading the current routing and source files may be enough.
What if the trust report marks a module low-confidence?
Use the module summary only to find relevant files. Re-read current source and tests before making behavior claims or edits.
// next step
Before your first code change
Before a serious edit, confirm that Codex has read the repository entrypoint, Routing Bundle, confidence report, and the current source files for the task.