roles

Team Roles

Overview

Team role definitions for both human teams and agent perspectives. These roles provide standardized expert perspectives during code reviews, planning, and validation.

Frontmatter Standard

All role documents MUST include YAML frontmatter with these fields:

---
name: role-name
description: |
  When to use this role and what expertise it provides.
  Include specific trigger conditions for agents.
model: balanced # Task-based model tier
---

Required Fields

Field	Description
name	Kebab-case identifier (e.g., tech-lead, senior-developer)
description	When to use this role; must be sufficient for agents to select without reading full document
model	Task-based model tier (see below)

Model Tiers

Task-based values that map to platform-specific models:

Value	Use Case	Claude	OpenAI
reasoning	Complex analysis, architecture design, security compliance	Opus 4.5	GPT-5.2
balanced	Code review, implementation validation, security review	Sonnet 4.5	GPT-5.1
speed	Quick validation, formatting checks, simple lookups	Haiku 4.5	GPT-5-nano
inherit	Use caller's model (see below)	(varies)	(varies)

Choosing Model Tiers

• reasoning: Use for roles requiring complex analysis, architectural decisions, threat modelling, or regulatory compliance. These tasks involve multi-step reasoning and trade-off evaluation.
• balanced: Use for most development roles - code review, implementation validation, testing, documentation. This is the default for implementation-focused work.
• speed: Use for quick validations, formatting checks, or simple lookups. Currently no roles use this tier as all roles require at least balanced capability for meaningful review.
• inherit: Use when the role's complexity should match the caller's context.

When in doubt, use balanced. Only use reasoning when the role explicitly requires deep analysis beyond typical code review.

Using inherit

The inherit tier means the role uses whatever model the calling agent or skill is using. Use this when:

• The role's complexity matches the caller's context
• You want to avoid model switching overhead
• The role is a subprocess of a larger task

Do not use inherit for roles that require specific model capabilities (e.g., security architecture requiring reasoning models).

Example

---
name: tech-lead
description: |
  Use for technical architecture decisions, design reviews, and cross-cutting
  concerns. Validates system design, evaluates trade-offs, and ensures
  architectural consistency.
model: reasoning # Complex analysis → Opus 4.5, GPT-5.2
---

Role Index

Development Roles

• Tech Lead - Technical architecture and design oversight
• Senior Developer - Code quality and implementation excellence
• Backend Developer - Stack-specific backend implementation and scalability
• Frontend Developer - Frontend implementation and browser security
• QA Engineer - Quality assurance and testing strategy

Security and Performance

• Security Reviewer - Security and threat modelling
• Performance Engineer - Performance optimization and scalability
• Security Architect - Security architecture and compliance

Operations and Infrastructure

• DevOps Engineer - Deployment, operations, and infrastructure
• Automation Engineer - Build-time automation and developer enablement
• Cloud Architect - Cloud infrastructure and platform design

Product and Design

• Product Owner - Business value and requirements
• Scrum Master - Process compliance and documentation completeness
• UX Expert - User experience and interface design
• Accessibility Expert - Accessibility and inclusive design

Documentation and Architecture

• Documentation Specialist - Documentation quality and accessibility
• Technical Architect - Enterprise architecture and system design
• Agent Skill Engineer - Agent skill design and optimization

Using Roles in Skills

When creating or updating skills:

1. Identify relevant roles: Determine which expert perspectives apply
2. Reference in "When to Use": Mention which roles should review
3. Include in BDD tests: Test scenarios with role perspectives
4. Document in examples: Show role usage in examples

Example

## When to Use

This skill should be reviewed by:

- **Tech Lead**: Validate architecture decisions
- **Senior Developer**: Review code quality
- **Security Reviewer**: Check for vulnerabilities

In BDD Tests

### GREEN Scenario: Multi-role review

**Given**: Implementation complete
**When**: Requesting code review
**Then**: Each role provides perspective:

- Tech Lead: ✅ Architecture sound
- Security Reviewer: ✅ No vulnerabilities found
- Senior Developer: ✅ Code quality excellent

In Code Review Requests

Please review from these perspectives:

**@role:security** - Authentication flow and input validation
**@role:performance** - Database query efficiency
**@role:senior-dev** - Code organization and clarity

