notque/vexjoy-agent / skills/process/pr-workflow
pr-workflow
FlaggedPull request lifecycle: commit, codex review, sync, review, fix, status, cleanup, and PR mining. Use when user wants to commit changes, get a second-opinion code review from Codex, push changes, create a PR, check PR status, fix review comments, clean up branches after merge, or mine tribal knowledge from PR reviews. Use for "commit my changes", "codex review", "push my changes", "create a PR", "pr status", "fix PR comments", "clean up branches", "mine PRs", or "address feedback".
references/codex-review-invocation.md
View on GitHub# Codex Invocation and Reporting
Detailed phases 2-4 of the pr-workflow skill's codex-review intent: how to invoke `codex exec`,
assess the feedback critically, and deliver the final unified report.
> Under Claude Code, codex review is an explicit cross-provider second-opinion tool — a deliberate OpenAI-lane call, not the automatic model default.
---
### Phase 2: Invoke Codex
**Goal**: Run `codex exec` with the right flags and a well-constructed prompt.
**Step 1: Create temp file for output.**
```bash
TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX)
```
Use exactly this pattern (no extension after the X's). macOS `mktemp` breaks
when you append an extension like `.md` after the template characters.
**Step 2: Construct the prompt.**
The prompt to Codex should have four parts:
1. **Context** -- the brief summary from Phase 1
2. **What to review** -- tell Codex which git command to run or which files to
read. Let Codex access the filesystem directly rather than embedding diffs in
the prompt, because Codex runs in its own sandbox with repo access and
embedding large diffs wastes tokens and loses formatting.
3. **Focus areas** -- any specific concerns (or "general review" if none)
4. **Output format** -- request the structured format below
Tell Codex to structure its output as:
```
## CRITICAL ISSUES
[Issues that would cause bugs, security vulnerabilities, data loss, or crashes.
Empty section if none found.]
## IMPROVEMENTS
[Suggestions for better code quality, performance, readability, or maintainability.
Not blocking but worth considering.]
## POSITIVE NOTES
[What's done well -- good patterns, clean abstractions, solid test coverage.
Reinforcing good practices matters.]
## SUMMARY
[2-3 sentence overall assessment: is this change ready, what's the biggest risk,
what's the biggest strength.]
```
**Step 3: Run codex exec.**
**Preferred: Use `codex exec review`** (purpose-built review subcommand):
```bash
codex exec review \
--base main \
-m gpt-5.6-sol \
-c 'model_reasoning_effort="xhigh"' \
--ephemeral \
--dangerously-bypass-approvals-and-sandbox \
-o "$TMPFILE"
```
The `review` subcommand handles diff computation internally. Use `--base` for
branch reviews, `--commit <SHA>` for single commits, or `--uncommitted` for
unstaged changes. Note: `--base`/`--commit` and a custom `[PROMPT]` argument
are mutually exclusive -- you cannot pass both.
**Fallback: Use `codex exec` with a custom prompt** when you need focus areas
or custom instructions:
```bash
codex exec \
-m gpt-5.6-sol \
-c 'model_reasoning_effort="xhigh"' \
--ephemeral \
--dangerously-bypass-approvals-and-sandbox \
-o "$TMPFILE" \
"YOUR_CONSTRUCTED_PROMPT_HERE"
```
For multi-line prompts, use a heredoc:
```bash
codex exec \
-m gpt-5.6-sol \
-c 'model_reasoning_effort="xhigh"' \
--ephemeral \
--dangerously-bypass-approvals-and-sandbox \
-o "$TMPFILE" \
"$(cat <<'PROMPT'
[Your constructed prompt here]
PROMPT
)"
```
Flag explanation:
- `-m gpt-5.6-sol` -- use the benchmark-selected high-risk review model
- `-c 'model_reasoning_effort="xhigh"'` -- the high-risk review lane; use
`max` only with an explicit exceptional override
- `--ephemeral` -- don't persist the Codex session (this is a one-shot review)
- `--dangerously-bypass-approvals-and-sandbox` -- bypass the bwrap sandbox
which fails in containerized/VM environments with "loopback: Failed
RTM_NEWADDR: Operation not permitted". This is safe because Claude Code
already provides external sandboxing and the review is read-only by nature.
The `-s read-only` flag is incompatible with this bypass (use one or the
other, not both)
- `-o "$TMPFILE"` -- capture Codex's output to the temp file for processing
**Step 4: Check exit code.**
If `codex exec` exits non-zero, report the error to the user and stop. Do not
retry automatically because Codex failures are typically due to API issues,
authentication problems, or prompt-length limits that won't resolve on retry.
Read the stderr output and include it in your error report so the user can
diagnose (e.g., rate limiting, invalid API key, model unavailable).
Gate: Codex exited 0 and `$TMPFILE` contains review output. Proceed to Phase 3.
---
### Phase 3: Assess and Filter
**Goal**: Critically evaluate Codex's feedback before presenting it. Claude is
the reviewer of the reviewer -- Codex provides signal, not authority.
**Step 1: Read the output.**
```bash
cat "$TMPFILE"
```
**Step 2: Assess each finding.**
For every issue Codex raised, evaluate:
| Question | Action |
|----------|--------|
| Is this actually correct? | Read the relevant code yourself. Codex may have misread the logic, missed context from other files, or misunderstood the intent. |
| Is this already handled elsewhere? | Check if the concern is addressed in code Codex didn't examine (e.g., middleware, error handling upstream). |
| Does this apply to this project's conventions? | Check the project's CLAUDE.md or style guides. What's an failure mode generally may be the accepted convention here. |
| Is the severity right? | Codex may flag a style preference as critical, or miss that a "minor" issue is actually a data-loss risk in this context. |
**Step 3: Classify each finding.**
After assessment, classify each Codex finding into one of:
- **Agree** -- finding is correct and properly scoped. Include it in the report.
- **Agree with modification** -- finding is directionally right but needs nuance
(different severity, narrower scope, additional context). Include the modified
version.
- **Disagree** -- finding is incorrect, not applicable, or already handled.
Mention it briefly with your reasoning so the user understands why it was
filtered, because silently dropping findings erodes trust.
**Step 4: Add Claude's own observations.**
If you noticed issues that Codex missed, add them. The cross-model approach works
both ways -- each model catches things the other doesn't.
Gate: Every Codex finding has been assessed. Proceed to Phase 4.
---
### Phase 4: Report
**Goal**: Present the unified review to the user.
Structure the report as:
```markdown
## Codex Code Review (GPT-5.6 Sol xhigh)
**Scope**: [what was reviewed -- e.g., "git diff main...HEAD (12 files)"]
### Critical Issues
[Agreed findings at critical severity, with Claude's assessment]
### Improvements
[Agreed suggestions, modified suggestions with Claude's notes]
### Positive Notes
[What both models agree is well-done]
### Filtered Findings
[Findings Claude disagreed with, plus reasoning -- keep brief]
### Claude's Additional Observations
[Issues Claude found that Codex missed, if any]
### Summary
[Combined assessment from both models]
```
**Clean up** the temp file:
```bash
rm -f "$TMPFILE"
```
---
## Integration Boundaries
### Treat Codex output as a second opinion
Codex is a second opinion, not a senior reviewer with merge authority. Its
findings need the same scrutiny you'd apply to any automated tool output. It can
hallucinate issues, misread control flow, or flag patterns that are intentional
in this codebase.
### Report failures instead of retrying
If Codex fails (non-zero exit, empty output, garbled response), report it to the
user and let them decide. Automatic retry loops burn API quota and rarely fix the
underlying problem (auth issues, rate limits, model errors).
### Point Codex at git commands instead of embedding diffs
Codex has filesystem access in its sandbox. Tell it which git command to run
(e.g., "run `git diff main...HEAD` to see the changes") rather than pasting the
diff into the prompt. Embedded diffs waste tokens, lose formatting, and hit
prompt length limits on large changes.
### Always run the assessment phase
The entire value of this skill is cross-model triangulation. If Claude just
passes through Codex output verbatim, the user could have run `codex exec`
themselves. The assessment phase is where Claude adds context, catches errors,
and filters noise.
### Present fixes for user confirmation before applying
Even if a finding is clearly correct and the fix is obvious, present it to the
user and let them decide. The user invoked this skill for a review, not for
autonomous code changes.
---
## Error Handling
**Error: `codex: command not found`**
- Cause: Codex CLI is not installed or not in PATH
- Solution: Tell the user to install it: `npm install -g @openai/codex`
(or check their installation docs). Verify with `codex --version`.
**Error: Non-zero exit code from `codex exec`**
- Cause: API authentication failure, rate limiting, model unavailable, or
prompt too long
- Solution: Read stderr, report the specific error to the user. Do not retry.
**Error: Empty output file**
- Cause: Codex ran but produced no output (possible timeout or model error)
- Solution: Report to user. Check if `$TMPFILE` exists but is empty vs.
doesn't exist. Include any stderr output.
**Error: Output is not in expected format**
- Cause: Codex didn't follow the structured output format requested
- Solution: Still process the output -- extract what findings you can and
assess them. Note in the report that Codex output was unstructured.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |