codex-consult

name	codex-consult
description	Use when seeking a second opinion from OpenAI Codex on documents, specs, plans, or other non-code-diff content.
argument-hint	[FILE] [question/focus] [--upstream FILE] [--research TOPICS] [--model MODEL]
allowed-tools	Bash, Read, Glob, Grep

Codex Consult

Invoke OpenAI's Codex CLI to review a document or plan, with instructions to research relevant topics before providing feedback.

When to Use

• You want a second opinion on a generated spec, plan, or document
• Cross-model consultation on non-code content (specs, plans, configs)
• Other skills can invoke this automatically for document review
• You want Codex to research current documentation before evaluating content

For code diff reviews, use /codex-review instead.

Prerequisites

• Codex CLI installed (codex --version works)
• Valid OpenAI authentication (codex login completed)

Arguments

Argument	Example	Description
FILE	PRODUCT_SPEC.md	Document to consult on (first positional arg)
focus	completeness	Focus consultation on specific area
--upstream FILE	--upstream PRODUCT_SPEC.md	Reference document to check alignment against
--research TOPICS	--research "Supabase, NextAuth"	Explicit technologies for Codex to research
--model MODEL	--model gpt-5.2	Use specific model (overrides config)

Workflow

Copy this checklist and track progress:

Codex Consult Progress:
- [ ] Step 1: Verify Codex CLI available
- [ ] Step 2: Read document content
- [ ] Step 3: Generate consultation prompt
- [ ] Step 4: Invoke Codex
- [ ] Step 5: Present results

Step 1: Verify Codex CLI

Check if Running Inside Codex

# Codex sets CODEX_SANDBOX when running
if [ -n "$CODEX_SANDBOX" ]; then
  echo "RUNNING_IN_CODEX"
fi

If running inside Codex CLI:

CODEX CONSULT: SKIPPED
======================
Reason: Already running inside Codex CLI.

Cross-model consultation requires a different model.
Continuing without cross-model consultation.

Return early. Do NOT block the parent workflow.

Check Codex CLI Installed

codex --version

If not installed:

Codex CLI is not installed or not in PATH.

Install: https://github.com/openai/codex
Then run: codex login

Check Authentication

codex login status

If not authenticated:

Codex authentication failed. Run:
  codex login

If ANY pre-flight check fails: Report the specific failure and STOP. Do NOT attempt alternative commands or workarounds. Return status: skipped.

Read Configuration

Read .claude/settings.local.json for settings:

# Read model from config (codexConsult with fallback to codexReview)
CONSULT_MODEL=$(jq -r '.codexConsult.researchModel // .codexReview.codeModel // "gpt-5.2"' .claude/settings.local.json 2>/dev/null || echo "gpt-5.2")
TIMEOUT_MINS=$(jq -r '.codexConsult.consultTimeoutMinutes // 20' .claude/settings.local.json 2>/dev/null || echo "20")

Check enabled status (fallback chain):

ENABLED=$(jq -r '.codexConsult.enabled // .codexReview.enabled // true' .claude/settings.local.json 2>/dev/null || echo "true")

If enabled is explicitly false, skip with message.

Select Model

Priority order: --model flag > config > default (gpt-5.2)

# 1. Explicit --model flag always wins
if [ -n "$EXPLICIT_MODEL" ]; then
  CODEX_MODEL="$EXPLICIT_MODEL"
# 2. Use configured model
else
  CODEX_MODEL="$CONSULT_MODEL"
fi

Step 2: Read Document Content

Read the target file specified as the first positional argument:

# Read the document under review
DOCUMENT_CONTENT=$(cat "$TARGET_FILE")

If --upstream is provided, also read the reference document:

UPSTREAM_CONTENT=$(cat "$UPSTREAM_FILE")

Step 3: Generate Consultation Prompt

See PROMPT_TEMPLATE.md for the full prompt structure.

Key sections:

1. Pre-Consultation Research — Technologies/topics Codex should research
2. Document Under Review — Full content of the target file
3. Reference Document (if --upstream provided) — Requirements to check against
4. Focus Area (if focus provided) — Specific area to concentrate on
5. Evaluation Criteria — Completeness, accuracy, feasibility, consistency

Step 4: Invoke Codex

See CODEX_INVOCATION.md for detailed command building.

IMPORTANT — Execution Rules:

