// Blog / operational checklist
Codex repo onboarding checklist for .knowledge
The useful setup artifact 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.
// real failure mode
The failure mode
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.
// repo-local model
The repo-local fix
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 card for the task.
If the module card is low-confidence, the next step is not to edit. The next step is to open the relevant source files and tests, then plan from current code.
// repo proof
Repo proof to inspect
.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
// command transcript
Commands and expected checks
node .knowledge/tools/install-agent-integrations.js - expected
- Codex, Claude Code, OpenCode, and command entrypoints are installed or refreshed.
- inspect next
- .agents/skills/ and .knowledge/agent-integrations/
node .knowledge/tools/flow.js import - expected
- The initial repository map and module cards are created or refreshed.
- inspect next
- .knowledge/project_index.json and .knowledge/modules/
node .knowledge/tools/flow.js release --no-color - expected
- Routing, trust, freshness, search, metrics, PR summary, and Inspector outputs are checked.
- inspect next
- .knowledge/maintenance/quality_report.json
node .knowledge/tools/build-visual-inspector.js - expected
- The local static Inspector is regenerated.
- inspect next
- .knowledge/inspector/index.html
Before asking Codex to change behavior
// field guide
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. |
| Agent integrations installed | Use reusable Codex skills and commands. | Run install-agent-integrations before handoff. |
// guardrails
What the agent should not trust blindly
- A missing routing bundle means setup is incomplete.
- A low-confidence module is not a blocker, but it changes the workflow: re-read source and tests before making claims or edits.
- A clean release flow is a readiness signal for the knowledge layer, not proof that the product code is correct.
// common mistakes
Common mistakes
- Putting the checklist only in chat instead of the repository.
- Running import once and never refreshing trust or stale files.
- Skipping the trust report because the first module summary looks plausible.
// 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 card only as a route hint. Re-read current source and tests before making behavior claims or edits.
// page-specific next step
Use this page as the Codex preflight
Before a serious edit, make Codex prove it has read the repo-local entrypoint, routing bundle, trust report, and the current source path for the task.