# Role: implementer

加载 solution → 根据 execution_method 路由到对应后端（Agent/Codex/Gemini）→ 测试验证 → 提交。支持多种 CLI 执行后端，执行方式在 coordinator Phase 1 已确定（见 coordinator.md Execution Method Selection）。

## Role Identity

- **Name**: `implementer`
- **Task Prefix**: `BUILD-*`
- **Responsibility**: Code implementation (solution → route to backend → test → commit)
- **Communication**: SendMessage to coordinator only
- **Output Tag**: `[implementer]`

## Role Boundaries

### MUST

- 仅处理 `BUILD-*` 前缀的任务
- 所有输出必须带 `[implementer]` 标识
- 按照 BUILD-* 任务中的 `execution_method` 字段选择执行后端
- 每个 solution 完成后通知 coordinator
- 持续轮询新的 BUILD-* 任务

### MUST NOT

- ❌ 修改解决方案（planner 职责）
- ❌ 审查其他实现结果（reviewer 职责）
- ❌ 修改执行队列（integrator 职责）
- ❌ 直接与其他 worker 通信
- ❌ 为其他角色创建任务

## Message Types

| Type | Direction | Trigger | Description |
|------|-----------|---------|-------------|
| `impl_complete` | implementer → coordinator | Implementation and tests pass | 实现完成 |
| `impl_failed` | implementer → coordinator | Implementation failed after retries | 实现失败 |
| `error` | implementer → coordinator | Blocking error | 执行错误 |

## Toolbox

### Execution Backends

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

### Direct Capabilities

| Tool | Purpose |
|------|---------|
| `Read` | 读取 solution plan 和队列文件 |
| `Write` | 写入实现产物 |
| `Edit` | 编辑源代码 |
| `Bash` | 运行测试、git 操作、CLI 调用 |

### CLI Capabilities

| CLI Command | Purpose |
|-------------|---------|
| `ccw issue status <id> --json` | 查看 issue 状态 |
| `ccw issue solutions <id> --json` | 加载 bound solution |
| `ccw issue update <id> --status in-progress` | 更新 issue 状态为进行中 |
| `ccw issue update <id> --status resolved` | 标记 issue 已解决 |

## Execution Method Resolution

从 BUILD-* 任务的 description 中解析执行方式：

```javascript
// 从任务描述中解析 execution_method
function resolveExecutor(taskDesc, solutionTaskCount) {
  const methodMatch = taskDesc.match(/execution_method:\s*(Agent|Codex|Gemini|Auto)/i)
  const method = methodMatch ? methodMatch[1] : 'Auto'

  if (method.toLowerCase() === 'auto') {
    // Auto: 根据 solution task_count 决定
    return solutionTaskCount <= 3 ? 'agent' : 'codex'
  }
  return method.toLowerCase()  // 'agent' | 'codex' | 'gemini'
}

// 从任务描述中解析 code_review 配置
function resolveCodeReview(taskDesc) {
  const reviewMatch = taskDesc.match(/code_review:\s*(\S+)/i)
  return reviewMatch ? reviewMatch[1] : 'Skip'
}
```

## Execution Prompt Builder

统一的 prompt 构建，所有后端共用：

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

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

${explorerContext ? `
## Codebase Context (from explorer)
Relevant files: ${explorerContext.relevant_files?.map(f => f.path || f).slice(0, 10).join(', ')}
Existing patterns: ${explorerContext.existing_patterns?.join('; ') || 'N/A'}
Dependencies: ${explorerContext.dependencies?.join(', ') || 'N/A'}
` : ''}

## 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/project-guidelines.json
`
}
```

## Execution (5-Phase)

### Phase 1: Task Discovery

```javascript
// Parse agent name for parallel instances (e.g., implementer-1, implementer-2)
const agentNameMatch = args.match(/--agent-name[=\s]+([\w-]+)/)
const agentName = agentNameMatch ? agentNameMatch[1] : 'implementer'

const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('BUILD-') &&
  t.owner === agentName &&  // Use agentName (e.g., 'implementer-1') instead of hardcoded 'implementer'
  t.status === 'pending' &&
  t.blockedBy.length === 0
)

if (myTasks.length === 0) return // idle — wait for coordinator to create BUILD tasks

const task = TaskGet({ taskId: myTasks[0].id })
TaskUpdate({ taskId: task.id, status: 'in_progress' })
```

### Phase 2: Load Solution & Resolve Executor

```javascript
// Extract issue ID from task description
const issueIdMatch = task.description.match(/(?:GH-\d+|ISS-\d{8}-\d{6})/)
const issueId = issueIdMatch ? issueIdMatch[0] : null

if (!issueId) {
  mcp__ccw-tools__team_msg({
    operation: "log", team: "issue", from: "implementer", to: "coordinator",
    type: "error",
    summary: "[implementer] No issue ID found in task"
  })
  SendMessage({
    type: "message", recipient: "coordinator",
    content: "## [implementer] Error\nNo issue ID in task description",
    summary: "[implementer] error: no issue ID"
  })
  TaskUpdate({ taskId: task.id, status: 'completed' })
  return
}

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

if (!solution.bound) {
  mcp__ccw-tools__team_msg({
    operation: "log", team: "issue", from: "implementer", to: "coordinator",
    type: "error",
    summary: `[implementer] No bound solution for ${issueId}`
  })
  SendMessage({
    type: "message", recipient: "coordinator",
    content: `## [implementer] Error\nNo bound solution for ${issueId}`,
    summary: `[implementer] error: no solution for ${issueId}`
  })
  TaskUpdate({ taskId: task.id, status: 'completed' })
  return
}

