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

Be explicit in TASK.md - Include all context, don't assume
Specify output structure - Tell Codex exactly what OUTPUT.md should contain
List input files - Explicitly name files Codex should read
Define constraints - Prevent unwanted modifications
Request thread ID - Include in deliverables for session resume
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):

dev_invoke_gemini-cli -- Alternative: Gemini CLI for large context analysis
dev_invoke_kimi-cli -- Alternative: Kimi CLI for test generation
qa_review_triple-model -- Uses this skill as one of three reviewers

dev_invoke_codex-cli

Invoking Codex CLI

Pattern: Markdown File Handoff