---

Codex Manager Skill

This skill enables Claude Code to orchestrate implementation tasks through Codex CLI. An architect (Gemini or similar) provides the plan (implementation_plan.md). Claude Code ensures faithful, high-quality execution by delegating tasks to Codex and validating results.

Architecture

Plan (implementation_plan.md) -> Claude Code (Orchestrator) -> Codex CLI (Implementer)

Core Principles

<orchestration_rules>

1. Delegate all implementation - Codex writes the code; Claude validates and orchestrates.
2. Follow the plan exactly - Execute tasks as defined in implementation_plan.md.
3. One task at a time - Default to incremental execution unless explicitly batching.
4. Reference the plan - Every Codex instruction must reference the plan file.
5. Validate before marking complete - Read and verify output meets requirements.
6. Quality over speed - Reject implementations that are functional but poorly structured.
7. Auto-continue - Proceed to the next task after successful validation. </orchestration_rules>

Before Starting

Validate Environment

Before delegating any task, verify the environment:

# Check Codex CLI is available
./skills/codex-manager/scripts/codex-task.sh --check

# Verify plan file exists and is valid
./skills/codex-manager/scripts/plan-utils.sh validate implementation_plan.md

Understand the Plan

Read the plan to identify current state and next task:

Read implementation_plan.md

Look for the first unchecked item (- [ ]).

Workflow

Phase 1: Task Selection

Identify the next incomplete task from the plan. Read relevant context files before delegating.

Phase 2: Delegation

Use the helper script with a clear, minimal prompt. Codex performs best with concise instructions.

<codex_prompting_principles>

• Keep prompts minimal and task-focused
• Avoid verbose explanations or role-play
• Give clear success criteria
• Let Codex use its tools without micromanaging
• Include file paths and specific requirements </codex_prompting_principles>

Template:

./skills/codex-manager/scripts/codex-task.sh "TASK: [Task name from plan]

Requirements:
- [Specific requirement 1]
- [Specific requirement 2]

Files: [relevant file paths]

Apply changes now."

Phase 3: Validation

After Codex completes, read the modified files and verify:

<validation_checklist>

1. Correctness - Does it implement what the plan specified?
2. Completeness - Are all requirements addressed? No TODOs left?
3. Quality - Is it clean, typed, and follows project conventions?
4. Safety - No hardcoded secrets, proper error handling, input validation? </validation_checklist>

If validation fails:

./skills/codex-manager/scripts/codex-task.sh "FIX: [Issue description]

Current: [What was implemented]
Required: [What the plan specifies]

Correct this now."

Phase 4: Update Plan

Only after successful validation, mark the task complete:

./skills/codex-manager/scripts/plan-utils.sh complete "Task Name" implementation_plan.md

Phase 5: Continue

Return to Phase 1 for the next task. Continue until all tasks are marked [x].

Command Reference

Standard Implementation

./skills/codex-manager/scripts/codex-task.sh "TASK: [Feature name]

Requirements:
- [Requirement from plan]

Files: src/path/to/file.ts

Apply changes now."

Request Correction

./skills/codex-manager/scripts/codex-task.sh "FIX: [Issue]

Expected: [What plan specifies]
Actual: [What was implemented]

Correct this now."

Quality Improvement

./skills/codex-manager/scripts/codex-task.sh "IMPROVE: [File path]

Issues:
- [Quality issue 1]
- [Quality issue 2]

Refactor to address these. Do not change logic."

Error Handling

Codex Not Available

If codex command is not found, the script will exit with an error. Ensure Codex CLI is installed and in PATH.

Plan File Missing

If implementation_plan.md is missing, use the gemini-manager skill or create the plan manually.

Task Failure

If a task fails repeatedly:

1. Break it into smaller subtasks
2. Provide more specific context
3. Check for environmental issues (missing dependencies, permissions)

Role Separation

Claude Code (Orchestrator)	Codex CLI (Implementer)
Reads and interprets plan	Writes code
Validates output quality	Implements logic
Manages task progression	Follows instructions
Updates plan status	Uses tools autonomously
Ensures consistency	Focuses on current task

Best Practices

<claude_orchestration_tips>

• Read files before delegating tasks that modify them
• Use structured formats (JSON) for tracking complex state
• Provide specific file paths and line numbers when requesting fixes
• Keep validation objective - does it match the plan?
• Use git to track progress across sessions </claude_orchestration_tips>

<codex_delegation_tips>

• Minimal prompts work better than verbose ones
• One clear task per delegation
• Include success criteria
• Trust Codex to use its tools appropriately
• Avoid requesting explanations unless needed </codex_delegation_tips>

---