lploc94/codex-codebase-review

Codex Codebase Review

Purpose

Review large codebases exceeding single-session context limits. Chunks by module, reviews independently, synthesizes cross-cutting findings.

When to Use

Full codebase audit (50-500+ files). For diff review use /codex-impl-review.

Prerequisites

• Source files in working directory.

Runner

RUNNER="{{RUNNER_PATH}}" SKILLS_DIR="{{SKILLS_DIR}}" json_esc() { printf '%s' "$1" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>process.stdout.write(JSON.stringify(d)))'; }

Critical Rules (DO NOT skip)

• Stdin: printf '%s' "$PROMPT" | node "$RUNNER" ... -- NEVER echo. JSON via heredoc.
• Validate: init output must start with CODEX_SESSION:. start/resume must return valid JSON. CODEX_NOT_FOUND->tell user install codex.
• status === "completed" means Codex's turn is done -- NOT that the review is over. Parse results and continue.
• Errors: failed->retry once, still fails->skip chunk. >50% failed->warn user. timeout->report partial. stalled+recoverable->stop->recovery resume->poll; not recoverable->report partial. Cleanup sequencing: finalize+stop ONLY after recovery resolves.
• Cleanup: ALWAYS finalize + stop ALL tracked sessions, even on failure/timeout.
• Runner manages all session state -- NEVER read/write session files manually.
• For detailed error flows -> Read references/protocol.md

Workflow

1. Collect Inputs

Effort: <50 files=medium, 50-200=high, >200=xhigh. Ask parallel factor (default 1), focus areas (default all). Effort levels: low=~10-20min/chunk, medium=~15-30min, high=~20-40min, xhigh=~30-60min.

2. Discovery

2a) Detect project type from markers (package.json, go.mod, Cargo.toml, etc.). 2b) List source files (extensions: js, ts, jsx, tsx, py, go, rs, java, cs, rb, php, vue, svelte). Exclude: node_modules, .git, dist, build, vendor, pycache, target, .next, .nuxt, coverage. 2c) Identify module boundaries: group by top-level dir under source root (depth 2). 2d) Count lines per module. 2e) Present module table for confirmation (effort >= medium).

3. Chunking

Target: 500-2000 lines/chunk. Module <300 lines -> merge with related. Module >2500 -> split by sub-dir. Order: config/types first -> core/utils -> features -> tests last. Present chunk plan (effort >= medium).

4. Review Loop

Track: ALL_SESSION_DIRS=(). For each chunk (sequential or parallel batches): 4a) Init: node "$RUNNER" init --skill-name codex-codebase-review --working-dir "$PWD". Track session. 4b) Render: template=chunk-review. Placeholders: PROJECT_TYPE, CHUNK_NAME, FOCUS_AREAS, FILE_LIST, CONTEXT_SUMMARY. 4c) Start + 4d) Poll. Report: "Chunk {N}/{TOTAL} [{name}]". 4e) Parse review.blocks[]. 4f) Context propagation: high/critical findings (~2000 tokens cap). 4g) Progress report. 4h) Finalize chunk. Parallel mode: batch by parallel_factor, start all simultaneously, poll round-robin, propagate context between batches only.

5. Cross-cutting Analysis (Claude-only)

Collect all ISSUE-{N} from all chunks -> group by file/category/severity -> find cross-module patterns -> generate CROSS-{N}. Categories by effort: pattern inconsistencies + DRY (all); API contracts (medium+); integration + architecture (high+).

6. Validation (effort >= high)

Init new session, render template=validation with CROSS_FINDINGS. Start + poll. Parse RESPONSE-{N} (accept/reject/revise). Rounds: high=1 max, xhigh=up to 2. Finalize validation session.

7. Final Report

Project type, Total files/lines, Chunks reviewed, Total issues, Cross-cutting findings. Per-module findings by severity, CROSS-{N} by category, architecture assessment (high+), action items (P0/P1/P2), per-chunk stats.

8. Session Finalization

Create master session, finalize with aggregated stats. Report master session path.

9. Cleanup

Stop ALL tracked sessions (chunk + validation + master). Always run. Chunk failure: retry once, skip on second fail. All failed: Claude fallback review top 5 chunks.

Flavor Text Triggers

SKILL_START, POLL_WAITING, CODEX_RETURNED, CHUNK_PROGRESS, CHUNK_CROSS, FINAL_SUMMARY

Rules

• If in plan mode, exit first. No cross-contamination between chunk sessions.
• Context propagation: only high/critical, capped ~2000 tokens. Scope is full codebase only.