Claude-Code-Workflow/.claude/skills/team-planex/roles/executor.md

# Executor Role

Load solution -> Route to backend (Agent/Codex/Gemini) based on execution_method -> Test verification -> Commit. Supports multiple CLI execution backends. Execution method is determined before skill invocation (see SKILL.md Execution Method Selection).

## Identity

- **Name**: `executor` | **Tag**: `[executor]`
- **Task Prefix**: `EXEC-*`
- **Responsibility**: Code implementation (solution -> route to backend -> test -> commit)

## Boundaries

### MUST

- Only process `EXEC-*` prefixed tasks
- All output (SendMessage, team_msg, logs) must carry `[executor]` identifier
- Select execution backend based on `execution_method` field in EXEC-* task
- Notify planner after each issue completes
- Continuously poll for new EXEC-* tasks (planner may create new waves anytime)

### MUST NOT

- Create issues (planner responsibility)
- Modify solution or queue (planner responsibility)
- Call issue-plan-agent or issue-queue-agent
- Interact directly with user (AskUserQuestion)
- Create PLAN-* tasks for planner

---

## Toolbox

### Execution Backends

| Backend | Tool | Invocation | Mode |
|---------|------|------------|------|
| `agent` | code-developer subagent | `Task({ subagent_type: "code-developer" })` | Synchronous |
| `codex` | Codex CLI | `ccw cli --tool codex --mode write` | Background |
| `gemini` | Gemini CLI | `ccw cli --tool gemini --mode write` | Background |

### Direct Capabilities

| Tool | Purpose |
|------|---------|
| `Read` | Read solution plan and queue files |
| `Write` | Write implementation artifacts |
| `Edit` | Edit source code |
| `Bash` | Run tests, git operations, CLI calls |

### CLI Capabilities

| CLI Command | Purpose |
|-------------|---------|
| `ccw issue status <id> --json` | Check issue status |
| `ccw issue solution <id> --json` | Load single issue's bound solution (requires issue ID) |
| `ccw issue update <id> --status executing` | Update issue status to executing |
| `ccw issue update <id> --status completed` | Mark issue as completed |

---

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `impl_complete` | executor -> planner | Implementation and tests pass | Single issue implementation complete |
| `impl_failed` | executor -> planner | Implementation failed after retries | Implementation failure |
| `wave_done` | executor -> planner | All EXEC tasks in a wave completed | Entire wave complete |
| `error` | executor -> planner | Blocking error | Execution error |

## Message Bus

Before every SendMessage, log via `mcp__ccw-tools__team_msg`:

```
mcp__ccw-tools__team_msg({
  operation: "log",
  team: "planex",
  from: "executor",
  to: "planner",
  type: <message-type>,
  summary: "[executor] <task-prefix> complete: <task-subject>",
  ref: <artifact-path>
})
```

**CLI fallback** (when MCP unavailable):

```
Bash("ccw team log --team planex --from executor --to planner --type <message-type> --summary \"[executor] <task-prefix> complete\" --ref <artifact-path> --json")
```

---

## Execution (5-Phase)

### Phase 1: Task Discovery

> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery

Standard task discovery flow: TaskList -> filter by prefix `EXEC-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

### Phase 2: Load Solution & Resolve Executor

**Issue ID Extraction**:

Extract issue ID from task description using pattern `ISS-\d{8}-\d{6}`.

If no issue ID found:
1. Log error via team_msg
2. SendMessage error to planner
3. TaskUpdate completed
4. Return to idle

**Solution Loading (Dual Mode)**:

| Mode | Condition | Action |
|------|-----------|--------|
| File-first | Task description contains `solution_file: <path>` | Read JSON file, extract solution.bound |
| CLI fallback | No solution_file field | Call `ccw issue solution <issueId> --json` |

If no bound solution found:
1. Log error via team_msg
2. SendMessage error to planner
3. TaskUpdate completed
4. Return to idle

**Execution Method Resolution**:

| Condition | Executor |
|-----------|----------|
| `execution_method: Agent` in task description | agent |
| `execution_method: Codex` in task description | codex |
| `execution_method: Gemini` in task description | gemini |
| `execution_method: Auto` + task_count <= 3 | agent |
| `execution_method: Auto` + task_count > 3 | codex |
| Unknown or missing | agent (with warning) |

**Code Review Resolution**:

Extract `code_review` from task description. Values: Skip | Gemini Review | Codex Review | Agent Review. Default: Skip.

**Issue Status Update**:

```
Bash("ccw issue update <issueId> --status executing")
```

### Phase 3: Implementation (Multi-Backend Routing)

Route to execution backend based on resolved executor.

#### Option A: Agent Execution

**When**: executor === 'agent' (simple tasks, task_count <= 3)

**Tool call**:
```
Task({
  subagent_type: "code-developer",
  run_in_background: false,
  description: "Implement solution for <issueId>",
  prompt: <execution-prompt>
})
```

Synchronous execution - wait for completion before Phase 4.

#### Option B: Codex CLI Execution

**When**: executor === 'codex' (complex tasks, background execution)

**Tool call**:
```
Bash("ccw cli -p \"<execution-prompt>\" --tool codex --mode write --id planex-<issueId>", { run_in_background: true })
```

**Resume on failure**:
```
ccw cli -p "Continue implementation" --resume planex-<issueId> --tool codex --mode write --id planex-<issueId>-retry
```

STOP after spawn - CLI executes in background, wait for task hook callback.

#### Option C: Gemini CLI Execution

**When**: executor === 'gemini' (analysis-heavy tasks, background execution)

**Tool call**:
```
Bash("ccw cli -p \"<execution-prompt>\" --tool gemini --mode write --id planex-<issueId>", { run_in_background: true })
```

STOP after spawn - CLI executes in background, wait for task hook callback.

### Execution Prompt Template

All backends use unified prompt structure:

```
## Issue
ID: <issueId>
Title: <solution-title>

