Claude-Code-Workflow/.claude/skills/team-lifecycle-v3/roles/README.md

Role Directory Guide

This directory contains all agent role specifications for Team Lifecycle v3.

Directory Structure

roles/
├── README.md                    # This file
├── coordinator/                 # Orchestrator agent
│   ├── role.md                 # Coordinator specification
│   └── commands/               # User command handlers
│       ├── dispatch.md
│       └── monitor.md
├── pipeline/                    # Core pipeline roles (always present)
│   ├── analyst.md              # Research and discovery
│   ├── writer.md               # Document drafting
│   ├── planner.md              # Implementation planning
│   ├── executor.md             # Code implementation
│   ├── tester.md               # Test generation
│   ├── reviewer.md             # Quality review
│   ├── architect.md            # Architecture design (consulting)
│   ├── fe-developer.md         # Frontend development (consulting)
│   └── fe-qa.md                # Frontend QA (consulting)
└── specialists/                 # Specialist roles (dynamically injected)
    ├── orchestrator.role.md    # Multi-module coordination
    ├── security-expert.role.md # Security analysis
    ├── performance-optimizer.role.md # Performance optimization
    ├── data-engineer.role.md   # Data pipeline work
    ├── devops-engineer.role.md # DevOps and deployment
    └── ml-engineer.role.md     # ML/AI implementation

Role Types

Coordinator (Orchestrator)

Location: coordinator/

Purpose: Manages workflow orchestration, task dependencies, role injection, and artifact registry.

Key Responsibilities:

• Parse user requests and clarify requirements
• Create and manage team sessions
• Analyze complexity and inject specialist roles
• Create task chains with dependencies
• Spawn workers and handle callbacks
• Validate artifacts and advance pipeline
• Display checkpoints and handle user commands

Always Present: Yes

Spawned By: Skill invocation

Pipeline Roles (Core Team)

Location: pipeline/

Purpose: Execute standard development workflow tasks.

Always Present: Yes (based on pipeline selection)

Spawned By: Coordinator

Core Pipeline Roles

Role	File	Purpose	Task Prefix
analyst	analyst.md	Research and discovery	RESEARCH-*
writer	writer.md	Document drafting	DRAFT-*
planner	planner.md	Implementation planning	PLAN-*
executor	executor.md	Code implementation	IMPL-*
tester	tester.md	Test generation and execution	TEST-*
reviewer	reviewer.md	Quality review and improvement	REVIEW-, QUALITY-, IMPROVE-*

Consulting Roles

Role	File	Purpose	Task Prefix	Injection Trigger
architect	architect.md	Architecture design	ARCH-*	High complexity
fe-developer	fe-developer.md	Frontend development	DEV-FE-*	Frontend tasks
fe-qa	fe-qa.md	Frontend QA	QA-FE-*	Frontend tasks

Specialist Roles (Dynamic Injection)

Location: specialists/

Purpose: Provide expert capabilities for specific domains.

Always Present: No (injected based on task analysis)

Spawned By: Coordinator (after complexity/keyword analysis)

Role	File	Purpose	Task Prefix	Injection Trigger
orchestrator	orchestrator.role.md	Multi-module coordination	ORCH-*	Medium/High complexity
security-expert	security-expert.role.md	Security analysis and audit	SECURITY-*	Keywords: security, vulnerability, OWASP, auth
performance-optimizer	performance-optimizer.role.md	Performance optimization	PERF-*	Keywords: performance, optimization, bottleneck
data-engineer	data-engineer.role.md	Data pipeline work	DATA-*	Keywords: data, pipeline, ETL, schema
devops-engineer	devops-engineer.role.md	DevOps and deployment	DEVOPS-*	Keywords: devops, CI/CD, deployment, docker
ml-engineer	ml-engineer.role.md	ML/AI implementation	ML-*	Keywords: ML, model, training, inference

Role Specification Format

All role specifications follow this structure:

---
role: <role-name>
type: <coordinator|pipeline|specialist>
task_prefix: <TASK-PREFIX>
priority: <P0|P1|P2>
injection_trigger: <always|complexity|keywords>
---

# Role: <Role Name>

## Purpose

Brief description of role purpose.

## Responsibilities

- Responsibility 1
- Responsibility 2

## Phase Execution

### Phase 1: Task Discovery
...

### Phase 2: Context Gathering
...

### Phase 3: Domain Work
...

### Phase 4: Artifact Generation
...

### Phase 5: Reporting
...

## Tools & Capabilities

- Tool 1
- Tool 2

## Artifact Contract

Expected artifacts and manifest schema.

Worker Execution Model

All workers (pipeline and specialist roles) follow the 5-phase execution model:

1. Phase 1: Task Discovery - Read task metadata, understand requirements
2. Phase 2: Context Gathering - Discover upstream artifacts, gather context
3. Phase 3: Domain Work - Execute role-specific work
4. Phase 4: Artifact Generation - Generate deliverables with manifest
5. Phase 5: Reporting - Report completion to coordinator

CLI Tool Integration

Workers can use CLI tools for complex analysis:

Capability	CLI Command	Used By
Codebase exploration	ccw cli --tool gemini --mode analysis	analyst, planner, architect
Multi-perspective critique	ccw cli --tool gemini --mode analysis (parallel)	analyst, writer, reviewer
Document generation	ccw cli --tool gemini --mode write	writer

Note: Workers CANNOT spawn utility members (explorer, discussant). Only the coordinator can spawn utility members.

Utility Members (Coordinator-Only)

Utility members are NOT roles but specialized subagents that can only be spawned by the coordinator:

Utility	Purpose	Callable By
explorer	Parallel multi-angle exploration	Coordinator only
discussant	Aggregate multi-CLI critique	Coordinator only
doc-generator	Template-based doc generation	Coordinator only

Location: ../subagents/ (not in roles directory)

Adding New Roles

To add a new specialist role:

1. Create role specification file in specialists/ directory
2. Follow the role specification format
3. Define injection trigger (keywords or complexity)
4. Update ../specs/team-config.json role registry
5. Update coordinator's role injection logic
6. Test with sample task descriptions

Role Selection Logic

Pipeline Selection

Coordinator selects pipeline based on user requirements:

• Spec-only: Documentation, requirements, design work
• Impl-only: Quick implementations with clear requirements
• Full-lifecycle: Complete feature development

Specialist Injection

Coordinator analyzes task description for:

1. Keywords: Specific domain terms (security, performance, data, etc.)
2. Complexity: Module count, dependency depth
3. Explicit requests: User mentions specific expertise needed

Conditional Routing

PLAN-001 assesses complexity and routes to appropriate implementation strategy:

• Low complexity → Direct implementation (executor only)
• Medium complexity → Orchestrated implementation (orchestrator + parallel executors)
• High complexity → Architecture + orchestrated implementation (architect + orchestrator + parallel executors)

Reference Documents

For detailed information, see:

• ../specs/core-concepts.md - Foundational principles
• ../specs/execution-flow.md - Execution walkthrough
• ../specs/artifact-contract-spec.md - Artifact manifest specification
• coordinator/role.md - Coordinator specification