phx-codex-loop
Fix Elixir/Phoenix code until Codex CLI review comes back clean — bounded
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phx-codex-loop
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Codex Loop (fix until clean)
Critic→Refiner loop with the Codex CLI as external critic: review → fix
approved findings → verify → re-review, until codex is clean or rounds run
out. Codex reviews; Claude fixes. Complements phx-review (Claude panel)
— run either or both before a PR.
Usage
phx-codex-loop # diff vs default branch, interactive
phx-codex-loop --uncommitted # staged + unstaged + untracked
phx-codex-loop --base develop # explicit base branch
phx-codex-loop --auto # auto-approve P0/P1/P2, skip P3
phx-codex-loop --max-rounds 2 # default 3
Iron Laws
- BOUNDED rounds — never exceed --max-rounds (default 3) — each round costs codex quota; report remaining findings instead of looping on
- Verify BEFORE re-review —
mix compile --warnings-as-errors+ tests must pass before burning a codex round on broken code - NEVER commit or push — leave git to the user
- Codex findings get Iron Law scrutiny — decline suggestions that violate an Iron Law, with explanation in the round report
- Skipped findings are reported, never dropped — every finding ends as fixed, declined (with reason), or deferred-by-user
- Missing CLI stops the skill with an install hint — suggest
phx-reviewas the codex-free alternative; never crash
Workflow
Step 1: Preflight
Run command -v codex. If missing: STOP.
Show the install hint (brew install codex or npm i -g @openai/codex,
then codex login; codex doctor to diagnose) and suggest phx-review.
Then two cheap checks that save review rounds:
- Dirty tree (
git status --short, only when using--base): codex inspects working-tree state too and WILL flag local dirt (stray edits, dirty submodules) as findings. Surface the dirt and ask: clean/stash first, or proceed knowing round 1 may spend findings on it. - Missing rubric: if
AGENTS.mdhas no## Review guidelinessection, note once thatphx-initinstalls the Elixir rubric that steers codex priorities — then proceed (it works without, on defaults).
Step 2: Detect Diff Mode
- Flag passed (
--base/--uncommitted) → use as given - Commits ahead of the default branch →
--base {default} - No commits yet →
--uncommitted
Step 3: Review Round (max --max-rounds, default 3)
Review — ONE foreground Bash call, explicit
timeout: 600000(large diffs run 10+ min). On timeout with the process alive: ONEuntil [ -f {out} ]; do sleep 5; donewait — never poll-spam orpkilla running review (quota is spent either way). ALWAYS silence the streams — only the-ofile matters (10k+ lines otherwise):codex exec review --base {branch} --ephemeral \ -o /tmp/codex-round-{n}.md > /tmp/codex-round-{n}.log 2>&1NEVER pass custom instructions with a diff-mode flag — the CLI rejects the combination; the rubric comes from AGENTS.md
## Review guidelines(phx-init). Parse the output file, NOT the exit code (0 even with findings). Recipes:references/codex-cli.md.Retired model (exit 1, no
-ofile, log:model is not supported/Model not found): resolve the account default —MODEL=$(codex debug models | jq -r '.models | map(select(.visibility == "list")) | sort_by(.priority) | .[0].slug')— retry once with-m "$MODEL" -c review_model="$MODEL"(both: a pinnedreview_modelbeats-m), reuse it every round, never hardcode a slug. Tell the user once to setmodel/review_model = "$MODEL"in~/.codex/config.toml.Clean check — parse the output file; no
- [P{n}]bullets means CLEAN → go to Step 5.
Step 4: Triage, Fix, Verify
Triage — emit the findings table (
# | P | file:line | title | proposed action) as visible response text BEFORE anyAskUserQuestioncall — a table composed only in thinking never renders. Then ask approve-or-skip per finding (AskUserQuestion). With--auto: approve P0/P1/P2, skip P3 (list skipped in the round report).Fix — apply approved fixes with user-visible diffs. Check each against Iron Laws first (Law 4).
Verify — scoped, before the next round:
mix format {changed_files} && \ mix compile --warnings-as-errors && mix test {affected_tests}If verification fails 3 times, STOP with a BLOCKER report — do not burn another codex round on broken code.
Next round (n+1) — back to Step 3.
Step 5: Final Report
## Codex Loop Report — {CLEAN | MAX ROUNDS REACHED | BLOCKED}
Rounds: {n}/{max} | Fixed: {n} | Declined (Iron Law): {n} | Deferred: {n}
{per-round: findings → outcome}
{remaining findings if not CLEAN}
On CLEAN: suggest phx-compound for non-obvious fixes, then commit/PR.
On MAX ROUNDS: list remaining findings; offer phx-plan to convert them
into a follow-up plan.
Integration
implement → phx-codex-loop (YOU ARE HERE) → clean → commit/PR → phx-watch-pr --codex
↑ or arrive from phx-review --codex verdict REQUIRES CHANGES
References
references/codex-cli.md— invocation recipes, parse patterns, verified gotchas (CLI 0.142.5; model fallback 0.162.1)
Files (claude-elixir-phoenix)
-
references
-
codex-cli.md 5.7 KB
Loading…
-
-
SKILL.md 5.5 KB
--- name: phx-codex-loop description: Fix Elixir/Phoenix code until Codex CLI review comes back clean — bounded review, fix, verify loop before opening a PR. Use when codex is installed and you want an external cross-model critic on your changes before pushing. --- # Codex Loop (fix until clean) Critic→Refiner loop with the Codex CLI as external critic: review → fix approved findings → verify → re-review, until codex is clean or rounds run out. Codex reviews; Claude fixes. Complements `phx-review` (Claude panel) — run either or both before a PR. ## Usage ``` phx-codex-loop # diff vs default branch, interactive phx-codex-loop --uncommitted # staged + unstaged + untracked phx-codex-loop --base develop # explicit base branch phx-codex-loop --auto # auto-approve P0/P1/P2, skip P3 phx-codex-loop --max-rounds 2 # default 3 ``` ## Iron Laws 1. **BOUNDED rounds — never exceed --max-rounds (default 3)** — each round costs codex quota; report remaining findings instead of looping on 2. **Verify BEFORE re-review** — `mix compile --warnings-as-errors` + tests must pass before burning a codex round on broken code 3. **NEVER commit or push** — leave git to the user 4. **Codex findings get Iron Law scrutiny** — decline suggestions that violate an Iron Law, with explanation in the round report 5. **Skipped findings are reported, never dropped** — every finding ends as fixed, declined (with reason), or deferred-by-user 6. **Missing CLI stops the skill with an install hint** — suggest `phx-review` as the codex-free alternative; never crash ## Workflow ### Step 1: Preflight Run `command -v codex`. If missing: STOP. Show the install hint (`brew install codex` or `npm i -g @openai/codex`, then `codex login`; `codex doctor` to diagnose) and suggest `phx-review`. Then two cheap checks that save review rounds: - **Dirty tree** (`git status --short`, only when using `--base`): codex inspects working-tree state too and WILL flag local dirt (stray edits, dirty submodules) as findings. Surface the dirt and ask: clean/stash first, or proceed knowing round 1 may spend findings on it. - **Missing rubric**: if `AGENTS.md` has no `## Review guidelines` section, note once that `phx-init` installs the Elixir rubric that steers codex priorities — then proceed (it works without, on defaults). ### Step 2: Detect Diff Mode - **Flag passed** (`--base`/`--uncommitted`) → use as given - **Commits ahead of the default branch** → `--base {default}` - **No commits yet** → `--uncommitted` ### Step 3: Review Round (max `--max-rounds`, default 3) 1. **Review** — ONE foreground Bash call, explicit `timeout: 600000` (large diffs run 10+ min). On timeout with the process alive: ONE `until [ -f {out} ]; do sleep 5; done` wait — never poll-spam or `pkill` a running review (quota is spent either way). ALWAYS silence the streams — only the `-o` file matters (10k+ lines otherwise): ```bash codex exec review --base {branch} --ephemeral \ -o /tmp/codex-round-{n}.md > /tmp/codex-round-{n}.log 2>&1 ``` NEVER pass custom instructions with a diff-mode flag — the CLI rejects the combination; the rubric comes from AGENTS.md `## Review guidelines` (`phx-init`). Parse the output file, NOT the exit code (0 even with findings). Recipes: `references/codex-cli.md`. **Retired model** (exit 1, no `-o` file, log: `model is not supported` / `Model not found`): resolve the account default — `MODEL=$(codex debug models | jq -r '.models | map(select(.visibility == "list")) | sort_by(.priority) | .[0].slug')` — retry once with `-m "$MODEL" -c review_model="$MODEL"` (both: a pinned `review_model` beats `-m`), reuse it every round, never hardcode a slug. Tell the user once to set `model`/`review_model = "$MODEL"` in `~/.codex/config.toml`. 2. **Clean check** — parse the output file; no `- [P{n}]` bullets means CLEAN → go to Step 5. ### Step 4: Triage, Fix, Verify 1. **Triage** — emit the findings table (`# | P | file:line | title | proposed action`) as **visible response text BEFORE any `AskUserQuestion` call** — a table composed only in thinking never renders. Then ask approve-or-skip per finding (`AskUserQuestion`). With `--auto`: approve P0/P1/P2, skip P3 (list skipped in the round report). 2. **Fix** — apply approved fixes with user-visible diffs. Check each against Iron Laws first (Law 4). 3. **Verify** — scoped, before the next round: ```bash mix format {changed_files} && \ mix compile --warnings-as-errors && mix test {affected_tests} ``` If verification fails 3 times, STOP with a BLOCKER report — do not burn another codex round on broken code. 4. Next round (n+1) — back to Step 3. ### Step 5: Final Report ```markdown ## Codex Loop Report — {CLEAN | MAX ROUNDS REACHED | BLOCKED} Rounds: {n}/{max} | Fixed: {n} | Declined (Iron Law): {n} | Deferred: {n} {per-round: findings → outcome} {remaining findings if not CLEAN} ``` On CLEAN: suggest `phx-compound` for non-obvious fixes, then commit/PR. On MAX ROUNDS: list remaining findings; offer `phx-plan` to convert them into a follow-up plan. ## Integration ```text implement → phx-codex-loop (YOU ARE HERE) → clean → commit/PR → phx-watch-pr --codex ↑ or arrive from phx-review --codex verdict REQUIRES CHANGES ``` ## References - `references/codex-cli.md` — invocation recipes, parse patterns, verified gotchas (CLI 0.142.5; model fallback 0.162.1)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.