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

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 中解析执行方式：

// 从任务描述中解析 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 构建，所有后端共用：

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

const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('BUILD-') &&
  t.owner === '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

// 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）。

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。

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，适合需要分析的复合任务。

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

// 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)

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

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 === 'implementer' &&
  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