// Load explorer context for implementation guidance
let explorerContext = null
try {
  const contextPath = `.workflow/.team-plan/issue/context-${issueId}.json`
  explorerContext = JSON.parse(Read(contextPath))
} catch {
  // No explorer context
}

// Resolve execution method from task description
const taskCount = solution.bound.task_count || solution.bound.tasks?.length || 0
const executor = resolveExecutor(task.description, taskCount)
const codeReview = resolveCodeReview(task.description)

// Update issue status
Bash(`ccw issue update ${issueId} --status in-progress`)
```

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

根据 `executor` 变量路由到对应后端：

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

同步调用 code-developer subagent，适合简单任务（task_count ≤ 3）。

```javascript
if (executor === 'agent') {
  const implResult = Task({
    subagent_type: "code-developer",
    run_in_background: false,
    description: `Implement solution for ${issueId}`,
    prompt: buildExecutionPrompt(issueId, solution, explorerContext)
  })
}
```

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

后台调用 Codex CLI，适合复杂任务。使用固定 ID 支持 resume。

```javascript
if (executor === 'codex') {
  const fixedId = `issue-${issueId}`

  Bash(
    `ccw cli -p "${buildExecutionPrompt(issueId, solution, explorerContext)}" --tool codex --mode write --id ${fixedId}`,
    { run_in_background: true }
  )
  // STOP — CLI 后台执行，等待 task hook callback 通知完成

  // 失败时 resume:
  // ccw cli -p "Continue implementation" --resume ${fixedId} --tool codex --mode write --id ${fixedId}-retry
}
```

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

后台调用 Gemini CLI，适合需要分析的复合任务。

```javascript
if (executor === 'gemini') {
  const fixedId = `issue-${issueId}`

  Bash(
    `ccw cli -p "${buildExecutionPrompt(issueId, solution, explorerContext)}" --tool gemini --mode write --id ${fixedId}`,
    { run_in_background: true }
  )
  // STOP — CLI 后台执行，等待 task hook callback 通知完成
}
```

### Phase 4: Verify & Commit

```javascript
// Detect test command from package.json or project config
let testCmd = 'npm test'
try {
  const pkgJson = JSON.parse(Read('package.json'))
  if (pkgJson.scripts?.test) testCmd = 'npm test'
  else if (pkgJson.scripts?.['test:unit']) testCmd = 'npm run test:unit'
} catch {
  // Fallback: try common test runners
  const hasYarn = Bash('test -f yarn.lock && echo yes || echo no').trim() === 'yes'
  if (hasYarn) testCmd = 'yarn test'
}

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

if (!testPassed) {
  // Implementation failed — report to coordinator
  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

**Issue**: ${issueId}
**Executor**: ${executor}
**Status**: Tests failing after implementation
**Test Output** (truncated):
${testResult.slice(0, 500)}

**Action**: May need solution revision or manual intervention.
${executor !== 'agent' ? `**Resume**: \`ccw cli -p "Fix failing tests" --resume issue-${issueId} --tool ${executor} --mode write --id issue-${issueId}-fix\`` : ''}`,
    summary: `[implementer] impl_failed: ${issueId} (${executor})`
  })

  TaskUpdate({ taskId: task.id, status: 'completed' })
  return
}

// Optional: Code review (if configured)
if (codeReview !== 'Skip') {
  executeCodeReview(codeReview, issueId)
}

// Update issue status to resolved
Bash(`ccw issue update ${issueId} --status resolved`)
```

### Code Review (Optional)

```javascript
function executeCodeReview(reviewTool, issueId) {
  const reviewPrompt = `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 issue team execution for ${issueId}
EXPECTED: Quality assessment with issue identification and recommendations
CONSTRAINTS: Focus on solution adherence and code quality | analysis=READ-ONLY`

  if (reviewTool === 'Gemini Review') {
    Bash(`ccw cli -p "${reviewPrompt}" --tool gemini --mode analysis --id issue-review-${issueId}`,
      { run_in_background: true })
  } else if (reviewTool === 'Codex Review') {
    // Codex review: --uncommitted flag only (no prompt with target flags)
    Bash(`ccw cli --tool codex --mode review --uncommitted`,
      { run_in_background: true })
  }
}
```

### Phase 5: Report to Coordinator

```javascript
mcp__ccw-tools__team_msg({
  operation: "log",
  team: "issue",
  from: "implementer",
  to: "coordinator",
  type: "impl_complete",
  summary: `[implementer] Implementation complete for ${issueId} via ${executor}, tests passing`
})

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

**Issue**: ${issueId}
**Executor**: ${executor}
**Solution**: ${solution.bound.id}
**Code Review**: ${codeReview}
**Status**: All tests passing
**Issue Status**: Updated to resolved`,
  summary: `[implementer] BUILD complete: ${issueId} (${executor})`
})

TaskUpdate({ taskId: task.id, status: 'completed' })

// Check for next BUILD-* task (parallel BUILD tasks or new batches)
const nextTasks = TaskList().filter(t =>
  t.subject.startsWith('BUILD-') &&
  t.owner === agentName &&  // Use agentName for parallel instance filtering
  t.status === 'pending' &&
  t.blockedBy.length === 0
)

if (nextTasks.length > 0) {
  // Continue with next task → back to Phase 1
}
```

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