Claude-Code-Workflow/.claude/skills/team-coordinate/specs/role-template.md

Dynamic Role Template

Template used by coordinator to generate worker role.md files at runtime. Each generated role is written to <session>/roles/<role-name>.md.

Template

# Role: <role_name>

<role_description>

## Identity

- **Name**: `<role_name>` | **Tag**: `[<role_name>]`
- **Task Prefix**: `<prefix>-*`
- **Responsibility**: <responsibility_type>
<if inner_loop>
- **Mode**: Inner Loop (handle all `<prefix>-*` tasks in single agent)
</if>

## Boundaries

### MUST
- Only process `<prefix>-*` prefixed tasks
- All output (SendMessage, team_msg, logs) must carry `[<role_name>]` identifier
- Only communicate with coordinator via SendMessage
- Work strictly within <responsibility_type> responsibility scope
- Use fast-advance for simple linear successors (see SKILL.md Phase 5)
- Produce MD artifacts in `<session>/artifacts/`
<if inner_loop>
- Use subagent for heavy work (do not execute CLI/generation in main agent context)
- Maintain context_accumulator across tasks within the inner loop
- Loop through all `<prefix>-*` tasks before reporting to coordinator
</if>

### MUST NOT
- Execute work outside this role's responsibility scope
- Communicate directly with other worker roles (must go through coordinator)
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
- Modify files or resources outside this role's scope
- Omit `[<role_name>]` identifier in any output
- Fast-advance when multiple tasks are ready or at checkpoint boundaries
<if inner_loop>
- Execute heavy work (CLI calls, large document generation) in main agent (delegate to subagent)
- SendMessage to coordinator mid-loop (unless consensus_blocked HIGH or error count >= 3)
</if>

## Toolbox

| Tool | Purpose |
|------|---------|
<tools based on responsibility_type -- see reference sections below>

## Message Types

| Type | Direction | Description |
|------|-----------|-------------|
| `<prefix>_complete` | -> coordinator | Task completed with artifact path |
| `<prefix>_error` | -> coordinator | Error encountered |
| `capability_gap` | -> coordinator | Work outside role scope discovered |

## Message Bus

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

mcp__ccw-tools__team_msg({ operation: "log", team: , from: "<role_name>", to: "coordinator", type: , summary: "[<role_name>] complete: ", ref: })

**`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name.

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

Bash("ccw team log --team --from <role_name> --to coordinator --type --summary "[<role_name>] complete" --ref --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 `<prefix>-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

### Phase 2: <phase2_name>

<phase2_content -- generated by coordinator based on responsibility type>

### Phase 3: <phase3_name>

<phase3_content -- generated by coordinator based on task specifics>

### Phase 4: <phase4_name>

<phase4_content -- generated by coordinator based on responsibility type>

<if inline_discuss>
### Phase 4b: Inline Discuss (optional)

After primary work, optionally call discuss subagent:

Task({ subagent_type: "cli-discuss-agent", run_in_background: false, description: "Discuss ", prompt: "## Multi-Perspective Critique: See subagents/discuss-subagent.md for prompt template. Perspectives: " })

| Verdict | Severity | Action |
|---------|----------|--------|
| consensus_reached | - | Include action items in report, proceed to Phase 5 |
| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format. Do NOT self-revise. |
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed normally. |
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
</if>

<if inner_loop>
### Phase 5-L: Loop Completion (Inner Loop)

When more same-prefix tasks remain:

1. **TaskUpdate**: Mark current task completed
2. **team_msg**: Log task completion
3. **Accumulate summary**:

context_accumulator.append({ task: "", artifact: "", key_decisions: , discuss_verdict: <from Phase 4>, summary: })

4. **Interrupt check**:
- consensus_blocked HIGH -> SendMessage -> STOP
- Error count >= 3 -> SendMessage -> STOP
5. **Loop**: Back to Phase 1

**Does NOT**: SendMessage to coordinator, Fast-Advance spawn.

### Phase 5-F: Final Report (Inner Loop)

When all same-prefix tasks are done:

1. **TaskUpdate**: Mark last task completed
2. **team_msg**: Log completion
3. **Summary report**: All tasks summary + discuss results + artifact paths
4. **Fast-Advance check**: Check cross-prefix successors
5. **SendMessage** or **spawn successor**

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

<else>
### Phase 5: Report + Fast-Advance

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

Standard report flow: team_msg log -> SendMessage with `[<role_name>]` prefix -> TaskUpdate completed -> Fast-Advance Check -> Loop to Phase 1 for next task.
</if>

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| No <prefix>-* tasks available | Idle, wait for coordinator assignment |
| Context file not found | Notify coordinator, request location |
| Subagent fails | Retry once with fallback; still fails -> log error, continue next task |
| Fast-advance spawn fails | Fall back to SendMessage to coordinator |
<if inner_loop>
| Cumulative 3 task failures | SendMessage to coordinator, STOP inner loop |
| Agent crash mid-loop | Coordinator detects orphan on resume -> re-spawn -> resume from interrupted task |
</if>
| Work outside scope discovered | SendMessage capability_gap to coordinator |
| Critical issue beyond scope | SendMessage fix_required to coordinator |

---

Phase 2-4 Content by Responsibility Type

Reference sections for coordinator to fill when generating roles. Select the matching section based on responsibility_type.

orchestration

Phase 2: Context Assessment

| Input | Source | Required |
|-------|--------|----------|
| Task description | From TaskGet | Yes |
| Shared memory | <session>/shared-memory.json | No |
| Prior artifacts | <session>/artifacts/ | No |
| Wisdom | <session>/wisdom/ | No |

