Codex Code Review

Codex Code Review Loop

Overview

This skill orchestrates the complete remediation workflow for code under review by the codex agent. It handles:

• Requesting reviews from codex using the codex --full-auto c CLI
• Parsing review output to identify P0 (security/correctness), P1 (reliability), P2-P4 (quality) findings
• Remediating critical issues through up to 3 review-fix-review cycles
• Deferring quality improvements to backlog with implementation plans and origin:ai-review labels
• Monorepo handling for selective file commits when working alongside other agents
• Circuit breaker escalation after 3 cycles if P0/P1 issues persist

When to Use

Trigger this skill when code requires codex review. Common usage patterns:

• "codex review this code" — Initiate review loop on current changes
• "run codex review on my changes" — Same as above
• "codex review --uncommitted" — Review all uncommitted changes
• "codex review --commit " — Review specific commit in monorepo
• Questions about codex (e.g., "how does codex work?") — Do not trigger this skill; answer directly

Do not trigger on questions. Only activate for direct review requests.

---

The Review Loop: Step by Step

ENTRY: User requests codex review or skill is triggered by "codex review" in a message

┌──────────────────────────┐
│ 1. INVOKE CODEX REVIEW   │ ← Run: codex --full-auto c [--uncommitted|--commit |--base ]
└──────┬───────────────────┘   Output goes to .agent/reviews/review-.md
       │
       ▼
┌──────────────────────────┐
│ 2. READ & PARSE REVIEW   │ ← Read markdown file, extract P0/P1/P2-P4 findings and verdict
└──────┬───────────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  ANY P0/P1?              NO         FILE P2-P4 ISSUES → Exit loop
       │                              (via backlog CLI)
       │ YES                         Create issue per finding with
       │                             - label: origin:ai-review
  ┌────────────────┐                - Implementation plan
  │ 3. REMEDIATE   │                - Priority (P2 or P3)
  │ P0/P1 FINDINGS │
  └────┬───────────┘
       │ (amend commit or new changes)
       │
       ▼
  ┌──────────────────────┐
  │ 4. LOOP CHECK        │
  │ Cycle count 
   git commit -m "Your commit message"
   ```
2. Note the commit SHA
3. Run review on your commit:
   ```bash
   codex --full-auto c --commit 
   ```
4. Remediate by amending your commit:
   ```bash
   git add 
   git commit --amend --no-edit
   ```
   (Preserve the original message; the amend adds the fixes)
5. Loop back to review as normal

**Result:** One clean commit with your changes and fixes. Other agents' work remains separate.

---

## File Locations

- **Review output:** `.agent/reviews/review-.md` (relative to project root)
- **One review file per cycle** — new file created on each `codex --full-auto c` invocation
- **Always read the latest file** — check the timestamp to ensure you're reading the current cycle's review

---

## Bundled References

**See `references/codex-cli-reference.md`** for:
- Complete codex CLI syntax and invocation patterns
- How to select `--uncommitted` vs. `--commit` vs. `--base`
- When to use each mode

**See `references/review-format.md`** for:
- Structure of the review markdown output
- How to parse P0/P1/P2/P3 sections
- How to identify the verdict (APPROVE / REQUEST CHANGES / BLOCKED)
- Example review output

**See `references/backlog-integration.md`** for:
- How to create backlog issues from deferred findings
- Label and priority conventions
- Implementation plan templates
- Examples of issues filed from reviews

**See `scripts/parse_codex_review.sh`** for:
- Helper script to extract findings from review markdown
- Counts P0/P1/P2/P3 per cycle
- Quick verdict extraction

---

## Key Rules

1. **All P0/P1 must be fixed** before exiting the loop. No exceptions.
2. **P2-P4 can be deferred** to backlog or fixed at your discretion.
3. **File one issue per finding** — do not batch unrelated P2/P3s into one issue.
4. **Deferred issues must include a plan** — codex identified the problem; you provide the structured approach.
5. **Amend commits** (not new commits) during remediation so you end with one clean commit.
6. **Max 3 review cycles** — after cycle 3, if P0/P1 remain, summarize and ask user to continue.
7. **In monorepos, commit selectively** — review and fix only the files you touched.

---

## Escalation: When Circuit Breaker Triggers

After 3 review cycles, if P0/P1 findings persist:

1. Stop remediating. Do not attempt a 4th cycle.
2. Produce a structured summary including:
   - What was attempted in each cycle
   - What P0/P1 findings remain
   - Why they persist (agent assessment — design issue? conflicting requirements? ambiguity in spec?)
   - Recommended human action
3. Present this summary to the user and ask how to proceed.

Escalation usually indicates the original task spec needs clarification or the code requires architectural changes beyond remediation scope.

---

## Integration with Other Skills

- **backlog-md**: File deferred P2/P3 findings using `backlog task create` with `origin:ai-review` label
- **git-ops**: Commit handling, amending, and selective staging in monorepos
- **requesting-code-review**: Use after codex review loop completes if human code review is also required

---

## Quick Reference: The Full Workflow

1. User: "codex review"

│ ▼

1. Invoke: codex --full-auto c --uncommitted

│ ▼

1. Read: .agent/reviews/review-.md

│ ├─────────────────────────────────────────┐ ▼ ▼ P0/P1 FOUND? NO FILE P2-P4 ISSUES ├─ YES: Fix + Loop ────────────────► backlog task create ... --plan "..." └─ NO: File P2-P4 → Exit (each finding = one issue) │ ├─ Cycle 1 → Fix → Review ├─ Cycle 2 → Fix → Review ├─ Cycle 3 → Fix → Review │ └─ If P0/P1 remain → Summarize + Ask User │ └─► Continue? (rare) / Stop & Escalate

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NickCrew](https://github.com/NickCrew)
- **Source:** [NickCrew/Claude-Cortex](https://github.com/NickCrew/Claude-Cortex)
- **License:** MIT
- **Homepage:** https://cortex.atlascrew.dev/

Install and usage instructions live in the source repository linked above.