ECC/docs/CODEX-NAVIGATION-GUIDE.md

Codex ECC Navigation Map

This guide helps Codex agents navigate ECC without scanning every surface from scratch. Use it after the root AGENTS.md and .codex/AGENTS.md when planning work, preparing a PR-quality diff, or handing context to a reviewer.

Start Here

Read in this order:

1. AGENTS.md - universal project rules, agent routing, testing expectations, and commit workflow.
2. .codex/AGENTS.md - Codex-specific setup, MCP, skill discovery, and hook-parity limits.
3. docs/COMMAND-AGENT-MAP.md - command to agent and skill routing.
4. This guide - repo navigation, diff packet shape, and PR review lanes for Codex sessions.

If those files disagree, prefer the more specific file for the current task: Codex-specific behavior belongs in .codex/AGENTS.md; general contribution policy belongs in AGENTS.md and CONTRIBUTING.md.

Surface Map

Surface	What It Owns	Codex Use
AGENTS.md	Cross-harness operating rules	Read before any repo work
.codex/AGENTS.md	Codex-only guidance	Read after root instructions
.codex/config.toml	Codex sandbox, MCP, profiles, agent roles	Inspect when setup or MCP behavior matters
.codex/agents/	Codex multi-agent role layers	Use for explorer, reviewer, and docs researcher roles
.agents/skills/	Codex-facing skill copies	Use when Codex needs native skill loading
skills/	Canonical skill source	Update first for new workflow knowledge
agents/	Claude-style subagent prompts	Use as source material for review lanes and delegation intent
commands/	Legacy slash-command shims	Update only when command compatibility is needed
docs/COMMAND-AGENT-MAP.md	Command to agent and skill relationships	Check before renaming or adding workflow surfaces
rules/	Shared coding, security, and workflow rules	Read language or domain rules before implementation
hooks/	Claude Code hook workflows	Do not assume Codex hook parity
scripts/	Install, validation, sync, and CLI utilities	Follow existing Node script patterns
manifests/	Install component and module registration	Update when adding installable surfaces
.github/PULL_REQUEST_TEMPLATE.md	Required PR body checklist	Preserve sections when creating PRs

Task Routing

Use this quick routing before editing:

Task	First Files	Likely Verification
Add or update a skill	skills/<name>/, .agents/skills/<name>/, manifests/, agent.yaml	node scripts/ci/validate-skills.js, node tests/ci/codex-skill-surface.test.js
Add or update a command	commands/, docs/COMMAND-AGENT-MAP.md, COMMANDS-QUICK-REF.md	node scripts/ci/validate-commands.js, npm run command-registry:check
Add a Codex setup change	.codex/, scripts/codex/, scripts/lib/install-targets/codex-home.js	node tests/scripts/codex-hooks.test.js, node tests/codex-config.test.js
Add installable content	manifests/, scripts/lib/install-*, package.json	node scripts/ci/validate-install-manifests.js, targeted install tests
Add docs-only guidance	docs/, README.md, harness supplement files	Targeted docs test plus markdownlint if available
Review a PR	commands/review-pr.md, agents/*reviewer.md, agents/pr-test-analyzer.md	Diff review plus relevant tests

Keep workflow contributions skills-first. Add or update commands/ only for legacy slash-entry compatibility or cross-harness parity.

Codex Agent Roles

ECC ships project-local Codex role layers in .codex/agents/:

Role	File	Use
Explorer	.codex/agents/explorer.toml	Read-only evidence gathering before edits
Reviewer	.codex/agents/reviewer.toml	Correctness, security, and missing-test review
Docs researcher	.codex/agents/docs-researcher.toml	API, release-note, and docs claim verification

Use roles for bounded sidecar work. Do the immediate blocking task locally, and delegate independent evidence or review tasks when they can run in parallel.

PR Diff Packet

Before /pr, prepare a local diff packet. This gives reviewers the context that many PR tools otherwise have to reconstruct.

Run:

git fetch origin
git diff origin/main...HEAD --stat
git diff origin/main...HEAD --name-only
git log origin/main..HEAD --oneline --reverse

Then capture:

## PR Diff Packet

### Intent
<One sentence describing the user-visible or maintainer-visible outcome.>

### Diff Map
- Added: <new files and why they exist>
- Modified: <existing files and why they changed>
- Unchanged but relevant: <surfaces checked and intentionally left alone>

### Risk and review lanes
- Behavior:
- Security:
- Tests:
- Docs:
- Release/install surface:

### Testing Done
- <commands run, or "Not run" with reason>

### Follow-ups
- <optional, only if not required for this PR>

Use .github/PULL_REQUEST_TEMPLATE.md as the final PR body structure. The diff packet feeds that template; it does not replace it.

PR Commands

Need	Command Surface	Notes
Create a PR	/pr	Discovers PR template, analyzes commits and files, pushes, and creates a PR
Create a PR from PRP workflow	/prp-pr	Same core flow with PRP artifact references
Review a PR	/review-pr	Runs multi-perspective review lanes and aggregates findings
Review current changes before PR	/code-review	Use before committing when no GitHub PR exists yet

Codex may not execute slash commands natively in every environment. When a slash command is not available, read the command file and perform the same steps manually.

Review Lanes

For a PR-quality diff, check these lanes before asking for review:

Lane	Evidence
Scope	git diff origin/main...HEAD --name-only matches the stated intent
Tests	New behavior has a targeted test or a clear no-test rationale
Security	No secrets, unsafe external writes, broad permissions, or input trust gaps
Install surface	New skills, commands, agents, hooks, scripts, or files are registered where required
Cross-harness	Codex, OpenCode, Cursor, Claude Code, and docs surfaces are updated only when applicable
Docs	README and focused docs link to the new source of truth

For code changes, invoke the relevant reviewer lane after implementation. For docs-only changes, run the targeted docs test and review links for drift.

Common Navigation Pitfalls

• Do not treat commands/ as the canonical place for new workflow knowledge. Prefer skills/ first.
• Do not copy Claude hook claims into Codex docs. Codex enforcement is based on instructions, sandbox settings, and optional MCP config.
• Do not update .agents/skills/ without checking the canonical skills/ source and Codex agents/openai.yaml metadata expectations.
• Do not open broad PRs that mix unrelated skill, command, install, and release changes unless the user explicitly wants a release bundle.
• Do not leave a Codex docs change discoverable only through README prose. Link it from .codex/AGENTS.md when it affects Codex behavior.

Fast Commands

Useful local checks:

node tests/docs/codex-navigation-map.test.js
node tests/ci/codex-skill-surface.test.js
npm run command-registry:check
npm run catalog:check
node tests/run-all.js