--- name: codex-cli description: Run OpenAI Codex CLI for spec gate reviews, code reviews, and general AI-assisted tasks. Use when you need Codex to review specs, analyze code, or provide a second opinion. Triggers on "codex review", "run codex", "codex spec gate", "codex cli". --- # Codex CLI Integration Run OpenAI Codex CLI from within Claude Code sessions. ## Usage ```bash \/codex-cli [options] ``` ### Actions | Action | Description | |--------|-------------| | `spec-gate ` | Run spec gate review on a ClickUp task | | `code-review` | Run code review on current changes | | `exec ""` | Run arbitrary Codex prompt | | `test` | Test that Codex CLI is working | ### Examples ```bash # Spec gate review \/codex-cli spec-gate 86aeue99t # Code review on staged changes \/codex-cli code-review # Custom prompt \/codex-cli exec "Analyze this architecture decision..." # Test connectivity \/codex-cli test ``` ## Requirements 1. **Must run from a git repository directory** - Codex requires a trusted git repo 2. **PowerShell required** - Bash doesn't capture Codex output properly on Windows 3. **OpenAI API key** - Must be configured in Codex CLI (`codex login`) ## How It Works Codex CLI runs as a separate process and returns its output. The key command pattern: ```powershell cd ''; codex exec --full-auto '' 2>&1 ``` ### Output Format Codex returns structured output: ``` OpenAI Codex v0.89.0 (research preview) -------- workdir: model: gpt-5.2-codex ... -------- user ... codex tokens used ``` The skill extracts just the `codex` response section. ## Spec Gate Review When running a spec gate review: 1. Reads the spec from ClickUp task or local file 2. Sends to Codex with spec review criteria 3. Returns APPROVED or NEEDS REVISION with reasons ### Spec Gate Prompt Template ``` Review this spec against these criteria: 1. Given\/When\/Then ACs - Are all ACs in proper testable format? 2. Edge Cases - Are null\/undefined\/missing states covered? 3. File Mapping - Is every AC mapped to specific files? 4. Test Plan - Does each AC have a corresponding test? 5. Rollback Plan - Is it specific with branch names? 6. Observability - Sentry CAPTURE and NEVER CAPTURE lists? 7. Idempotency - Is retry\/overwrite behavior defined? Reply with: - APPROVED - if spec meets all criteria - NEEDS REVISION - with specific issues to fix SPEC: ``` ## Code Review When running a code review: 1. Gets the diff of staged or committed changes 2. Sends to Codex with review criteria 3. Returns findings organized by severity ## Integration with CazVid Workflow This skill is called by: - `\/cazvid-run` - During Phase 2 (Spec Gate) and Phase 5 (Code Review) - `\/cazvid-spec-gate` - For spec validation - `\/cazvid-codex-review` - For implementation review ## Troubleshooting ### "Not inside a trusted directory" Run from a git repository directory (worktree or repo). ### No output returned Use PowerShell wrapper - bash doesn't capture Codex stdout properly on Windows. ### Timeout Codex can take 30-60 seconds for complex prompts. Default timeout is 120 seconds. ### Authentication error Run `codex login` to authenticate with OpenAI. ## Included Scripts (this pack) - `scripts\/codex-cli.ps1` - main router for actions (spec-gate, code-review, exec, test) - `scripts\/spec-gate.ps1` - spec gate runner (provided) Typical usage from a repo worktree: ```powershell powershell -ExecutionPolicy Bypass -File .claude\/skills\/codex-cli\/scripts\/codex-cli.ps1 spec-gate -WorkDir (Get-Location) -SpecFile .\SPEC.md ``` In Claude Code, prefer calling the skill directly: - `\/codex-cli spec-gate ` - `\/codex-cli code-review`