The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(codex): add ECC navigation guide (#2525)
haelyraa3130f9ebfae
diff --git a/.codex/AGENTS.md b/.codex/AGENTS.mdindex 0364e354c..70a249ccb 100644--- a/.codex/AGENTS.md+++ b/.codex/AGENTS.md@@ -2,6 +2,9 @@This supplements the root `AGENTS.md` with Codex-specific guidance.+For repo navigation, surface ownership, and PR diff packet guidance, read+`docs/CODEX-NAVIGATION-GUIDE.md` after this supplement.+## Model Recommendations| Task Type | Recommended Model |diff --git a/README.md b/README.mdindex 10b01a457..160fd7277 100644--- a/README.md+++ b/README.md@@ -1385,7 +1385,7 @@ alwaysApply: false## Codex macOS App + CLI Support-ECC provides **first-class Codex support** for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills.+ECC provides **first-class Codex support** for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills. For repo navigation, surface ownership, and PR diff packet guidance, start with [`docs/CODEX-NAVIGATION-GUIDE.md`](docs/CODEX-NAVIGATION-GUIDE.md).### Quick Start (Codex App + CLI)diff --git a/docs/CODEX-NAVIGATION-GUIDE.md b/docs/CODEX-NAVIGATION-GUIDE.mdnew file mode 100644index 000000000..8ff4c294c--- /dev/null+++ b/docs/CODEX-NAVIGATION-GUIDE.md@@ -0,0 +1,167 @@+# 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:++```bash+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:++```markdown+## 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:++```bash+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+```diff --git a/package.json b/package.jsonindex ae74ebee2..3b056e3b3 100644--- a/package.json+++ b/package.json@@ -46,6 +46,7 @@".codex-plugin/",".cursor/",".gemini/",+ ".github/PULL_REQUEST_TEMPLATE.md",".hermes/",".kimi/",".opencode/",@@ -54,6 +55,8 @@".zed/",".mcp.json","AGENTS.md",+ "COMMANDS-QUICK-REF.md",+ "CONTRIBUTING.md","VERSION","agent.yaml","assets/ecc-icon.svg",@@ -62,6 +65,8 @@"agents/","commands/","docs/de-DE/",+ "docs/CODEX-NAVIGATION-GUIDE.md",+ "docs/COMMAND-AGENT-MAP.md","docs/ja-JP/","docs/ko-KR/","docs/pt-BR/",@@ -118,6 +123,7 @@"scripts/setup-package-manager.js","scripts/skill-create-output.js","scripts/status.js",+ "scripts/sync-ecc-to-codex.sh","scripts/work-items.js","scripts/uninstall.js","skills/agent-architecture-audit/",diff --git a/scripts/sync-ecc-to-codex.sh b/scripts/sync-ecc-to-codex.shindex 8742f539e..43ca4fa53 100755--- a/scripts/sync-ecc-to-codex.sh+++ b/scripts/sync-ecc-to-codex.sh@@ -29,6 +29,16 @@ AGENTS_ROOT_SRC="$REPO_ROOT/AGENTS.md"AGENTS_CODEX_SUPP_SRC="$REPO_ROOT/.codex/AGENTS.md"CODEX_AGENTS_SRC="$REPO_ROOT/.codex/agents"CODEX_AGENTS_DEST="$CODEX_HOME/agents"+CODEX_NAV_GUIDE_SRC="$REPO_ROOT/docs/CODEX-NAVIGATION-GUIDE.md"+CODEX_NAV_GUIDE_DEST="$CODEX_HOME/docs/CODEX-NAVIGATION-GUIDE.md"+CODEX_COMMAND_AGENT_MAP_SRC="$REPO_ROOT/docs/COMMAND-AGENT-MAP.md"+CODEX_COMMAND_AGENT_MAP_DEST="$CODEX_HOME/docs/COMMAND-AGENT-MAP.md"+CODEX_COMMANDS_QUICK_REF_SRC="$REPO_ROOT/COMMANDS-QUICK-REF.md"+CODEX_COMMANDS_QUICK_REF_DEST="$CODEX_HOME/COMMANDS-QUICK-REF.md"+CODEX_CONTRIBUTING_SRC="$REPO_ROOT/CONTRIBUTING.md"+CODEX_CONTRIBUTING_DEST="$CODEX_HOME/CONTRIBUTING.md"+CODEX_PR_TEMPLATE_SRC="$REPO_ROOT/.github/PULL_REQUEST_TEMPLATE.md"+CODEX_PR_TEMPLATE_DEST="$CODEX_HOME/.github/PULL_REQUEST_TEMPLATE.md"PROMPTS_SRC="$REPO_ROOT/commands"PROMPTS_DEST="$CODEX_HOME/prompts"BASELINE_MERGE_SCRIPT="$REPO_ROOT/scripts/codex/merge-codex-config.js"@@ -150,6 +160,11 @@ MCP_MERGE_SCRIPT="$REPO_ROOT/scripts/codex/merge-mcp-config.js"require_path "$REPO_ROOT/AGENTS.md" "ECC AGENTS.md"require_path "$AGENTS_CODEX_SUPP_SRC" "ECC Codex AGENTS supplement"require_path "$CODEX_AGENTS_SRC" "ECC Codex agent roles"+require_path "$CODEX_NAV_GUIDE_SRC" "ECC Codex navigation guide"+require_path "$CODEX_COMMAND_AGENT_MAP_SRC" "ECC command-agent map"+require_path "$CODEX_COMMANDS_QUICK_REF_SRC" "ECC commands quick reference"+require_path "$CODEX_CONTRIBUTING_SRC" "ECC contributing guide"+require_path "$CODEX_PR_TEMPLATE_SRC" "ECC PR template"require_path "$PROMPTS_SRC" "ECC commands directory"require_path "$BASELINE_MERGE_SCRIPT" "ECC Codex baseline merge script"require_path "$HOOKS_INSTALLER" "ECC global git hooks installer"@@ -259,6 +274,15 @@ elsenode "$BASELINE_MERGE_SCRIPT" "$CONFIG_FILE"fi+log "Syncing Codex navigation guide"+run_or_echo mkdir -p "$(dirname "$CODEX_NAV_GUIDE_DEST")"+run_or_echo cp "$CODEX_NAV_GUIDE_SRC" "$CODEX_NAV_GUIDE_DEST"+run_or_echo cp "$CODEX_COMMAND_AGENT_MAP_SRC" "$CODEX_COMMAND_AGENT_MAP_DEST"+run_or_echo cp "$CODEX_COMMANDS_QUICK_REF_SRC" "$CODEX_COMMANDS_QUICK_REF_DEST"+run_or_echo cp "$CODEX_CONTRIBUTING_SRC" "$CODEX_CONTRIBUTING_DEST"+run_or_echo mkdir -p "$(dirname "$CODEX_PR_TEMPLATE_DEST")"+run_or_echo cp "$CODEX_PR_TEMPLATE_SRC" "$CODEX_PR_TEMPLATE_DEST"+log "Syncing sample Codex agent role files"run_or_echo mkdir -p "$CODEX_AGENTS_DEST"for agent_file in "$CODEX_AGENTS_SRC"/*.toml; dodiff --git a/tests/docs/codex-navigation-map.test.js b/tests/docs/codex-navigation-map.test.jsnew file mode 100644index 000000000..9497c8070--- /dev/null+++ b/tests/docs/codex-navigation-map.test.js@@ -0,0 +1,80 @@+'use strict';++const assert = require('assert');+const fs = require('fs');+const path = require('path');++const repoRoot = path.resolve(__dirname, '..', '..');+const guidePath = 'docs/CODEX-NAVIGATION-GUIDE.md';++let passed = 0;+let failed = 0;++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ passed++;+ } catch (error) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${error.message}`);+ failed++;+ }+}++function read(relativePath) {+ return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');+}++console.log('\n=== Testing Codex ECC navigation map docs ===\n');++test('Codex navigation map exists and identifies canonical surfaces', () => {+ const source = read(guidePath);++ for (const required of [+ 'AGENTS.md',+ '.codex/AGENTS.md',+ '.codex/config.toml',+ '.codex/agents/',+ '.agents/skills/',+ 'docs/COMMAND-AGENT-MAP.md',+ 'commands/',+ 'skills/',+ 'agents/',+ 'rules/',+ 'hooks/',+ 'scripts/',+ 'manifests/'+ ]) {+ assert.ok(source.includes(required), `Missing canonical surface ${required}`);+ }+});++test('Codex navigation map documents PR diff packet workflow', () => {+ const source = read(guidePath);++ for (const required of [+ 'PR Diff Packet',+ 'git diff origin/main...HEAD --stat',+ 'git diff origin/main...HEAD --name-only',+ 'git log origin/main..HEAD --oneline --reverse',+ '/pr',+ '/review-pr',+ '.github/PULL_REQUEST_TEMPLATE.md',+ 'Testing Done',+ 'Risk and review lanes'+ ]) {+ assert.ok(source.includes(required), `Missing PR workflow marker ${required}`);+ }+});++test('README and Codex supplement link to the navigation map', () => {+ const readme = read('README.md');+ const codexAgents = read('.codex/AGENTS.md');++ assert.ok(readme.includes(guidePath), 'README.md must link the Codex navigation map');+ assert.ok(codexAgents.includes(guidePath), '.codex/AGENTS.md must link the Codex navigation map');+});++console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+process.exit(failed > 0 ? 1 : 0);diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.jsindex 7aa17ae62..cb556c446 100644--- a/tests/scripts/npm-publish-surface.test.js+++ b/tests/scripts/npm-publish-surface.test.js@@ -70,6 +70,7 @@ function buildExpectedPublishPaths(repoRoot) {"scripts/session-inspect.js","scripts/uninstall.js","scripts/gemini-adapt-agents.js",+ "scripts/sync-ecc-to-codex.sh","scripts/codex/check-plugin-cache.js","scripts/codex/merge-codex-config.js","scripts/codex/merge-mcp-config.js",@@ -80,9 +81,14 @@ function buildExpectedPublishPaths(repoRoot) {"install.ps1","schemas","agent.yaml",+ ".github/PULL_REQUEST_TEMPLATE.md",+ "COMMANDS-QUICK-REF.md",+ "CONTRIBUTING.md","VERSION","assets/ecc-icon.svg","assets/hero.png",+ "docs/CODEX-NAVIGATION-GUIDE.md",+ "docs/COMMAND-AGENT-MAP.md","assets/images/sponsors",]const exclusionPaths = [@@ -144,14 +150,20 @@ function main() {"scripts/release-video-suite.js","scripts/work-items.js","scripts/platform-audit.js",+ "scripts/sync-ecc-to-codex.sh","scripts/codex/check-plugin-cache.js",".gemini/GEMINI.md",".qwen/QWEN.md",".claude-plugin/plugin.json",+ ".github/PULL_REQUEST_TEMPLATE.md",".codex-plugin/plugin.json",+ "COMMANDS-QUICK-REF.md",+ "CONTRIBUTING.md","plugins/ecc/.codex-plugin/plugin.json","assets/ecc-icon.svg","assets/hero.png",+ "docs/CODEX-NAVIGATION-GUIDE.md",+ "docs/COMMAND-AGENT-MAP.md","schemas/install-state.schema.json","skills/backend-patterns/SKILL.md",]) {diff --git a/tests/scripts/sync-ecc-to-codex.test.js b/tests/scripts/sync-ecc-to-codex.test.jsindex 2626c13c3..61a5b128e 100644--- a/tests/scripts/sync-ecc-to-codex.test.js+++ b/tests/scripts/sync-ecc-to-codex.test.js@@ -69,11 +69,32 @@ function runTests() {if (test('filesystem-changing calls use argv-form run_or_echo invocations', () => {assert.ok(source.includes('run_or_echo mkdir -p "$BACKUP_DIR"'), 'mkdir should use argv form');+ assert.ok(source.includes('run_or_echo mkdir -p "$(dirname "$CODEX_NAV_GUIDE_DEST")"'), 'Codex guide destination directory should use argv form');+ assert.ok(source.includes('run_or_echo cp "$CODEX_NAV_GUIDE_SRC" "$CODEX_NAV_GUIDE_DEST"'), 'Codex guide copy should use argv form');+ assert.ok(source.includes('run_or_echo cp "$CODEX_COMMAND_AGENT_MAP_SRC" "$CODEX_COMMAND_AGENT_MAP_DEST"'), 'Command-agent map copy should use argv form');+ assert.ok(source.includes('run_or_echo cp "$CODEX_COMMANDS_QUICK_REF_SRC" "$CODEX_COMMANDS_QUICK_REF_DEST"'), 'Commands quick reference copy should use argv form');+ assert.ok(source.includes('run_or_echo cp "$CODEX_CONTRIBUTING_SRC" "$CODEX_CONTRIBUTING_DEST"'), 'Contributing guide copy should use argv form');+ assert.ok(source.includes('run_or_echo mkdir -p "$(dirname "$CODEX_PR_TEMPLATE_DEST")"'), 'PR template destination directory should use argv form');+ assert.ok(source.includes('run_or_echo cp "$CODEX_PR_TEMPLATE_SRC" "$CODEX_PR_TEMPLATE_DEST"'), 'PR template copy should use argv form');// Skills sync rm/cp calls were removed — Codex reads from ~/.agents/skills/ nativelyassert.ok(!source.includes('run_or_echo rm -rf "$dest"'), 'skill sync rm should be removed');assert.ok(!source.includes('run_or_echo cp -R "$skill_dir" "$dest"'), 'skill sync cp should be removed');})) passed++; else failed++;+ if (test('sync script carries the Codex navigation guide referenced by AGENTS', () => {+ assert.ok(source.includes('CODEX_NAV_GUIDE_SRC="$REPO_ROOT/docs/CODEX-NAVIGATION-GUIDE.md"'), 'Expected source path for Codex navigation guide');+ assert.ok(source.includes('CODEX_NAV_GUIDE_DEST="$CODEX_HOME/docs/CODEX-NAVIGATION-GUIDE.md"'), 'Expected destination path for Codex navigation guide');+ assert.ok(source.includes('require_path "$CODEX_NAV_GUIDE_SRC" "ECC Codex navigation guide"'), 'Expected sync preflight for Codex navigation guide');+ for (const required of [+ 'CODEX_COMMAND_AGENT_MAP_SRC="$REPO_ROOT/docs/COMMAND-AGENT-MAP.md"',+ 'CODEX_COMMANDS_QUICK_REF_SRC="$REPO_ROOT/COMMANDS-QUICK-REF.md"',+ 'CODEX_CONTRIBUTING_SRC="$REPO_ROOT/CONTRIBUTING.md"',+ 'CODEX_PR_TEMPLATE_SRC="$REPO_ROOT/.github/PULL_REQUEST_TEMPLATE.md"'+ ]) {+ assert.ok(source.includes(required), `Expected synced reference source ${required}`);+ }+ })) passed++; else failed++;+if (test('sync script avoids GNU-only grep -P parsing', () => {assert.ok(!source.includes('grep -oP'), 'sync-ecc-to-codex.sh should remain portable across BSD and GNU environments');})) passed++; else failed++;