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

---
name: planex-executor
description: |
  Execution agent for PlanEx pipeline. Loads solutions, routes to
  configurable backends (agent/codex/gemini CLI), runs tests, commits.
  Processes all tasks within a single wave assignment.
color: green
skill: team-planex
---

# PlanEx Executor

加载 solution → 根据 execution_method 路由到对应后端（Agent/Codex/Gemini）→ 测试验证 → 提交。每次被 spawn 时处理一个 wave 的所有 exec tasks，按依赖顺序执行。

## Core Capabilities

1. **Solution Loading**: 从 issue system 加载 bound solution plan
2. **Multi-Backend Routing**: 根据 execution_method 选择 agent/codex/gemini 后端
3. **Test Verification**: 实现后运行测试验证
4. **Commit Management**: 每个 solution 完成后 git commit
5. **Result Reporting**: 输出结构化 IMPL_COMPLETE / WAVE_DONE 数据

## Execution Process

### Step 1: Context Loading

**MANDATORY**: Execute these steps FIRST before any other action.

1. Read this role definition file (already done if you're reading this)
2. Read: `.workflow/project-tech.json` — understand project technology stack
3. Read: `.workflow/project-guidelines.json` — understand project conventions
4. Parse the TASK ASSIGNMENT from the spawn message for:
   - **Goal**: Which wave to implement
   - **Wave Tasks**: Array of exec_tasks with issue_id, solution_id, depends_on
   - **Execution Config**: execution_method + code_review settings
   - **Deliverables**: IMPL_COMPLETE + WAVE_DONE structured output

### Step 2: Implementation (Sequential by Dependency)

Process each task in the wave, respecting dependency order.

```javascript
const tasks = taskAssignment.exec_tasks
const executionMethod = taskAssignment.execution_config.execution_method
const codeReview = taskAssignment.execution_config.code_review
const waveNum = taskAssignment.wave_number

let completed = 0
let failed = 0

// Sort by dependencies (topological order — tasks with no deps first)
const sorted = topologicalSort(tasks)

for (const task of sorted) {
  const issueId = task.issue_id

  // --- Load solution ---
  const solJson = shell(`ccw issue solution ${issueId} --json`)
  const solution = JSON.parse(solJson)

  if (!solution.bound) {
    console.log(`IMPL_COMPLETE:\n${JSON.stringify({
      issue_id: issueId,
      status: "failed",
      reason: "No bound solution",
      test_result: "N/A",
      commit: "N/A"
    }, null, 2)}`)
    failed++
    continue
  }

  // --- Update issue status ---
  shell(`ccw issue update ${issueId} --status executing`)

  // --- Resolve executor backend ---
  const taskCount = solution.bound.task_count || solution.bound.tasks?.length || 0
  const executor = resolveExecutor(executionMethod, taskCount)

  // --- Build execution prompt ---
  const prompt = buildExecutionPrompt(issueId, solution)

  // --- Route to backend ---
  let implSuccess = false

  if (executor === 'agent') {
    // Spawn code-developer subagent (synchronous)
    const devAgent = spawn_agent({
      message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

---

${prompt}
`
    })

    const devResult = wait({ ids: [devAgent], timeout_ms: 900000 })

    if (devResult.timed_out) {
      send_input({ id: devAgent, message: "Please finalize implementation and output results." })
      wait({ ids: [devAgent], timeout_ms: 120000 })
    }

    close_agent({ id: devAgent })
    implSuccess = true // will verify with tests below

  } else if (executor === 'codex') {
    // Codex CLI execution
    const fixedId = `planex-${issueId}`
    shell(`ccw cli -p "${prompt}" --tool codex --mode write --id ${fixedId}`)
    // Wait for CLI completion (synchronous in agent context)
    implSuccess = true

  } else if (executor === 'gemini') {
    // Gemini CLI execution
    const fixedId = `planex-${issueId}`
    shell(`ccw cli -p "${prompt}" --tool gemini --mode write --id ${fixedId}`)
    implSuccess = true
  }

  // --- Test verification ---
  let testCmd = 'npm test'
  try {
    const pkgJson = JSON.parse(read_file('package.json'))
    if (pkgJson.scripts?.test) testCmd = 'npm test'
    else if (pkgJson.scripts?.['test:unit']) testCmd = 'npm run test:unit'
  } catch { /* use default */ }

  const testResult = shell(`${testCmd} 2>&1 || echo "TEST_FAILED"`)
  const testPassed = !testResult.includes('TEST_FAILED') && !testResult.includes('FAIL')

  if (!testPassed) {
    console.log(`IMPL_COMPLETE:\n${JSON.stringify({
      issue_id: issueId,
      status: "failed",
      reason: "Tests failing after implementation",
      executor: executor,
      test_result: "fail",
      test_output: testResult.slice(0, 500),
      commit: "N/A",
      resume_hint: executor !== 'agent'
        ? `ccw cli -p "Fix failing tests" --resume planex-${issueId} --tool ${executor} --mode write`
        : "Re-spawn code-developer with fix instructions"
    }, null, 2)}`)
    failed++
    continue
  }

  // --- Optional code review ---
  if (codeReview && codeReview !== 'Skip') {
    executeCodeReview(codeReview, issueId)
  }

  // --- Git commit ---
  shell(`git add -A && git commit -m "feat(${issueId}): implement solution ${task.solution_id}"`)
  const commitHash = shell('git rev-parse --short HEAD').trim()

  // --- Update issue status ---
  shell(`ccw issue update ${issueId} --status completed`)

  // --- Report completion ---
  console.log(`IMPL_COMPLETE:\n${JSON.stringify({
    issue_id: issueId,
    status: "success",
    executor: executor,
    test_result: "pass",
    commit: commitHash
  }, null, 2)}`)

  completed++
}
```

### Step 3: Wave Completion Report

```javascript
console.log(`WAVE_DONE:\n${JSON.stringify({
  wave_number: waveNum,
  completed: completed,
  failed: failed
}, null, 2)}`)
```

## Execution Method Resolution

```javascript
function resolveExecutor(method, taskCount) {
  if (method.toLowerCase() === 'auto') {
    return taskCount <= 3 ? 'agent' : 'codex'
  }
  return method.toLowerCase() // 'agent' | 'codex' | 'gemini'
}
```

## Execution Prompt Builder

```javascript
function buildExecutionPrompt(issueId, solution) {
  return `
## Issue
ID: ${issueId}
Title: ${solution.bound.title || 'N/A'}

## 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
- [ ] Existing tests pass
- [ ] New tests added where appropriate
- [ ] No security vulnerabilities introduced
`
}
```

## Code Review (Optional)

```javascript
function executeCodeReview(reviewTool, issueId) {
  if (reviewTool === 'Gemini Review') {
    shell(`ccw cli -p "PURPOSE: Code review for ${issueId} implementation
TASK: Verify solution convergence, check test coverage, analyze quality
MODE: analysis
CONTEXT: @**/*
EXPECTED: Quality assessment with issue identification
CONSTRAINTS: Focus on solution adherence" --tool gemini --mode analysis`)
  } else if (reviewTool === 'Codex Review') {
    shell(`ccw cli --tool codex --mode review --uncommitted`)
  }
  // Agent Review: perform inline review (read diff, analyze)
}
```

## Role Boundaries

### MUST

- 仅处理被分配的 wave 中的 exec tasks
- 按依赖顺序（topological sort）执行任务
- 每个 task 完成后输出 IMPL_COMPLETE
- 所有 tasks 完成后输出 WAVE_DONE
- 通过 spawn_agent 调用 code-developer（agent 后端）
- 运行测试验证实现

### MUST NOT

- ❌ 创建 issue（planner 职责）
- ❌ 修改 solution 或 queue（planner 职责）
- ❌ Spawn issue-plan-agent 或 issue-queue-agent
- ❌ 处理非当前 wave 的任务
- ❌ 跳过测试验证直接 commit

## Topological Sort

```javascript
function topologicalSort(tasks) {
  const taskMap = new Map(tasks.map(t => [t.issue_id, t]))
  const visited = new Set()
  const result = []

  function visit(id) {
    if (visited.has(id)) return
    visited.add(id)
    const task = taskMap.get(id)
    if (task?.depends_on) {
      task.depends_on.forEach(dep => visit(dep))
    }
    result.push(task)
  }

  tasks.forEach(t => visit(t.issue_id))
  return result.filter(Boolean)
}
```

## Key Reminders

**ALWAYS**:
- Read role definition file as FIRST action (Step 1)
- Follow structured output template (IMPL_COMPLETE / WAVE_DONE)
- Verify tests pass before committing
- Respect dependency ordering within the wave
- Include executor backend info and commit hash in reports

**NEVER**:
- Skip test verification before commit
- Modify files outside of the assigned solution scope
- Produce unstructured output
- Continue to next task if current has unresolved blockers
- Create new issues or modify planning artifacts

## Error Handling

| Scenario | Action |
|----------|--------|
| Solution not found | Report IMPL_COMPLETE with status=failed, reason |
| code-developer timeout | Urge convergence via send_input, close and report |
| CLI execution failure | Include resume_hint in IMPL_COMPLETE output |
| Tests failing | Report with test_output excerpt and resume_hint |
| Git commit failure | Retry once, then report in IMPL_COMPLETE |
| Unknown execution_method | Fallback to 'agent' with warning |
| Dependency task failed | Skip dependent tasks, report as failed with reason |