Canonical Names

Use these exact names when referencing roles:

• Tech Lead (not: "Technical Lead", "Architect", "Tech Arch")
• Senior Developer (not: "Developer", "Sr Dev", "Engineer")
• Backend Developer (not: "Backend", "Backend Eng", "Server Dev")
• Frontend Developer (not: "Frontend", "Frontend Eng", "UI Dev")
• QA Engineer (not: "QA", "Tester", "Quality Assurance")
• Security Reviewer (not: "Security", "Sec Engineer", "AppSec")
• Performance Engineer (not: "Performance", "Perf Engineer")
• DevOps Engineer (not: "DevOps", "SRE", "Ops")
• Automation Engineer (not: "Automation", "Build Engineer", "CI/CD Engineer")
• Product Owner (not: "PO", "Product", "Product Manager")
• Scrum Master (not: "SM", "Scrum", "Process Manager", "Agile Coach")
• Documentation Specialist (not: "Docs", "Tech Writer")
• UX Expert (not: "UX", "UX Designer", "UI/UX")
• Accessibility Expert (not: "A11y", "Accessibility", "WCAG Expert")
• Agent Skill Engineer (not: "Skill Engineer", "Agent Engineer", "Prompt Engineer")
• Technical Architect (not: "Architect", "Enterprise Architect", "Solutions Architect")
• Security Architect (not: "Sec Arch", "AppSec Architect", "InfoSec")
• Cloud Architect (not: "Cloud Engineer", "Infrastructure Architect", "Platform Architect")

External Role References

• Code Reviewer: See superpowers:receiving-code-review (not editable here)

Reference Format

In markdown: **Tech Lead** or @role:tech-lead

In code comments: @role tech-lead or // Review: Tech Lead perspective needed

Role Selection Guide

When multiple roles seem applicable, use these criteria:

By Scope

Scope	Use These Roles
Single component	Senior Developer, Backend/Frontend Developer, QA
Cross-cutting	Tech Lead, Performance Engineer, DevOps, Automation
Enterprise-wide	Technical Architect, Security Architect, Cloud Architect

By Phase

Phase	Use These Roles
Design	Tech Lead, Technical Architect, Cloud Architect
Implementation	Senior Developer, Backend Developer, Frontend Developer
Review	QA Engineer, Security Reviewer, Documentation Specialist
Automation	Automation Engineer, DevOps Engineer

Overlapping Domains

• Tech Lead vs Technical Architect: Tech Lead for project-level decisions; Technical Architect for enterprise or cross-project concerns
• Security Reviewer vs Security Architect: Security Reviewer for code-level issues; Security Architect for compliance, threat modelling, or system-level security
• Senior Developer vs QA Engineer: Senior Developer for code quality; QA Engineer for test strategy and coverage
• Senior Developer vs Backend/Frontend Developer: Senior Developer for cross-cutting patterns and quality; Backend/Frontend Developer for stack-specific implementation
• DevOps Engineer vs Automation Engineer: DevOps for run-time operations and production; Automation Engineer for build-time automation and developer enablement

Validation

Role frontmatter is validated during:

• Pre-commit hooks: Format and syntax validation via prettier
• CI pipeline: Markdown linting via markdownlint-cli2
• Manual check: Run npm run lint to validate all role files

Required fields (name, description, model) are enforced by convention. Invalid frontmatter will cause YAML parsing errors when roles are loaded by agents.

Troubleshooting

Issue: Agent selects wrong role for task

• Check the description field includes specific trigger conditions
• Ensure overlapping roles have clear differentiation (see Role Selection Guide)
• Consider adding "use X instead" guidance for ambiguous cases

Issue: Model tier seems incorrect for role complexity

• Review the Choosing Model Tiers guidance above
• Use balanced as the default; only use reasoning for complex analysis
• Add escalation guidance in description if role may need higher tier

Issue: Frontmatter validation fails

• Ensure YAML syntax is correct (proper indentation, | for multiline)
• Check all required fields are present: name, description, model
• Run npm run format to auto-fix formatting issues

Issue: Multiple roles apply to a task

• Use scope criteria: single component vs cross-cutting vs enterprise
• Use phase criteria: design vs implementation vs review
• When still unclear, prefer the more specific role over general ones