consult-codex

# Dual-AI Consultation: Codex vs Code-Searcher

You orchestrate consultation between OpenAI's Codex and Claude's code-searcher to provide comprehensive analysis with comparison.

## When to Use This Skill

**High value queries:**
- Complex code analysis requiring multiple perspectives
- Debugging difficult issues
- Architecture/design questions
- Code review requests
- Finding specific implementations across a codebase

**Lower value (single AI may suffice):**
- Simple syntax questions
- Basic file lookups
- Straightforward documentation queries

## Workflow

When the user asks a code question:

### 1. Build Enhanced Prompt

**Problem-restate pre-flight (non-blocking).** Before building the prompt, emit ONE line
restating the code question you are about to dispatch (and, only if genuinely ambiguous, the
alternative reading), then proceed:

> *Reading this as: «one-line restatement» (alt: «other reading», if any) — proceeding to consult; interrupt now to correct the framing.*

Emit-and-proceed — do not ask-and-wait (the orchestrator can't reliably detect its own
misframing). One line, and it guards the whole dispatch against a wrong-framing run.


Wrap the user's question with structured output requirements:

````
[USER_QUESTION]

=== Analysis Guidelines ===

**Structure your response with:**
1. **Summary:** 2-3 sentence overview
2. **Key Findings:** bullet points of discoveries
3. **Evidence:** file paths with line numbers (format: `file:line` or `file:start-end`)
4. **Confidence:** High/Medium/Low with reasoning
5. **Limitations:** what couldn't be determined

**Line Number Requirements:**
- ALWAYS include specific line numbers when referencing code
- Use format: `path/to/file.ext:42` or `path/to/file.ext:42-58`
- For multiple references: list each on a SEPARATE line with its own file path
  (avoid comma-separated multi-citation like `file.ts:45, 67, 98`)
- Include brief code snippets for key findings

**Examples of good citations:**
- "The authentication check at `src/auth/validate.ts:127-134`"
- "Configuration loaded from `config/settings.json:15`"
- "Error handling in `lib/errors.ts:45`, `lib/errors.ts:67-72`, and `lib/errors.ts:98`"

**Citations Index (required):** end your response with a fenced block, one line per
Key Finding (repeat each block entry's `file:line` inline in the finding as usual):
```citations
<finding #> — path/to/file.ext:LINE[-END]
```
````

**Severity / no-manufacture block — ORCHESTRATOR-GATED.** Append the block below to both
agents' prompts **identically** ONLY when the query is a defect hunt / code review (bug,
security audit, "what's wrong with…", "review this"). OMIT it for explanatory / "how does
X work" questions, where "found nothing" is not meaningful. The orchestrator — which knows
the query type — makes this include/omit decision once, BEFORE writing the prompt files;
do not leave it to each agent to self-classify. When included, append exactly these two
bullets (the text only — no leading marker):

    - Tag each finding with a **Severity** — Critical (wrong/broken on expected inputs) · Warning (fails on unusual but valid inputs) · Info (noteworthy, not actionable). Severity is *impact*, orthogonal to the Confidence field (*certainty*).
    - **Finding nothing is a valid, valuable result.** If the code is correct, say so plainly with one verifying note — do NOT manufacture issues to look thorough.

### 2. Invoke Both Analyses in Parallel

**Setup (run first).** `$CLAUDE_PROJECT_DIR` is not always exported into the Bash
tool shell, so resolve it with a `$PWD` fallback and ensure the tmp dir exists.
Substitute the resolved literal path for `$PROJECT_DIR`, and a freshly generated
`RUN_ID` (seconds-resolution + 4-char nonce, e.g. `run-2026-05-25-143052-a7f3`),
into every command below. The `RUN_ID` in temp filenames prevents collisions
between two concurrent invocations sharing `$PROJECT_DIR/tmp`.
```bash
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
# Validate BEFORE creating tmp — `mkdir -p` would otherwise make the check pass even
# for a bad path (it creates the dir, then `[ -d ]` always succeeds).
[ -d "$PROJECT_DIR" ] || { echo "ERROR: PROJECT_DIR '$PROJECT_DIR' is not a directory" >&2; exit 1; }
mkdir -p "$PROJECT_DIR/tmp"

# Pre-flight (fail fast, not after a 10-min hang). jq is a HARD dependency — output
# parsing needs it — so abort now rather than warn-and-continue into opaque failures.
command -v jq >/dev/null 2>&1 || { echo "ERROR: 'jq' not found — required for output parsing; aborting" >&2; exit 1; }
# codex is a soft dependency — the CODEX_BIN resilience block below resolves or SKIPs it.
command -v codex >/dev/null 2>&1 || \
  zsh  -i -c "type codex" >/dev/null 2>&1 || \
  bash -i -c "type codex" >/dev/null 2>&1 || \
  echo "WARNING: 'codex' not found — will attempt nvm resolution below, else SKIP"

# Sweep stale orphans (>60 min) from crashed prior runs (best-effort, age-based —
# can theoretically delete a live run's files if it paused >60 min; acceptable).
find "$PROJECT_DIR/tmp" -maxdepth 1 -name '*-prompt-*.txt'   -mmin +60 -delete 2>/dev/null
find "$PROJECT_DIR/tmp" -maxdepth 1 -name '*-output-*.jsonl' -mmin +60 -delete 2>/dev/null
```

**Codex binary resilience (run once, before dispatch).** An nvm-managed `codex`
can be a symlink whose `@openai/codex` install is broken (deleted vendor binary →
`spawn ... ENOENT`), and a broken version can sit EARLIER on `PATH` than a working
one. `command -v` / `zsh -i` return the broken path, so detect by RUNNING the
binary. If the PATH-resolved codex fails, hunt all nvm node installs for one whose
`--version` succeeds and emit its absolute path. Emit `CODEX_BIN=SKIP` if none work.
```bash
CODEX_BIN=""; INTERACTIVE_SHELL=zsh
# Capture WHICH interactive shell resolves codex (nvm may be in only one of
# ~/.zshrc / ~/.bashrc). The dispatch below uses $INTERACTIVE_SHELL so a
# .bashrc-only setup on macOS still works (prior bug: probe accepted bash,
# dispatch hardcoded zsh).
if   zsh  -i -c 'codex --ve