dev-invoke-codex-cli

name	dev_invoke_codex-cli
description	Delegate code tasks to OpenAI Codex CLI using markdown file handoff pattern. Write instructions to TASK.md, Codex reads and executes, outputs to OUTPUT.md. Use for implementation, refactoring, code generation requiring extended thinking. Triggers: codex, codex cli, delegate to codex, codex subagent, implementation task, refactoring task, code generation, gpt-5.2-codex, openai codex, extended thinking, multi-file changes, complex implementation Prerequisites: Codex CLI authenticated (codex login or OPENAI_API_KEY) Model: gpt-5.2-codex (default, supports xhigh reasoning effort)
shared_corpus	false
harness_scope	claude_only

Invoking Codex CLI

Claude-only orchestration skill. This skill exists to let Claude delegate out to Codex CLI. It is excluded from any future shared multi-harness skill corpus.

Delegate tasks to Codex CLI using markdown files for instruction input and deliverable output. Write instructions to TASK.md, invoke Codex, then read OUTPUT.md for results.

Pattern: Markdown File Handoff

Claude Code                         Codex CLI
    |                                   |
    +-- Write TASK.md ------------------+
    |   (instructions + context)        |
    |                                   |
    +-- Execute: codex e "Read TASK.md, |
    |   follow instructions, write      |
    |   deliverables to OUTPUT.md"      |
    |                                   |
    |                                   +-- Reads TASK.md
    |                                   +-- Executes task
    |                                   +-- Writes OUTPUT.md
    |                                   |
    +-- Read OUTPUT.md <----------------+
    |   (deliverables + results)        |
    v                                   v

Benefits:

• Eliminates shell escaping issues (quotes, special characters, code blocks)
• Keeps context structured in reviewable files
• Enforces explicit deliverable format
• Supports session resume via thread ID

When to Use

Use this skill for:

• Complex implementation requiring multi-file changes
• Refactoring with dependency tracking
• Code generation with detailed specifications
• Tasks requiring extended thinking (20-30 minutes)

Model Selection

Model: Always use gpt-5.2-codex (latest model).

Reasoning Effort: Adjust based on task complexity.

Reasoning Effort	Use Case	Speed
xhigh	Default. Complex tasks, deep analysis	Slowest, best quality
high	Medium complexity, good reasoning	Balanced
medium	Lighter tasks, adequate reasoning	Faster
low	Simple tasks, quick response	Fastest

Recommendation: Use default xhigh reasoning for most tasks. Lower reasoning effort for simpler tasks instead of switching to older models.

Invocation

Standard Pattern (Recommended)

codex e "Read TASK.md in the current directory. Follow the instructions exactly. Write all deliverables to OUTPUT.md." \
  -C "/path/to/project" \
  --full-auto \
  --skip-git-repo-check

With Lower Reasoning Effort

# For simpler tasks, reduce reasoning effort (not model)
codex e "Read TASK.md, follow instructions, write results to OUTPUT.md" \
  -C "/path/to/project" \
  -c model_reasoning_effort=medium \
  --full-auto \
  --skip-git-repo-check

Resume Session

codex e resume <thread_id> "Read TASK.md for updated instructions, append results to OUTPUT.md"

Core Flags Reference

Flag	Purpose
-C /path	Working directory (where TASK.md lives)
--full-auto	Sandboxed auto-execution (workspace-write + no approvals)
--skip-git-repo-check	Work in any directory
-c model_reasoning_effort=<level>	Reasoning: xhigh (default), high, medium, low

Model: Always gpt-5.2-codex (latest). Adjust reasoning effort instead of changing models.

Task File Template (TASK.md)

# Task: [Brief Title]

## Objective
[Clear statement of what needs to be accomplished]

## Context
[Relevant background, constraints, requirements]

## Input Files
- `src/api/users.ts` - User service to modify
- `src/types/user.ts` - Type definitions

## Instructions
1. [First step]
2. [Second step]
3. [Third step]

## Deliverables
Write to OUTPUT.md:
- Summary of changes made
- List of files modified
- Any issues encountered
- Recommendations for follow-up
- Thread ID for session resume

## Constraints
- Do not modify files outside src/api/
- Maintain backward compatibility
- Follow existing code style

Output File Template (OUTPUT.md)

Instruct Codex to produce:

# Deliverables: [Task Title]

## Summary
[Brief description of what was done]

## Changes Made

### Files Modified
| File | Change |
|------|--------|
| `src/api/users.ts` | Added validation logic |

### Code Changes
[Key code snippets if relevant]

## Issues Encountered
- [Any problems and how resolved]

## Recommendations
- [Suggested follow-up actions]

## Session
Thread ID: `<thread_id>` (for resume)

Workflow Example (ras-commander)

1. Write TASK.md

# Task: Add Validation to Precipitation API

## Objective
Add depth conservation validation to precipitation methods.

## Context
The precipitation methods in ras_commander/precip/ need validation
to ensure depth conservation at 10^-6 precision.

## Input Files
- `ras_commander/precip/Atlas14Storm.py`
- `ras_commander/precip/StormGenerator.py`

## Instructions
1. Add depth conservation check after hyetograph generation
2. Raise ValidationError if conservation fails
3. Log successful validation with actual precision achieved

## Deliverables
Write to OUTPUT.md:
- Summary of validation logic added
- Files modified with line references
- Test cases to validate

## Constraints
- Use existing ValidationSeverity pattern
- Maintain backward compatibility

2. Execute Codex

codex e "Read TASK.md, follow the instructions, write deliverables to OUTPUT.md" \
  -C "C:/GH/ras-commander" \
  --full-auto \
  --skip-git-repo-check

3. Read OUTPUT.md

Parse the results, verify changes, and continue the workflow.

Environment Variables

CODEX_API_KEY=sk-xxx      # Required (or use codex login)
OPENAI_API_KEY=sk-xxx     # Alternative

Session Management

• Thread ID appears in Codex console output at session start
• Request thread ID in OUTPUT.md deliverables section
• Resume with: codex e resume <thread_id> "follow-up instruction"

Tips

1. Be explicit in TASK.md - Include all context, don't assume
2. Specify output structure - Tell Codex exactly what OUTPUT.md should contain
3. List input files - Explicitly name files Codex should read
4. Define constraints - Prevent unwanted modifications
5. Request thread ID - Include in deliverables for session resume
6. Use default model - gpt-5.2-codex is best for complex reasoning tasks

When to Escalate

Use Codex for:

• Implementation requiring extended thinking
• Multi-file refactoring
• Complex code generation
• Architecture planning

Use specialized ras-commander agents for:

• HDF analysis -> hdf-analyst
• Geometry parsing -> geometry-parser
• USGS integration -> usgs-integrator

Cross-References

Agents (delegate when needed):

• code-oracle-codex -- Delegate for deep code analysis with Codex

Skills (related workflows):

• qa_review_triple-model -- Legacy provider-mixed workflow; explicit user request only