• Execute synchronously. NEVER use run_in_background for Codex invocations.
• If this command fails, report the exit code and return status: error. Do NOT retry with different flags or subcommands.
• Use the Bash tool's timeout parameter set to TIMEOUT_MINS * 60 * 1000 (ms) instead of the shell timeout command or run_in_background.

Safety Guard (prevent accidental commits)

Before invoking Codex, protect the working tree:

# Record current HEAD so we can detect if Codex makes commits
HEAD_BEFORE=$(git rev-parse HEAD)

Note: Do NOT stash uncommitted changes — stash/pop triggers file-system events that confuse IDE watchers, hot-reload, and other processes. The HEAD check alone is sufficient.

Invoke Codex

See CODEX_INVOCATION.md for the full command, effort handling, and safety checks. The invocation file is the single source of truth — do not duplicate the command here.

Important: Do NOT use 2>&1 — Codex streams progress to stderr and final output to stdout. Merging them corrupts the parseable response.

Step 5: Present Results

Parse and present the Codex output.

Output Format (User-Facing)

CODEX CONSULTATION COMPLETE
============================
Document: PRODUCT_SPEC.md
Consulted by: Codex ({model})
Status: PASS WITH NOTES

Issues: None

Suggestions:
1. [Section: User Stories] Consider adding edge case for guest users
   -> Suggestion: Add a user story for unauthenticated access

2. [Section: Data Model] Missing field for soft-delete tracking
   -> Suggestion: Add deleted_at timestamp field

Positive Findings:
- Comprehensive coverage of core user workflows
- Clear acceptance criteria for each feature

{If --upstream provided}
Alignment Check: All 5 requirements from PRODUCT_SPEC.md addressed
{/If}

Output Format (Programmatic — for calling skills)

When invoked by another skill (/create-pr, /codex-implement, /feature-spec, /product-spec, /technical-spec, /generate-plan, or any other caller), return structured data:

{
  "status": "<Status>",
  "issues": [],
  "suggestions": [],
  "positive_findings": [],
  "alignment_check": {
    "checked": true,
    "all_addressed": true,
    "missing_items": []
  }
}

Status enum — exactly one of:

Value	Meaning
pass	No issues found. Document is ready.
pass_with_notes	No blocking issues, but suggestions were generated.
needs_attention	One or more issues require human review before proceeding.
error	Codex invocation failed (timeout, crash, malformed output).
skipped	Pre-flight check failed (not installed, not authenticated, disabled, or running inside Codex).

Field descriptions:

Field	Type	Description
status	Status	Overall consultation result (see enum above).
issues	string[]	Actionable problems found in the document. Empty array when none.
suggestions	string[]	Non-blocking improvement ideas. Empty array when none.
positive_findings	string[]	Things the document does well. Empty array when none.
alignment_check	object | null	Present only when --upstream was provided; null otherwise.
alignment_check.checked	boolean	Always true when the object is present.
alignment_check.all_addressed	boolean	true if every upstream requirement is covered.
alignment_check.missing_items	string[]	Upstream requirements not found in the target document.

## Error Handling

| Failure | Action |
|---------|--------|
| Codex CLI not found | Report and stop |
| Authentication failed | Suggest `codex login` |
| Target file not found | Report missing file |
| Codex times out | Return partial output if available |
| Output is malformed | Attempt best-effort parsing |

## Configuration

Read from `.claude/settings.local.json`:

```json
{
  "codexConsult": {
    "enabled": true,
    "researchModel": "gpt-5.2",
    "consultTimeoutMinutes": 20
  }
}

Setting	Default	Fallback	Description
enabled	true	codexReview.enabled	Set to false to disable consultation
researchModel	"gpt-5.2"	codexReview.codeModel	Model for consultation tasks
consultTimeoutMinutes	20	—	Max time for consultation invocations

Existing codexReview.codeModel config continues to work via fallback.

For CI/headless environments: Set CODEX_API_KEY environment variable for authentication without interactive login.

Examples

Review a product spec:

/codex-consult PRODUCT_SPEC.md

Check alignment with upstream:

/codex-consult --upstream PRODUCT_SPEC.md TECHNICAL_SPEC.md

Focus on completeness:

/codex-consult completeness --research "user stories, acceptance criteria" FEATURE_SPEC.md

Specific model:

/codex-consult --model gpt-5.2 EXECUTION_PLAN.md