Codex Consult

---
name: codex-consult
description: Get a second opinion from OpenAI Codex on documents, specs, or plans. Use for cross-AI consultation on any content, not just code diffs.
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

```bash
# 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

```bash
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

```bash
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:

```bash
# 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):

```bash
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`)

```bash
# 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:

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

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

```bash
UPSTREAM_CONTENT=$(cat "$UPSTREAM_FILE")
```

## Step 3: Generate Consultation Prompt

See [PROMPT_TEMPLATE.md](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](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:

```bash
# 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](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:

```json
{
  "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
```