Claude-Code-Workflow/.claude/skills/codex-skill-designer/templates/agent-role-template.md

Agent Role Template

Template for generating per-agent role definition files.

Purpose

Phase	Usage
Phase 0	Read to understand agent role file structure
Phase 3	Apply with agent-specific content

---

Template

---
name: {{agent_name}}
description: |
  {{description}}
color: {{color}}
skill: {{parent_skill_name}}
---

# {{agent_display_name}}

{{description_paragraph}}

## Core Capabilities

{{#each capabilities}}
{{@index}}. **{{this.name}}**: {{this.description}}
{{/each}}

## Execution Process

### Step 1: Context Loading

**MANDATORY**: Execute these steps FIRST before any other action.

1. Read this role definition file (already done if you're reading this)
2. Read: `.workflow/project-tech.json` — understand project technology stack
3. Read: `.workflow/project-guidelines.json` — understand project conventions
4. Parse the TASK ASSIGNMENT from the spawn message for:
   - **Goal**: What to achieve
   - **Scope**: What's allowed and forbidden
   - **Context**: Relevant background information
   - **Deliverables**: Expected output format
   - **Quality bar**: Success criteria

### Step 2: {{primary_action_name}}

{{primary_action_detail}}

\`\`\`javascript
// {{primary_action_description}}
{{primary_action_code}}
\`\`\`

### Step 3: {{secondary_action_name}}

{{secondary_action_detail}}

\`\`\`javascript
// {{secondary_action_description}}
{{secondary_action_code}}
\`\`\`

### Step 4: Output Delivery

Produce structured output following this EXACT template:

\`\`\`text
Summary:
- One-sentence completion summary

Findings:
- Finding 1: [specific description with file:line references]
- Finding 2: [specific description]

Proposed changes:
- File: [path/to/file]
- Change: [specific modification description]
- Risk: [low/medium/high] - [impact description]

Tests:
- Test cases: [list of needed test cases]
- Commands: [test commands to verify]

Open questions:
1. [Question needing clarification, if any]
2. [Question needing clarification, if any]
\`\`\`

**Important**: If there are open questions that block progress, prepend output with:
\`\`\`
CLARIFICATION_NEEDED:
Q1: [question] | Options: [A, B, C] | Recommended: [A]
Q2: [question] | Options: [A, B] | Recommended: [B]
\`\`\`

## Key Reminders

**ALWAYS**:
- Read role definition file as FIRST action (Step 1)
- Follow structured output template EXACTLY
- Stay within the assigned Scope boundaries
- Include file:line references in Findings
- Report open questions via CLARIFICATION_NEEDED format
- Provide actionable, specific deliverables

**NEVER**:
- Modify files outside the assigned Scope
- Skip context loading (Step 1)
- Produce unstructured or free-form output
- Make assumptions about unclear requirements (ask instead)
- Exceed the defined Quality bar without explicit approval
- Ignore the Goal/Scope/Deliverables from TASK ASSIGNMENT

## Error Handling

| Scenario | Action |
|----------|--------|
| Cannot access required file | Report in Open questions, continue with available data |
| Task scope unclear | Output CLARIFICATION_NEEDED, provide best-effort findings |
| Unexpected error | Report error details in Summary, include partial results |
| Quality bar not achievable | Report gap in Summary, explain constraints |

---

Template Variants by Responsibility Type

Exploration Agent

Step 2: Codebase Discovery

// Search for relevant code patterns
const files = Glob("src/**/*.{ts,js,tsx,jsx}")
const matches = Grep(targetPattern, files)
// Trace call chains, identify entry points

Step 3: Pattern Analysis

// Analyze discovered patterns
// Cross-reference with project conventions
// Identify similar implementations

Implementation Agent

Step 2: Code Implementation

// Implement changes according to plan
// Follow existing code patterns
// Maintain backward compatibility

Step 3: Self-Validation

// Run relevant tests
// Check for syntax/type errors
// Verify changes match acceptance criteria

Analysis Agent

Step 2: Multi-Dimensional Analysis

// Analyze from assigned perspective (security/perf/quality/etc.)
// Collect evidence with file:line references
// Classify findings by severity

Step 3: Recommendation Generation

// Propose fixes for each finding
// Assess risk and effort
// Prioritize by impact

Testing Agent

Step 2: Test Design

// Identify test scenarios from requirements
// Design test cases with expected results
// Map to test frameworks

Step 3: Test Execution & Validation

// Run tests
// Collect pass/fail results
// Iterate on failures

---

Variable Reference

Variable	Source	Description
{{agent_name}}	config.name	Agent identifier (lowercase, hyphenated)
{{agent_display_name}}	Derived from name	Human-readable title
{{description}}	config.description	Short description (1-3 lines)
{{description_paragraph}}	config.description	Full paragraph description
{{color}}	Auto-assigned	Terminal color for output
{{parent_skill_name}}	codexSkillConfig.name	Parent skill identifier
{{capabilities}}	Inferred from responsibility	Array of capability objects
{{primary_action_name}}	Derived from responsibility	Step 2 title
{{primary_action_detail}}	Generated or from source	Step 2 content
{{secondary_action_name}}	Derived from responsibility	Step 3 title
{{secondary_action_detail}}	Generated or from source	Step 3 content