Repository Orientation
Build the smallest accurate mental model needed for the user's task.
Protocol
- Read applicable
AGENTS.md files and inspect git status. Treat existing
changes as user work.
- Inventory with
rg --files, bounded by relevant top-level directories.
Identify manifests, lockfiles, build/test config, deployment config, and
generated/vendor boundaries.
- Infer the repository shape: application, library, monorepo, service set,
plugin, infrastructure, or hybrid. Verify the inference from manifests.
- Trace one real execution path from an external entry point to its terminal
effect. Follow imports/calls, configuration, persistence, and outbound I/O;
do not infer architecture from names alone.
- Trace the requested concern separately. Locate its definition, runtime
wiring, tests, and operational surface. Search symbols and call sites before
reading entire large files.
- Identify boundaries that constrain a change: public API, data/schema,
process/service, trust/authorization, transaction, concurrency, and release.
- Stop when the model answers the user's question. Do not exhaustively catalog
unrelated modules.
Evidence discipline
- Cite concrete
path:line references for important claims.
- Distinguish observed facts from inferences. State what would falsify an
inference when uncertainty matters.
- Treat README and diagrams as orientation leads, then reconcile them with
executable code and configuration.
- Call out stale, duplicated, dead, generated, or bypassed paths.
- If multiple entry points differ materially, map each relevant path rather
than inventing one universal flow.
Output
Use references/repository-map.md. Lead with the answer the user needs, then
give the execution path, boundaries, change location, and open questions. Skip
sections that add no decision value.
Do not edit the repository unless the user also requests a change.
1---2name: repo-orient3description: Map an unfamiliar software repository from code and configuration. Use when Codex needs to understand a new codebase, locate entry points or ownership boundaries, explain architecture and runtime flow, identify where a change belongs, or prepare for implementation without yet modifying files. Produce an evidence-backed repository map, not a directory listing or README paraphrase.4---56# Repository Orientation78Build the smallest accurate mental model needed for the user's task.910## Protocol11121. Read applicable `AGENTS.md` files and inspect `git status`. Treat existing13 changes as user work.142. Inventory with `rg --files`, bounded by relevant top-level directories.15 Identify manifests, lockfiles, build/test config, deployment config, and16 generated/vendor boundaries.173. Infer the repository shape: application, library, monorepo, service set,18 plugin, infrastructure, or hybrid. Verify the inference from manifests.194. Trace one real execution path from an external entry point to its terminal20 effect. Follow imports/calls, configuration, persistence, and outbound I/O;21 do not infer architecture from names alone.225. Trace the requested concern separately. Locate its definition, runtime23 wiring, tests, and operational surface. Search symbols and call sites before24 reading entire large files.256. Identify boundaries that constrain a change: public API, data/schema,26 process/service, trust/authorization, transaction, concurrency, and release.277. Stop when the model answers the user's question. Do not exhaustively catalog28 unrelated modules.2930## Evidence discipline3132- Cite concrete `path:line` references for important claims.33- Distinguish observed facts from inferences. State what would falsify an34 inference when uncertainty matters.35- Treat README and diagrams as orientation leads, then reconcile them with36 executable code and configuration.37- Call out stale, duplicated, dead, generated, or bypassed paths.38- If multiple entry points differ materially, map each relevant path rather39 than inventing one universal flow.4041## Output4243Use `references/repository-map.md`. Lead with the answer the user needs, then44give the execution path, boundaries, change location, and open questions. Skip45sections that add no decision value.4647Do not edit the repository unless the user also requests a change.
contextosai