codex-code-review

Files (5)

• SKILL.md
• backlog-integration.md · references/
• codex-cli-reference.md · references/
• review-format.md · references/
• parse_codex_review.sh · scripts/

SKILL.md (first lines)

# 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 <SHA>"** — 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 <SHA>|--base <BRANCH>]
└──────┬───────────────────┘   Output goes to .agent/reviews/review-<timestamp>.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 < 3?     │
  └────┬───────────────┬─┘
       │ YES           │ NO
       │               └─→ SUMMARIZE & ASK USER TO CONTINUE
       │                   (or exit if user declines)
       ▼
  Re-run codex review (step 1, same files/scope)
  Loop back to step 2
```

### Cycle Management

- **Cycle 1**: Initial review after implementation
- **Cycle 2**: After first remediation
- **Cycle 3**: After second remediation
- **After Cycle 3**: If P0/P1 remain, stop. Summarize findings and ask user if they want to continue (rare; usually indicates design-level issues)

---

## Decision Tree: Handling Findings

### When review shows P0/P1 findings (verdict: REQUEST CHANGES)

1. Read the codex review markdown file
2. Extract each P0 and P1 finding with:
   - Finding ID and title
   - File location
   - Suggested fix
3. Fix ONLY the cited findings in the code
4. Do NOT refactor, do NOT introduce new functionality
5. If a fix requires significant design changes, note this and let codex re-evaluate on next cycle
6. Amend your commit OR create a new one (user's choice via git config; by default amend to keep one commit at end)
7. Increment cycle counter and re-run codex review

### When review shows P2-P4 findings (verdict: APPROVE or PASS WITH ISSUES)

1. For each P2/P3 finding, decide:
   - **Fix now**: You have discretion; implement the improvement in the same cycle
   - **Defer**: Create a backlog issue with:
     - Type label: `remediation`
     - Severity label: `P2` or `P3`
     - Custom label: `origin:ai-review`
     - Implementation plan based on codex's suggested approach
     - Acceptance criteria from the review

2. Examples:
   ```
   # P2 finding deferred to backlog
   backlog task create "Code clarity: add docstring to validateInput()" \
     -d "Review finding: missing documentation on public function" \
     -l remediation -p 2 \
     --ac "Add docstring explaining parameter types and return value" \
     --plan "Add JSDoc comment above function definition per project style"
   ```

### When review shows no findings (verdict: APPROVE)

Exit the loop. Code is clean. Proceed to test review (if applicable) or commit for merge.

---

## Monorepo Handling

From NickCrew/Claude-Cortex, MIT.

More from NickCrew/Claude-Cortex