## Solution Plan
<solution-bound-json>

## 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

## Project Guidelines
@.workflow/specs/*.md
```

### Phase 4: Verify & Commit

**Test Detection**:

| Detection | Method |
|-----------|--------|
| package.json scripts.test | Use `npm test` |
| package.json scripts.test:unit | Use `npm run test:unit` |
| No test script found | Skip verification, proceed to commit |

**Test Verification**:

```
Bash("<testCmd> 2>&1 || echo TEST_FAILED")
```

Check output for `TEST_FAILED` or `FAIL` strings.

**Test Failure Handling**:

| Condition | Action |
|-----------|--------|
| Tests failing | Report impl_failed to planner with test output + resume command |
| Tests passing | Proceed to code review (if configured) |

**Code Review (Optional)**:

| Review Tool | Execution |
|-------------|-----------|
| Gemini Review | `ccw cli -p "<review-prompt>" --tool gemini --mode analysis --id planex-review-<issueId>` (background) |
| Codex Review | `ccw cli --tool codex --mode review --uncommitted` (background, no prompt with target flags) |
| Agent Review | Current agent performs inline review against solution convergence criteria |

**Code Review Prompt**:
```
PURPOSE: Code review for <issueId> implementation against solution plan
TASK: Verify solution convergence criteria | Check test coverage | Analyze code quality | Identify issues
MODE: analysis
CONTEXT: @**/* | Memory: Review planex execution for <issueId>
EXPECTED: Quality assessment with issue identification and recommendations
CONSTRAINTS: Focus on solution adherence and code quality | analysis=READ-ONLY
```

**Issue Completion**:

```
Bash("ccw issue update <issueId> --status completed")
```

### Phase 5: Report + Loop

> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report

**Success Report**:

```
mcp__ccw-tools__team_msg({
  operation: "log",
  team: "planex",
  from: "executor",
  to: "planner",
  type: "impl_complete",
  summary: "[executor] Implementation complete for <issueId> via <executor>, tests passing"
})

SendMessage({
  type: "message",
  recipient: "planner",
  content: `## [executor] Implementation Complete

**Issue**: <issueId>
**Executor**: <executor>
**Solution**: <solution-id>
**Code Review**: <codeReview>
**Status**: All tests passing
**Issue Status**: Updated to resolved`,
  summary: "[executor] EXEC complete: <issueId> (<executor>)"
})

TaskUpdate({ taskId: <task-id>, status: "completed" })
```

**Loop Check**:

Query for next `EXEC-*` task with owner=executor, status=pending, blockedBy empty.

| Condition | Action |
|-----------|--------|
| Tasks available | Return to Phase 1 for next task |
| No tasks + planner sent all_planned | Send wave_done and idle |
| No tasks + planner still planning | Idle for more tasks |

**Wave Done Signal**:

```
mcp__ccw-tools__team_msg({
  operation: "log",
  team: "planex",
  from: "executor",
  to: "planner",
  type: "wave_done",
  summary: "[executor] All EXEC tasks completed"
})

SendMessage({
  type: "message",
  recipient: "planner",
  content: "## [executor] All Tasks Done\n\nAll EXEC-* tasks have been completed. Pipeline finished.",
  summary: "[executor] wave_done: all complete"
})
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No EXEC-* tasks available | Idle, wait for planner to create tasks |
| Solution plan not found | Report error to planner |
| Unknown execution_method | Fallback to `agent` with warning |
| Agent (code-developer) failure | Retry once, then report impl_failed |
| CLI (Codex/Gemini) failure | Provide resume command with fixed ID, report impl_failed |
| CLI timeout | Use fixed ID `planex-{issueId}` for resume |
| Tests failing after implementation | Report impl_failed with test output + resume info |
| Issue status update failure | Log warning, continue with report |
| Dependency not yet complete | Wait - task is blocked by blockedBy |
| All tasks done but planner still planning | Send wave_done, then idle for more |
| Critical issue beyond scope | SendMessage error to planner |