Loading steps:
1. Extract session path from task description
2. Read shared-memory.json for cross-role context
3. Read prior artifacts (if any exist from upstream tasks)
4. Load wisdom files for accumulated knowledge
5. Optionally call explore subagent for codebase context

Phase 3: Subagent Execution

Delegate to appropriate subagent based on task:

Task({
  subagent_type: "general-purpose",
  run_in_background: false,
  description: "<task-type> for <task-id>",
  prompt: "## Task
  - <task description>
  - Session: <session-folder>
  ## Context
  <prior artifacts + shared memory + explore results>
  ## Expected Output
  Write artifact to: <session>/artifacts/<artifact-name>.md
  Return JSON summary: { artifact_path, summary, key_decisions[], warnings[] }"
})

Phase 4: Result Aggregation

1. Verify subagent output artifact exists
2. Read artifact, validate structure/completeness
3. Update shared-memory.json with key findings
4. Write insights to wisdom/ files

code-gen (docs)

Phase 2: Load Prior Context

| Input | Source | Required |
|-------|--------|----------|
| Task description | From TaskGet | Yes |
| Prior artifacts | <session>/artifacts/ from upstream tasks | Conditional |
| Shared memory | <session>/shared-memory.json | No |
| Wisdom | <session>/wisdom/ | No |

Loading steps:
1. Extract session path from task description
2. Read upstream artifacts (e.g., research findings for a writer)
3. Read shared-memory.json for cross-role context
4. Load wisdom for accumulated decisions

Phase 3: Document Generation

Task({
  subagent_type: "universal-executor",
  run_in_background: false,
  description: "Generate <doc-type> for <task-id>",
  prompt: "## Task
  - Generate: <document type>
  - Session: <session-folder>
  ## Prior Context
  <upstream artifacts + shared memory>
  ## Instructions
  <task-specific writing instructions from coordinator>
  ## Expected Output
  Write document to: <session>/artifacts/<doc-name>.md
  Return JSON: { artifact_path, summary, key_decisions[], sections_generated[], warnings[] }"
})

Phase 4: Structure Validation

1. Verify document artifact exists
2. Check document has expected sections
3. Validate no placeholder text remains
4. Update shared-memory.json with document metadata

code-gen (code)

Phase 2: Load Plan/Specs

| Input | Source | Required |
|-------|--------|----------|
| Task description | From TaskGet | Yes |
| Plan/design artifacts | <session>/artifacts/ | Conditional |
| Shared memory | <session>/shared-memory.json | No |
| Wisdom | <session>/wisdom/ | No |

Loading steps:
1. Extract session path from task description
2. Read plan/design artifacts from upstream
3. Load shared-memory.json for implementation context
4. Load wisdom for conventions and patterns

Phase 3: Code Implementation

Task({
  subagent_type: "code-developer",
  run_in_background: false,
  description: "Implement <task-id>",
  prompt: "## Task
  - <implementation description>
  - Session: <session-folder>
  ## Plan/Design Context
  <upstream artifacts>
  ## Instructions
  <task-specific implementation instructions>
  ## Expected Output
  Implement code changes.
  Write summary to: <session>/artifacts/implementation-summary.md
  Return JSON: { artifact_path, summary, files_changed[], key_decisions[], warnings[] }"
})

Phase 4: Syntax Validation

1. Run syntax check (tsc --noEmit or equivalent)
2. Verify all planned files exist
3. Check no broken imports
4. If validation fails -> attempt auto-fix (max 2 attempts)
5. Write implementation summary to artifacts/

read-only

Phase 2: Target Loading

| Input | Source | Required |
|-------|--------|----------|
| Task description | From TaskGet | Yes |
| Target artifacts/files | From task description or upstream | Yes |
| Shared memory | <session>/shared-memory.json | No |

Loading steps:
1. Extract session path and target files from task description
2. Read target artifacts or source files for analysis
3. Load shared-memory.json for context

Phase 3: Multi-Dimension Analysis

Task({
  subagent_type: "general-purpose",
  run_in_background: false,
  description: "Analyze <target> for <task-id>",
  prompt: "## Task
  - Analyze: <target description>
  - Dimensions: <analysis dimensions from coordinator>
  - Session: <session-folder>
  ## Target Content
  <artifact content or file content>
  ## Expected Output
  Write report to: <session>/artifacts/analysis-report.md
  Return JSON: { artifact_path, summary, findings[], severity_counts: {critical, high, medium, low} }"
})

Phase 4: Severity Classification

1. Verify analysis report exists
2. Classify findings by severity (Critical/High/Medium/Low)
3. Update shared-memory.json with key findings
4. Write issues to wisdom/issues.md

validation

Phase 2: Environment Detection

| Input | Source | Required |
|-------|--------|----------|
| Task description | From TaskGet | Yes |
| Implementation artifacts | Upstream code changes | Yes |

Loading steps:
1. Detect test framework from project files
2. Get changed files from implementation
3. Identify test command and coverage tool

Phase 3: Test-Fix Cycle

Task({
  subagent_type: "test-fix-agent",
  run_in_background: false,
  description: "Test-fix for <task-id>",
  prompt: "## Task
  - Run tests and fix failures
  - Session: <session-folder>
  - Max iterations: 5
  ## Changed Files
  <from upstream implementation>
  ## Expected Output
  Write report to: <session>/artifacts/test-report.md
  Return JSON: { artifact_path, pass_rate, coverage, iterations_used, remaining_failures[] }"
})

Phase 4: Result Analysis

1. Check pass rate >= 95%
2. Check coverage meets threshold
3. Generate test report with pass/fail counts
4. Update shared-memory.json with test results