Task setup
Use the current request and repository instructions to establish the exact scope and existing authorization. Keep unrelated changes and account boundaries intact. Verify referenced CLIs, scripts, and skills are available before relying on them; use only the capabilities needed for this workflow.
Do not run plugin upgrades, telemetry, session pruning, onboarding, or preference prompts as a side effect of this task. Do not load unrelated skill catalogs. Ask a question only when a material decision or missing authorization remains unresolved; prepare a concrete result before any required approval.
Use the configured model and proportional reasoning. Run focused validation and the repository's required checks; broaden only for a failure or unresolved risk. Report verified outcomes, remaining failures, and unavailable coverage. Do not invent coverage percentages, speedups, or human-versus-agent time estimates.
This is a read-only review or consultation. Temporary output capture is allowed when needed; modifying repository files, publishing, or changing configuration requires separate task authorization. Preserve OAuth authentication and the read-only Codex sandbox.
Step 0: Detect base branch
Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
Check if a PR already exists for this branch:
gh pr view --json baseRefName -q .baseRefNameIf this succeeds, use the printed branch name as the base branch.If no PR exists (command fails), detect the repo's default branch:
gh repo view --json defaultBranchRef -q .defaultBranchRef.nameIf both commands fail, fall back to
main.
Print the detected base branch name. In every subsequent git diff, git log,
git fetch, git merge, and gh pr create command, substitute the detected
branch name wherever the instructions say "the base branch."
/codex — Multi-AI Second Opinion
You are running the /codex skill. This wraps the OpenAI Codex CLI to get an independent,
brutally honest second opinion from a different AI system.
Codex provides an independent technical review: direct, concise, precise, and willing to challenge assumptions, catches things you might miss. Present its output faithfully, not summarized.
Step 0: Check codex binary
CODEX_BIN=$(which codex 2>/dev/null || echo "")
[ -z "$CODEX_BIN" ] && echo "NOT_FOUND" || echo "FOUND: $CODEX_BIN"
If NOT_FOUND: stop and tell the user:
"Codex CLI not found. Install it: npm install -g @openai/codex or see https://github.com/openai/codex"
Step 1: Detect mode
Parse the user's input to determine which mode to run:
/codex reviewor/codex review <instructions>— Review mode (Step 2A)/codex challengeor/codex challenge <focus>— Challenge mode (Step 2B)/codexwith no arguments — Auto-detect:- Check for a diff (with fallback if origin isn't available):
git diff origin/<base> --stat 2>/dev/null | tail -1 || git diff <base> --stat 2>/dev/null | tail -1 - If a diff exists, ask with AskUserQuestion (header "Codex mode"):
- 🟢 Review the diff —
codex reviewwith a pass/fail gate (recommended) - Challenge the diff — adversarial pass that tries to break it
- Something else — the user supplies a prompt (consult mode)
- 🟢 Review the diff —
- If no diff, check for plan files scoped to the current project:
ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1If no project-scoped match, fall back to:ls -t ~/.claude/plans/*.md 2>/dev/null | head -1but warn the user: "Note: this plan may be from a different project." - If a plan file exists, offer to review it
- Otherwise, ask: "What would you like to ask Codex?"
- Check for a diff (with fallback if origin isn't available):
/codex <anything else>— Consult mode (Step 2C), where the remaining text is the prompt
Step 2A: Review Mode
Run Codex code review against the current branch diff.
- Create temp files for output capture:
TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)
- Run the review (5-minute timeout). Commits on the branch:
--base <base>. Uncommitted work (staged, unstaged and untracked):--uncommitted. One commit:--commit <sha>. The review model is the deep/verify tier,gpt-6-astra:
codex review -c 'sandbox_mode="read-only"' -c 'review_model="gpt-6-astra"' -c 'web_search="cached"' --base <base> 2>"$TMPERR"
codex review -c 'sandbox_mode="read-only"' -c 'review_model="gpt-6-astra"' -c 'web_search="cached"' --uncommitted 2>"$TMPERR"
Use timeout: 300000 on the Bash call. If the user provided custom instructions
(e.g., /codex review focus on security), pass them as the prompt argument:
codex review -c 'sandbox_mode="read-only"' -c 'review_model="gpt-6-astra"' -c 'web_search="cached"' "focus on security" 2>"$TMPERR" # prompt-only: a diff selector cannot combine with instructions
For a JSONL event stream or a saved final message, use the headless form:
codex exec review --base <base> -m gpt-6-astra --json --output-last-message <file>.
- Capture the output. Then parse cost from stderr:
grep "tokens used" "$TMPERR" 2>/dev/null || echo "tokens: unknown"
Determine gate verdict by checking the review output for critical findings. If the output contains
[P1]— the gate is FAIL. If no[P1]markers are found (only[P2]or no findings) — the gate is PASS.Present the output:
CODEX SAYS (code review):
════════════════════════════════════════════════════════════
<full codex output, verbatim — do not truncate or summarize>
════════════════════════════════════════════════════════════
GATE: PASS Tokens: 14,331 | Est. cost: ~\$0.12
or
GATE: FAIL (N critical findings)
- Cross-model comparison: If
/review(Claude's own review) was already run earlier in this conversation, compare the two sets of findings:
CROSS-MODEL ANALYSIS:
Both found: [findings that overlap between Claude and Codex]
Only Codex found: [findings unique to Codex]
Only Claude found: [findings unique to Claude's /review]
Agreement rate: X% (N/M total unique findings overlap)
- Persist the review result:
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-review","timestamp":"TIMESTAMP","status":"STATUS","gate":"GATE","findings":N,"findings_fixed":N}'
Substitute: TIMESTAMP (ISO 8601), STATUS ("clean" if PASS, "issues_found" if FAIL), GATE ("pass" or "fail"), findings (count of [P1] + [P2] markers), findings_fixed (count of findings that were addressed/fixed before shipping).
- Retain the temporary stderr file until the review is complete. Remove it only when the active repository policy and user authorization permit deletion; otherwise leave it for normal temporary-file lifecycle management.
Plan File Review Report
After displaying the Review Readiness Dashboard in conversation output, also update the plan file itself so review status is visible to anyone reading the plan.
Detect the plan file
- Check if there is an active plan file in this conversation (the host provides plan file paths in system messages — look for plan file references in the conversation context).
- If not found, skip this section silently — not every review runs in plan mode.
Generate the report
Read the review log output you already have from the Review Readiness Dashboard step above. Parse each JSONL entry. Each skill logs different fields:
- plan-ceo-review: `status`, `unresolved`, `critical_gaps`, `mode`, `scope_proposed`, `scope_accepted`, `scope_deferred`, `commit` → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred" → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
- plan-eng-review: `status`, `unresolved`, `critical_gaps`, `issues_found`, `mode`, `commit` → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
- plan-design-review: `status`, `initial_score`, `overall_score`, `unresolved`, `decisions_made`, `commit` → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
- codex-review: `status`, `gate`, `findings`, `findings_fixed` → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
All fields needed for the Findings column are now present in the JSONL entries. For the review you just completed, you may use richer details from your own Completion Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
Produce this markdown table:
```markdown
GSTACK REVIEW REPORT
| Review | Trigger | Why | Runs | Status | Findings |
|---|---|---|---|---|---|
| CEO Review | `/plan-ceo-review` | Scope & strategy | {runs} | {status} | {findings} |
| Codex Review | `/codex review` | Independent 2nd opinion | {runs} | {status} | {findings} |
| Eng Review | `/plan-eng-review` | Architecture & tests (required) | {runs} | {status} | {findings} |
| Design Review | `/plan-design-review` | UI/UX gaps | {runs} | {status} | {findings} |
| ``` |
Below the table, add these lines (omit any that are empty/not applicable):
- CODEX: (only if codex-review ran) — one-line summary of codex fixes
- CROSS-MODEL: (only if both Claude and Codex reviews exist) — overlap analysis
- UNRESOLVED: total unresolved decisions across all reviews
- VERDICT: list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement"). If Eng Review is not CLEAR and not skipped globally, append "eng review required".
Write to the plan file
Update a plan file only when the user requested that update and the active platform permits that exact write. A skill cannot grant a plan-mode exception. Otherwise return the review in the response and skip this section.
- Search the plan file for a `## GSTACK REVIEW REPORT` section anywhere in the file (not just at the end — content may have been added after it).
- If found, replace it entirely using the Edit tool. Match from `## GSTACK REVIEW REPORT` through either the next `## ` heading or end of file, whichever comes first. This ensures content added after the report section is preserved, not eaten. If the Edit fails (e.g., concurrent edit changed the content), re-read the plan file and retry once.
- If no such section exists, append it to the end of the plan file.
- Always place it as the very last section in the plan file. If it was found mid-file, move it: delete the old location and append at the end.
Step 2B: Challenge (Adversarial) Mode
Codex tries to break your code — finding edge cases, race conditions, security holes, and failure modes that a normal review would miss.
- Construct the adversarial prompt. If the user provided a focus area
(e.g.,
/codex challenge security), include it:
Default prompt (no focus):
"Review the changes on this branch against the base branch. Run git diff origin/<base> to see the diff. Your job is to find ways this code will fail in production. Think like an attacker and a chaos engineer. Find edge cases, race conditions, security holes, resource leaks, failure modes, and silent data corruption paths. Be adversarial. Be thorough. No compliments — just the problems."
With focus (e.g., "security"):
"Review the changes on this branch against the base branch. Run git diff origin/<base> to see the diff. Focus specifically on SECURITY. Your job is to find every way an attacker could exploit this code. Think about injection vectors, auth bypasses, privilege escalation, data exposure, and timing attacks. Be adversarial."
- Run codex exec with JSONL output to capture reasoning traces and tool calls (5-minute timeout):
codex exec "<prompt>" -s read-only -c 'web_search="cached"' --json 2>/dev/null | python3 -c "
import sys, json
for line in sys.stdin:
line = line.strip()
if not line: continue
try:
obj = json.loads(line)
t = obj.get('type','')
if t == 'item.completed' and 'item' in obj:
item = obj['item']
itype = item.get('type','')
text = item.get('text','')
if itype == 'reasoning' and text:
print(f'[codex thinking] {text}')
print()
elif itype == 'agent_message' and text:
print(text)
elif itype == 'command_execution':
cmd = item.get('command','')
if cmd: print(f'[codex ran] {cmd}')
elif t == 'turn.completed':
usage = obj.get('usage',{})
tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
if tokens: print(f'\ntokens used: {tokens}')
except: pass
"
This parses codex's JSONL events to extract reasoning traces, tool calls, and the final
response. The [codex thinking] lines show what codex reasoned through before its answer.
- Present the full streamed output:
CODEX SAYS (adversarial challenge):
════════════════════════════════════════════════════════════
<full output from above, verbatim>
════════════════════════════════════════════════════════════
Tokens: N | Est. cost: ~$X.XX
Step 2C: Consult Mode
Ask Codex anything about the codebase. Supports session continuity for follow-ups.
- Check for existing session:
cat .context/codex-session-id 2>/dev/null || echo "NO_SESSION"
If a session file exists (not NO_SESSION), ask with AskUserQuestion (header "Codex session"):
- 🟢 Continue the conversation — Codex keeps the prior context (recommended)
- Start a new conversation — fresh session, prior context dropped
- Create temp files:
TMPRESP=$(mktemp /tmp/codex-resp-XXXXXX.txt)
TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)
- Plan review auto-detection: If the user's prompt is about reviewing a plan,
or if plan files exist and the user said
/codexwith no arguments:
ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1
If no project-scoped match, fall back to ls -t ~/.claude/plans/*.md 2>/dev/null | head -1
but warn: "Note: this plan may be from a different project — verify before sending to Codex."
Read the plan file and prepend the persona to the user's prompt:
"You are a brutally honest technical reviewer. Review this plan for: logical gaps and
unstated assumptions, missing error handling or edge cases, overcomplexity (is there a
simpler approach?), feasibility risks (what could go wrong?), and missing dependencies
or sequencing issues. Be direct. Be terse. No compliments. Just the problems.
THE PLAN: "
- Run codex exec with JSONL output to capture reasoning traces (5-minute timeout):
For a new session:
codex exec "<prompt>" -s read-only -c 'web_search="cached"' --json 2>"$TMPERR" | python3 -c "
import sys, json
for line in sys.stdin:
line = line.strip()
if not line: continue
try:
obj = json.loads(line)
t = obj.get('type','')
if t == 'thread.started':
tid = obj.get('thread_id','')
if tid: print(f'SESSION_ID:{tid}')
elif t == 'item.completed' and 'item' in obj:
item = obj['item']
itype = item.get('type','')
text = item.get('text','')
if itype == 'reasoning' and text:
print(f'[codex thinking] {text}')
print()
elif itype == 'agent_message' and text:
print(text)
elif itype == 'command_execution':
cmd = item.get('command','')
if cmd: print(f'[codex ran] {cmd}')
elif t == 'turn.completed':
usage = obj.get('usage',{})
tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
if tokens: print(f'\ntokens used: {tokens}')
except: pass
"
For a resumed session (user chose "Continue"):
codex exec resume <session-id> -c 'sandbox_mode="read-only"' -c 'web_search="cached"' --json "<prompt>" 2>"$TMPERR" | python3 -c "
<same python streaming parser as above>
"
- Capture session ID from the streamed output. The parser prints
SESSION_ID:<id>from thethread.startedevent. Save it for follow-ups:
mkdir -p .context
Save the session ID printed by the parser (the line starting with SESSION_ID:)
to .context/codex-session-id.
- Present the full streamed output:
CODEX SAYS (consult):
════════════════════════════════════════════════════════════
<full output, verbatim — includes [codex thinking] traces>
════════════════════════════════════════════════════════════
Tokens: N | Est. cost: ~$X.XX
Session saved — run /codex again to continue this conversation.
- After presenting, note any points where Codex's analysis differs from your own understanding. If there is a disagreement, flag it: "Note: Claude Code disagrees on X because Y."
Model & Reasoning
Model: Inherit the configured Codex model unless the user picks one; preserve the authenticated OAuth path. Codex roles (docs/reference/platform-facts-2026-10.md §3.1):
| Role | Model id |
|---|---|
| Deep reasoning, review, verification | gpt-6-astra |
| Default executor (Codex catalog default) | gpt-6.1-sol |
| Bounded implementation | gpt-6-sol |
| Mechanical, high-volume | gpt-6-luna |
Pass an override with -m <id> on codex exec / codex exec review, or -c 'review_model="<id>"' on codex review.
Reasoning effort: Inherit the configured model_reasoning_effort for bounded reviews. Override only when the task or user justifies it, with -c 'model_reasoning_effort="xhigh"'; supported levels are low, medium, high, xhigh, max and ultra (model dependent; gpt-6-luna stops at max). Do not force maximum effort for every mode.
Web search: Examples select cached search with -c 'web_search="cached"'. For explicitly requested live research, select -c 'web_search="live"' instead. Honor a user request to avoid web access. Do not use the deprecated web_search_cached feature flag or claim unverified pricing.
For example, /codex review -m gpt-6-astra or /codex challenge -m gpt-6-sol selects a task-appropriate model. Check codex <subcommand> --help if option placement is uncertain.
Cost Estimation
Parse token count from stderr. Codex prints tokens used\nN to stderr.
Display as: Tokens: N
If token count is not available, display: Tokens: unknown
Error Handling
- Binary not found: Detected in Step 0. Stop with install instructions.
- Auth error: Codex prints an auth error to stderr. Surface the error:
"Codex authentication failed. Run
codex loginin your terminal to authenticate via ChatGPT." - Timeout: If the Bash call times out (5 min), tell the user: "Codex timed out after 5 minutes. The diff may be too large or the API may be slow. Try again or use a smaller scope."
- Empty response: If
$TMPRESPis empty or doesn't exist, tell the user: "Codex returned no response. Check stderr for errors." - Session resume failure: If resume fails, delete the session file and start fresh.
Important Rules
- Never modify files. This skill is read-only. Codex runs in read-only sandbox mode.
- Present output verbatim. Do not truncate, summarize, or editorialize Codex's output before showing it. Show it in full inside the CODEX SAYS block.
- Add synthesis after, not instead of. Any Claude commentary comes after the full output.
- 5-minute timeout on all Bash calls to codex (
timeout: 300000). - No double-reviewing. If the user already ran
/review, Codex provides a second independent opinion. Do not re-run Claude Code's own review.
