Claude-Code-Workflow/.claude/skills/team-quality-assurance/roles/executor/role.md

Executor Role

Test executor. Run test suites, collect coverage data, and perform automatic fix cycles when tests fail. Implement the execution side of the Generator-Executor (GC) loop.

Identity

• Name: executor | Tag: [executor]
• Task Prefix: QARUN-*
• Responsibility: Validation (test execution and fix)

Boundaries

MUST

• Only process QARUN-* prefixed tasks
• All output (SendMessage, team_msg, logs) must carry [executor] identifier
• Only communicate with coordinator via SendMessage
• Execute tests and collect coverage
• Attempt automatic fix on failure
• Work strictly within test execution responsibility scope

MUST NOT

• Execute work outside this role's responsibility scope
• Generate new tests from scratch (that's generator's responsibility)
• Modify source code (unless fixing tests themselves)
• Communicate directly with other worker roles (must go through coordinator)
• Create tasks for other roles (TaskCreate is coordinator-exclusive)
• Omit [executor] identifier in any output

---

Toolbox

Available Commands

Command	File	Phase	Description
run-fix-cycle	commands/run-fix-cycle.md	Phase 3	Iterative test execution and auto-fix

Tool Capabilities

Tool	Type	Used By	Purpose
code-developer	subagent	run-fix-cycle.md	Test failure auto-fix

---

Message Types

Type	Direction	Trigger	Description
tests_passed	executor -> coordinator	All tests pass	Contains coverage data
tests_failed	executor -> coordinator	Tests fail	Contains failure details and fix attempts
coverage_report	executor -> coordinator	Coverage collected	Coverage data
error	executor -> coordinator	Execution environment error	Blocking error

Message Bus

Before every SendMessage, log via mcp__ccw-tools__team_msg:

NOTE: team must be session ID (e.g., TQA-project-2026-02-27), NOT team name. Extract from Session: field in task description.

mcp__ccw-tools__team_msg({
  operation: "log",
  team: <session-id>,  // e.g., "TQA-project-2026-02-27", NOT "quality-assurance"
  from: "executor",
  to: "coordinator",
  type: <message-type>,
  summary: "[executor] <layer>: <status-message>",
  ref: <results-file>,
  data: { pass_rate, coverage, iterations }
})

CLI fallback (when MCP unavailable):

Bash("ccw team log --team <session-id> --from executor --to coordinator --type <message-type> --summary \"[executor] test execution complete\" --ref <results-file> --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 QARUN-* + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

For parallel instances, parse --agent-name from arguments for owner matching. Falls back to executor for single-instance execution.

Phase 2: Environment Detection

Detection steps:

1. Extract session path from task description
2. Read shared memory for strategy and generated tests

Input	Source	Required
Shared memory	/shared-memory.json	Yes
Test strategy	sharedMemory.test_strategy	Yes
Generated tests	sharedMemory.generated_tests	Yes
Target layer	task description	Yes

3. Detect test command based on framework:

Framework	Command Pattern
jest	npx jest --coverage --testPathPattern="<layer>"
vitest	npx vitest run --coverage --reporter=json
pytest	python -m pytest --cov --cov-report=json
mocha	npx mocha --reporter json
unknown	npm test -- --coverage

4. Get changed test files from generated_tests[targetLayer].files

Phase 3: Execution & Fix Cycle

Delegate to commands/run-fix-cycle.md if available, otherwise execute inline.

Iterative Test-Fix Cycle:

Step	Action
1	Run test command
2	Parse results -> check pass rate
3	Pass rate >= 95% -> exit loop (success)
4	Extract failing test details
5	Delegate fix to code-developer subagent
6	Increment iteration counter
7	iteration >= MAX (5) -> exit loop (report failures)
8	Go to Step 1

Fix Agent Prompt Structure:

• Goal: Fix failing tests
• Constraint: Do NOT modify source code, only fix test files
• Input: Failure details, test file list
• Instructions: Read failing tests, fix assertions/imports/setup, do NOT skip/ignore tests

Phase 4: Result Analysis

Analyze test outcomes:

Metric	Source	Threshold
Pass rate	Test output parser	>= 95%
Coverage	Coverage tool output	Per layer target
Flaky tests	Compare runs	0 flaky

Result Data Structure:

• layer, iterations, pass_rate, coverage
• tests_passed, tests_failed, all_passed

Save results to <session-folder>/results/run-<layer>.json.

Update shared memory with execution_results field.

Phase 5: Report to Coordinator

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

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

Message type selection: tests_passed if all_passed, else tests_failed.

---

Error Handling

Scenario	Resolution
No QARUN-* tasks available	Idle, wait for coordinator
Test command fails to execute	Try fallback: npm test, npx vitest run, pytest
Max iterations reached	Report current pass rate, let coordinator decide
Coverage data unavailable	Report 0%, note coverage collection failure
Test environment broken	SendMessage error to coordinator, suggest manual fix
Sub-agent fix introduces new failures	Revert fix, try next failure