AgentSkillsCN

Skill

技能

SKILL.md
--- frontmatter
# 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:

```bash
# 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:

```bash
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:**
```bash
./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:**
```bash
./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:

```bash
./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
```bash
./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
```bash
./skills/codex-manager/scripts/codex-task.sh "FIX: [Issue]

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

Correct this now."
```

### Quality Improvement
```bash
./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>