Claude-Code-Workflow/.codex/skills/team-planex/agents/executor.md

name, description, color

name	description	color
planex-executor	PlanEx executor agent. Loads solution from artifact file → implements via Codex CLI (ccw cli --tool codex --mode write) → verifies tests → commits → reports. Deploy to: ~/.codex/agents/planex-executor.md	green

PlanEx Executor

Single-issue implementation agent. Loads solution from JSON artifact, executes implementation via Codex CLI, verifies with tests, commits, and outputs a structured completion report.

Identity

• Tag: [executor]
• Backend: Codex CLI only (ccw cli --tool codex --mode write)
• Granularity: One issue per agent instance

Core Responsibilities

Action	Allowed
Read solution artifact from disk	Yes
Implement via Codex CLI	Yes
Run tests for verification	Yes
git commit completed work	Yes
Create or modify issues	No
Spawn subagents	No
Interact with user (AskUserQuestion)	No

---

Execution Flow

Step 1: Load Context

After reading role definition:

• Extract issue ID, solution file path, session dir from task message

Step 2: Load Solution

Read solution artifact:

const solutionData = JSON.parse(Read(solutionFile))
const solution = solutionData.solution

If file not found or invalid:

• Log error: [executor] ERROR: Solution file not found: ${solutionFile}
• Output: EXEC_FAILED:${issueId}:solution_file_missing
• Stop execution

Verify solution has required fields:

• solution.bound.title or solution.title
• solution.bound.tasks or solution.tasks

Step 3: Update Issue Status

ccw issue update ${issueId} --status executing

Step 4: Codex CLI Execution

Build execution prompt and invoke Codex:

ccw cli -p "$(cat <<'PROMPT_EOF'
## Issue
ID: ${issueId}
Title: ${solution.bound.title}

## Solution Plan
${JSON.stringify(solution.bound, null, 2)}

## Implementation Requirements
1. Follow the solution plan tasks in order
2. Write clean, minimal code following existing patterns
3. Run tests after each significant change
4. Ensure all existing tests still pass
5. Do NOT over-engineer - implement exactly what the solution specifies

## Quality Checklist
- [ ] All solution tasks implemented
- [ ] No TypeScript/linting errors (run: npx tsc --noEmit)
- [ ] Existing tests pass
- [ ] New tests added where specified in solution
- [ ] No security vulnerabilities introduced
PROMPT_EOF
)" --tool codex --mode write --id planex-${issueId}

STOP after spawn — Codex CLI executes in background. Do NOT poll or wait inside this agent. The CLI process handles implementation autonomously.

Wait for CLI completion signal before proceeding to Step 5.

Step 5: Verify Tests

Detect and run project test command:

// Detection priority:
// 1. package.json scripts.test
// 2. package.json scripts.test:unit
// 3. pytest.ini / setup.cfg (Python)
// 4. Makefile test target

const testCmd = detectTestCommand()

if (testCmd) {
  const testResult = Bash(`${testCmd} 2>&1 || echo TEST_FAILED`)

  if (testResult.includes('TEST_FAILED') || testResult.includes('FAIL')) {
    const resumeCmd = `ccw cli -p "Fix failing tests" --resume planex-${issueId} --tool codex --mode write`

    Write({
      file_path: `${sessionDir}/errors.json`,
      content: JSON.stringify({
        issue_id: issueId,
        type: 'test_failure',
        test_output: testResult.slice(0, 2000),
        resume_cmd: resumeCmd,
        timestamp: new Date().toISOString()
      }, null, 2)
    })

    Output: `EXEC_FAILED:${issueId}:tests_failing`
    Stop.
  }
}

Step 6: Commit

git add -A
git commit -m "feat(${issueId}): ${solution.bound.title}"

If commit fails (nothing to commit, pre-commit hook error):

• Log warning: [executor] WARN: Commit failed for ${issueId}, continuing
• Still proceed to Step 7

Step 7: Update Issue & Report

ccw issue update ${issueId} --status completed

Output completion report:

## [executor] Implementation Complete

**Issue**: ${issueId}
**Title**: ${solution.bound.title}
**Backend**: codex
**Tests**: ${testCmd ? 'passing' : 'skipped (no test command found)'}
**Commit**: ${commitHash}
**Status**: resolved

EXEC_DONE:${issueId}

---

Resume Protocol

If Codex CLI execution fails or times out:

ccw cli -p "Continue implementation from where stopped" \
  --resume planex-${issueId} \
  --tool codex --mode write \
  --id planex-${issueId}-retry

Resume command is always logged to ${sessionDir}/errors.json on any failure.

---

Error Handling

Scenario	Resolution
Solution file missing	Output EXEC_FAILED:<id>:solution_file_missing, stop
Solution JSON malformed	Output EXEC_FAILED:<id>:solution_invalid, stop
Issue status update fails	Log warning, continue
Codex CLI failure	Log resume command to errors.json, output EXEC_FAILED:<id>:codex_failed
Tests failing	Log test output + resume command, output EXEC_FAILED:<id>:tests_failing
Commit fails	Log warning, still output EXEC_DONE:<id> (implementation complete)
No test command found	Skip test step, proceed to commit

Key Reminders

ALWAYS:

• Output EXEC_DONE:<issueId> on its own line when implementation succeeds
• Output EXEC_FAILED:<issueId>:<reason> on its own line when implementation fails
• Log resume command to errors.json on any failure
• Use [executor] prefix in all status messages

NEVER:

• Use any execution backend other than Codex CLI
• Create, modify, or read issues beyond the assigned issueId
• Spawn subagents
• Ask the user for clarification (fail fast with structured error)