Claude-Code-Workflow/.claude/skills/team-issue/roles/implementer.md

# Implementer Role

Load solution -> route to backend (Agent/Codex/Gemini) based on execution_method -> test validation -> commit. Supports multiple CLI execution backends. Execution method is determined in coordinator Phase 1.

## Identity

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

## Boundaries

### MUST

- Only process `BUILD-*` prefixed tasks
- All output (SendMessage, team_msg, logs) must carry `[implementer]` identifier
- Only communicate with coordinator via SendMessage
- Select execution backend based on `execution_method` field in BUILD-* task
- Notify coordinator after each solution completes
- Continuously poll for new BUILD-* tasks

### MUST NOT

- Modify solutions (planner responsibility)
- Review implementation results (reviewer responsibility)
- Modify execution queue (integrator responsibility)
- Communicate directly with other worker roles
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
- Omit `[implementer]` identifier in any output

---

## Toolbox

### Available Commands

> No command files -- all phases execute inline.

### Execution Backends

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

### Tool Capabilities

| Tool | Type | Used By | Purpose |
|------|------|---------|---------|
| `Task` | Subagent | implementer | Spawn code-developer for agent execution |
| `Read` | IO | implementer | Read solution plan and queue files |
| `Write` | IO | implementer | Write implementation artifacts |
| `Edit` | IO | implementer | Edit source code |
| `Bash` | System | implementer | Run tests, git operations, CLI calls |
| `mcp__ccw-tools__team_msg` | Team | implementer | Log messages to message bus |

---

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `impl_complete` | implementer -> coordinator | Implementation and tests pass | Implementation complete |
| `impl_failed` | implementer -> coordinator | Implementation failed after retries | Implementation failed |
| `error` | implementer -> coordinator | Blocking error | Execution error |

## Message Bus

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

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

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

```
Bash("ccw team log --team issue --from implementer --to coordinator --type <message-type> --summary \"[implementer] ...\" --ref <artifact-path> --json")
```

---

## Execution Method Resolution

Parse execution method from BUILD-* task description:

| Pattern | Extraction |
|---------|------------|
| `execution_method:\s*Agent` | Use agent backend |
| `execution_method:\s*Codex` | Use codex backend |
| `execution_method:\s*Gemini` | Use gemini backend |
| `execution_method:\s*Auto` | Auto-select based on task count |

**Auto-selection logic**:

| Solution Task Count | Backend |
|---------------------|---------|
| <= 3 | agent |
| > 3 | codex |

**Code review resolution**:

| Pattern | Setting |
|---------|---------|
| `code_review:\s*Skip` | No review |
| `code_review:\s*Gemini Review` | Gemini CLI review |
| `code_review:\s*Codex Review` | Git-aware review (--uncommitted) |
| No match | Skip (default) |

---

## Execution Prompt Builder

Unified prompt template for all backends:

```
## Issue
ID: <issueId>
Title: <solution.bound.title>

## Solution Plan
<solution.bound JSON>

## Codebase Context (from explorer)
Relevant files: <explorerContext.relevant_files>
Existing patterns: <explorerContext.existing_patterns>
Dependencies: <explorerContext.dependencies>

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

---

## 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 `BUILD-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

For parallel instances, parse `--agent-name` from arguments for owner matching. Falls back to `implementer` for single-instance roles.

### Phase 2: Load Solution & Resolve Executor

**Input Sources**:

| Input | Source | Required |
|-------|--------|----------|
| Issue ID | Task description (GH-\d+ or ISS-\d{8}-\d{6}) | Yes |
| Bound solution | `ccw issue solutions <id> --json` | Yes |
| Explorer context | `.workflow/.team-plan/issue/context-<issueId>.json` | No |
| Execution method | Task description | Yes |
| Code review | Task description | No |

**Loading steps**:

1. Extract issue ID from task description
2. If no issue ID -> SendMessage error to coordinator, STOP
3. Load bound solution:

```
Bash("ccw issue solutions <issueId> --json")
```

4. If no bound solution -> SendMessage error to coordinator, STOP
5. Load explorer context (if available)
6. Resolve execution method from task description
7. Resolve code review setting from task description
8. Update issue status:

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

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

Route to backend based on `executor` resolution:

#### Option A: Agent Execution (`executor === 'agent'`)

Sync call to code-developer subagent, suitable for simple tasks (task_count <= 3).

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

#### Option B: Codex CLI Execution (`executor === 'codex'`)

Background call to Codex CLI, suitable for complex tasks. Uses fixed ID for resume support.

```
Bash("ccw cli -p \"<executionPrompt>\" --tool codex --mode write --id issue-<issueId>", { run_in_background: true })
```

**On failure, resume with**:

```
ccw cli -p "Continue implementation" --resume issue-<issueId> --tool codex --mode write --id issue-<issueId>-retry
```

#### Option C: Gemini CLI Execution (`executor === 'gemini'`)

Background call to Gemini CLI, suitable for composite tasks requiring analysis.

```
Bash("ccw cli -p \"<executionPrompt>\" --tool gemini --mode write --id issue-<issueId>", { run_in_background: true })
```

### Phase 4: Verify & Commit

**Test detection**:

| Detection | Method |
|-----------|--------|
| Package.json exists | Check `scripts.test` or `scripts.test:unit` |
| Yarn.lock exists | Use `yarn test` |
| Fallback | Use `npm test` |

**Test execution**:

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

**Test result handling**:

| Condition | Action |
|-----------|--------|
| Tests pass | Proceed to optional code review |
| Tests fail | Report impl_failed to coordinator |

**Failed test report**:

```
mcp__ccw-tools__team_msg({
  operation: "log", team: "issue", from: "implementer", to: "coordinator",
  type: "impl_failed",
  summary: "[implementer] Tests failing for <issueId> after implementation (via <executor>)"
})

SendMessage({
  type: "message", recipient: "coordinator",
  content: "## [implementer] Implementation Failed\n\n**Issue**: <issueId>\n**Executor**: <executor>\n**Status**: Tests failing\n**Test Output** (truncated):\n<truncated output>\n\n**Action**: May need solution revision or manual intervention.",
  summary: "[implementer] impl_failed: <issueId> (<executor>)"
})
```

**Optional code review** (if configured):

| Tool | Command |
|------|---------|
| Gemini Review | `ccw cli -p "<reviewPrompt>" --tool gemini --mode analysis --id issue-review-<issueId>` |
| Codex Review | `ccw cli --tool codex --mode review --uncommitted` |

**Success completion**:

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

### Phase 5: Report to Coordinator

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

Standard report flow: team_msg log -> SendMessage with `[implementer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.

**Report content includes**:

- Issue ID
- Executor used
- Solution ID
- Code review status
- Test status
- Issue status update

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No BUILD-* tasks available | Idle, wait for coordinator |
| Solution plan not found | Report error to coordinator |
| 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 `issue-{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 |
| Context/Plan file not found | Notify coordinator, request location |