SuperClaude/Guides/agents-guide.md

# SuperClaude Agents Guide 🤖

## Overview

The SuperClaude Framework features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents provide expert-level assistance across all aspects of software development, from architecture design to documentation writing.

**The simple truth**: You don't need to pick agents or memorize what they do. SuperClaude automatically brings in the right experts for each situation!

**Here's what actually happens:**
- You type `/analyze auth.js` → Security engineer automatically jumps in 🛡️
- You work on React components → Frontend architect often takes over 🎨  
- You debug performance issues → Performance engineer often helps ⚡
- You write documentation → Technical writer usually helps out ✍️

**It's like having a smart team** that knows when to jump in and help, without you managing who does what.

## 🚀 Just Try These (No Agent Knowledge Required)

```bash
# These automatically activate the right experts:
/analyze payment-system/         # → Security + backend experts auto-activate
/build react-app/               # → Frontend architect takes over  
/improve slow-queries.sql       # → Performance engineer jumps in
/troubleshoot "auth failing"    # → Root cause analyst + security expert coordinate
/brainstorm "task manager app"  # → Requirements analyst guides discovery
```

**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. See [Examples Cookbook](examples-cookbook.md) for many more examples like these.

---

## The SuperClaude Agent Team 👥

### Architecture & System Design Agents 🏗️

#### 🏗️ `system-architect` - Large-Scale Design Expert
**What they do**: Design scalable system architecture with focus on maintainability and long-term technical decisions

**Auto-activation triggers**:
- Keywords: "architecture", "design", "scalability", "system", "patterns", "microservices"
- Large-scale system design and architectural decisions
- Cross-system integration and design pattern implementation

**Specialized capabilities**:
- **System Design**: Component boundaries, interfaces, and interaction patterns
- **Scalability Architecture**: Horizontal scaling strategies, bottleneck identification
- **Dependency Management**: Coupling analysis, dependency mapping, risk assessment
- **Architectural Patterns**: Microservices, CQRS, event sourcing, domain-driven design
- **Technology Strategy**: Tool selection based on long-term impact and ecosystem fit

**Example use cases**:
```bash
/design microservices-architecture     # → System architecture and service design
/analyze --focus architecture system/  # → Architectural review and improvement
/plan scalability-improvements         # → Scaling strategy and implementation
```

---

#### ⚙️ `backend-architect` - Reliable Backend Systems Expert
**What they do**: Design reliable backend systems with focus on data integrity, security, and fault tolerance

**Auto-activation triggers**:
- Backend system design and API development requests
- Database design and optimization needs
- Security, reliability, and performance requirements
- Server-side architecture and scalability challenges

**Specialized capabilities**:
- **API Design**: RESTful services, GraphQL, proper error handling, validation
- **Database Architecture**: Schema design, ACID compliance, query optimization
- **Security Implementation**: Authentication, authorization, encryption, audit trails
- **System Reliability**: Circuit breakers, graceful degradation, monitoring
- **Performance Optimization**: Caching strategies, connection pooling, scaling patterns

**Example use cases**:
```bash
/design user-management-api        # → Reliable API with proper auth
/optimize database-queries/        # → Performance tuning and indexing
/implement payment-processing      # → Secure, reliable payment system
```

---

#### 🎨 `frontend-architect` - Accessible UI Systems Expert
**What they do**: Create accessible, performant user interfaces with focus on user experience and modern frameworks

**Auto-activation triggers**:
- UI component development and design system requests
- Accessibility compliance and WCAG implementation needs
- Performance optimization and Core Web Vitals improvements
- Responsive design and mobile-first development requirements

**Specialized capabilities**:
- **Accessibility**: WCAG 2.1 AA compliance, keyboard navigation, screen reader support
- **Performance**: Core Web Vitals, bundle optimization, loading strategies
- **Responsive Design**: Mobile-first approach, flexible layouts, device adaptation
- **Component Architecture**: Reusable systems, design tokens, maintainable patterns
- **Modern Frameworks**: React, Vue, Angular with best practices and optimization

**Example use cases**:
```bash
/build dashboard-components/       # → Accessible React components
/improve --focus accessibility ui/ # → WCAG compliance and optimization
/optimize bundle-performance       # → Core Web Vitals improvement
```

---

#### 🚀 `devops-architect` - Infrastructure Automation Expert
**What they do**: Automate infrastructure and deployment processes with focus on reliability and observability

**Auto-activation triggers**:
- Infrastructure automation and CI/CD pipeline development needs
- Deployment strategy and zero-downtime release requirements
- Monitoring, observability, and reliability engineering requests
- Infrastructure as code and configuration management tasks

**Specialized capabilities**:
- **CI/CD Pipelines**: Automated testing, deployment strategies, rollback capabilities
- **Infrastructure as Code**: Version-controlled, reproducible infrastructure management
- **Observability**: Comprehensive monitoring, logging, alerting, and metrics
- **Container Orchestration**: Kubernetes, Docker, microservices architecture
- **Cloud Automation**: Multi-cloud strategies, resource optimization, compliance

**Example use cases**:
```bash
/deploy production-app             # → Zero-downtime deployment pipeline
/build monitoring-stack           # → Comprehensive observability setup
/secure infrastructure/           # → Security hardening and compliance
```

### Quality & Analysis Agents 🔍

#### 🛡️ `security-engineer` - Threat Modeling Expert
**What they do**: Identify security vulnerabilities and ensure compliance with security standards and best practices

**Auto-activation triggers**:
- Security vulnerability assessment and code audit requests
- Compliance verification and security standards implementation needs
- Threat modeling and attack vector analysis requirements
- Authentication, authorization, and data protection implementation reviews

**Specialized capabilities**:
- **Vulnerability Assessment**: OWASP Top 10, CWE patterns, code security analysis
- **Threat Modeling**: Attack vector identification, risk assessment, security controls
- **Compliance Verification**: Industry standards, regulatory requirements, security frameworks
- **Authentication & Authorization**: Identity management, access controls, privilege escalation
- **Data Protection**: Encryption implementation, secure data handling, privacy compliance

**Example use cases**:
```bash
/scan --focus security auth-system/ # → Comprehensive security audit
/analyze payment-flow --security     # → Threat modeling and risk assessment
/improve --fix vulnerabilities api/  # → Security hardening and fixes
```

---

#### ⚡ `performance-engineer` - Bottleneck Detection Expert
**What they do**: Optimize system performance through measurement-driven analysis and bottleneck elimination

**Auto-activation triggers**:
- Performance optimization requests and bottleneck resolution needs
- Speed and efficiency improvement requirements
- Load time, response time, and resource usage optimization requests
- Core Web Vitals and user experience performance issues

**Specialized capabilities**:
- **Frontend Performance**: Core Web Vitals, bundle optimization, asset delivery
- **Backend Performance**: API response times, query optimization, caching strategies
- **Resource Optimization**: Memory usage, CPU efficiency, network performance
- **Critical Path Analysis**: User journey bottlenecks, load time optimization
- **Benchmarking**: Before/after metrics validation, performance regression detection

**Example use cases**:
```bash
/analyze --focus performance slow-api/ # → Bottleneck identification and fixes
/optimize database-queries/            # → Query performance tuning
/benchmark application-performance     # → Load testing and capacity planning
```

---

#### 🔍 `root-cause-analyst` - Systematic Investigation Expert
**What they do**: Systematically investigate complex problems to identify underlying causes through evidence-based analysis and hypothesis testing

**Auto-activation triggers**:
- Complex debugging scenarios requiring systematic investigation and evidence-based analysis
- Multi-component failure analysis and pattern recognition needs
- Problem investigation requiring hypothesis testing and verification
- Root cause identification for recurring issues and system failures

**Specialized capabilities**:
- **Evidence Collection**: Log analysis, error pattern recognition, system behavior investigation
- **Hypothesis Formation**: Multiple theory development, assumption validation, systematic testing approach
- **Pattern Analysis**: Correlation identification, symptom mapping, system behavior tracking
- **Investigation Documentation**: Evidence preservation, timeline reconstruction, conclusion validation
- **Problem Resolution**: Clear remediation path definition, prevention strategy development

**Example use cases**:
```bash
/troubleshoot "payment processing fails randomly" # → Systematic investigation
/analyze mysterious-bug/                          # → Evidence-based debugging
/investigate system-outage-logs/                  # → Root cause analysis
```

---

#### 🧪 `quality-engineer` - Quality Assurance Expert
**What they do**: Ensure software quality through comprehensive testing strategies and systematic edge case detection

**Auto-activation triggers**:
- Testing strategy design and comprehensive test plan development requests
- Quality assurance process implementation and edge case identification needs
- Test coverage analysis and risk-based testing prioritization requirements
- Automated testing framework setup and integration testing strategy development

**Specialized capabilities**:
- **Test Strategy Design**: Comprehensive test planning, risk assessment, coverage analysis
- **Edge Case Detection**: Boundary conditions, failure scenarios, negative testing
- **Test Automation**: Framework selection, CI/CD integration, automated test development
- **Quality Metrics**: Coverage analysis, defect tracking, quality risk assessment
- **Testing Methodologies**: Unit, integration, performance, security, and usability testing

**Example use cases**:
```bash
/test --comprehensive user-service/     # → Full testing strategy and implementation
/validate --quality critical-features/  # → Quality gate implementation
/analyze --focus testing legacy-code/   # → Testing strategy for existing code
```

---

#### 🔄 `refactoring-expert` - Clean Code Specialist
**What they do**: Improve code quality and reduce technical debt through systematic refactoring and clean code principles

**Auto-activation triggers**:
- Code complexity reduction and technical debt elimination requests
- SOLID principles implementation and design pattern application needs
- Code quality improvement and maintainability enhancement requirements
- Refactoring methodology and clean code principle application requests

**Specialized capabilities**:
- **Code Simplification**: Complexity reduction, readability improvement, cognitive load minimization
- **Technical Debt Reduction**: Duplication elimination, anti-pattern removal, quality metric improvement
- **Pattern Application**: SOLID principles, design patterns, refactoring catalog techniques
- **Quality Metrics**: Cyclomatic complexity, maintainability index, code duplication measurement
- **Safe Transformation**: Behavior preservation, incremental changes, comprehensive testing validation

**Example use cases**:
```bash
/improve --focus quality legacy-module/  # → Comprehensive code quality improvement
/refactor --safe complex-functions/      # → Safe refactoring with test coverage
/cleanup --technical-debt codebase/      # → Systematic technical debt reduction
```

### Specialized Development Agents 🎯

#### 🐍 `python-expert` - Master Python Specialist
**What they do**: Deliver production-ready, secure, high-performance Python code following SOLID principles and modern best practices

**Auto-activation triggers**:
- Python development requests requiring production-quality code and architecture decisions
- Code review and optimization needs for performance and security enhancement
- Testing strategy implementation and comprehensive coverage requirements
- Modern Python tooling setup and best practices implementation

**Specialized capabilities**:
- **Production Quality**: Security-first development, comprehensive testing, error handling, performance optimization
- **Modern Architecture**: SOLID principles, clean architecture, dependency injection, separation of concerns
- **Testing Excellence**: TDD approach, unit/integration/property-based testing, 95%+ coverage, mutation testing
- **Security Implementation**: Input validation, OWASP compliance, secure coding practices, vulnerability prevention
- **Performance Engineering**: Profiling-based optimization, async programming, efficient algorithms, memory management

**Example use cases**:
```bash
/build python-api --focus security     # → Production-ready FastAPI with security
/improve legacy-python/ --focus quality # → Refactor to SOLID principles
/test python-service/ --comprehensive   # → Full test suite with coverage
```

---

#### 📋 `requirements-analyst` - Requirements Discovery Expert
**What they do**: Transform ambiguous project ideas into concrete specifications through systematic requirements discovery and structured analysis

**Auto-activation triggers**:
- Ambiguous project requests requiring requirements clarification and specification development
- PRD creation and formal project documentation needs from conceptual ideas
- Stakeholder analysis and user story development requirements
- Project scope definition and success criteria establishment requests

**Specialized capabilities**:
- **Requirements Discovery**: Systematic questioning, stakeholder analysis, user need identification
- **Specification Development**: PRD creation, user story writing, acceptance criteria definition
- **Scope Definition**: Boundary setting, constraint identification, feasibility validation
- **Success Metrics**: Measurable outcome definition, KPI establishment, acceptance condition setting
- **Stakeholder Alignment**: Perspective integration, conflict resolution, consensus building

**Example use cases**:
```bash
/brainstorm "task management app"  # → Interactive discovery session
# → Automatic handoff to requirements analyst
# → PRD generation with structured requirements
```

### Communication & Learning Agents 📚

#### ✍️ `technical-writer` - Documentation Excellence Expert
**What they do**: Create clear, comprehensive technical documentation tailored to specific audiences with focus on usability and accessibility

**Auto-activation triggers**:
- API documentation and technical specification creation requests
- User guide and tutorial development needs for technical products
- Documentation improvement and accessibility enhancement requirements
- Technical content structuring and information architecture development

**Specialized capabilities**:
- **Audience Analysis**: User skill level assessment, goal identification, context understanding
- **Content Structure**: Information architecture, navigation design, logical flow development
- **Clear Communication**: Plain language usage, technical precision, concept explanation
- **Practical Examples**: Working code samples, step-by-step procedures, real-world scenarios
- **Accessibility Design**: WCAG compliance, screen reader compatibility, inclusive language

**Example use cases**:
```bash
/document api-endpoints/               # → Comprehensive API documentation
/write user-guide --audience beginner  # → User-friendly tutorial and guides
/improve --docs project-documentation/ # → Documentation quality enhancement
```

---

#### 👨‍🏫 `learning-guide` - Learning & Mentorship Expert
**What they do**: Teach programming concepts and explain code with focus on understanding through progressive learning and practical examples

**Auto-activation triggers**:
- Code explanation and programming concept education requests
- Tutorial creation and progressive learning path development needs
- Algorithm breakdown and step-by-step analysis requirements
- Educational content design and skill development guidance requests

**Specialized capabilities**:
- **Concept Explanation**: Clear breakdowns, practical examples, real-world application demonstration
- **Progressive Learning**: Step-by-step skill building, prerequisite mapping, difficulty progression
- **Educational Examples**: Working code demonstrations, variation exercises, practical implementation
- **Understanding Verification**: Knowledge assessment, skill application, comprehension validation
- **Learning Path Design**: Structured progression, milestone identification, skill development tracking

**Example use cases**:
```bash
/explain complex-algorithm --educational    # → Step-by-step learning guide
/teach react-patterns --beginner           # → Progressive React tutorial
/mentor junior-developer --focus testing   # → Personalized learning guidance
```

---

## Agent Coordination & Integration 🤝

### Automatic Agent Collaboration

Agents often work together automatically. Here are common collaboration patterns:

#### **Multi-Domain Projects**
```bash
/build full-stack-app/
# Auto-coordinates: backend-architect + frontend-architect + system-architect
```

#### **Security-Focused Development**
```bash
/analyze --focus security payment-system/
# Auto-coordinates: security-engineer + backend-architect + performance-engineer
```

#### **Quality Improvement**
```bash
/improve --focus quality legacy-codebase/
# Auto-coordinates: refactoring-expert + quality-engineer + system-architect
```

### Integration with MCP Servers

Each agent leverages specific MCP servers for enhanced capabilities:

- **Context7**: Documentation patterns, framework best practices, compliance standards
- **Sequential**: Complex analysis, systematic problem solving, architectural planning
- **Magic**: UI component generation, design system integration, modern frameworks
- **Playwright**: Cross-browser testing, visual validation, performance testing
- **Morphllm**: Intelligent code transformations, pattern application, optimization
- **Serena**: Memory operations, cross-reference management, symbol-level analysis

### Integration with Commands

Agents seamlessly integrate with SuperClaude's command system:

```bash
# Commands automatically select appropriate agents
/analyze → root-cause-analyst or system-architect (context-dependent)
/build → frontend-architect, backend-architect, or python-expert
/test → quality-engineer with domain-specific coordination
/brainstorm → requirements-analyst for requirements discovery
/document → technical-writer with audience-appropriate formatting
```

## Quick Reference 📋

### Agent Selection Cheat Sheet

| Agent | Best For | Auto-Activates On | Example Use |
|-------|----------|-------------------|-------------|
| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design |
| ⚙️ backend-architect | Backend systems | APIs, databases, services | Reliable backend systems |
| 🎨 frontend-architect | User interfaces | UI components, accessibility | Accessible web interfaces |
| 🚀 devops-architect | Infrastructure | CI/CD, deployment, monitoring | Deployment automation |
| 🛡️ security-engineer | Security analysis | Security keywords, auth code | Vulnerability assessment |
| ⚡ performance-engineer | Performance tuning | "slow", "bottleneck", profiling | System optimization |
| 🔍 root-cause-analyst | Problem solving | "debug", "investigate", bugs | Complex bug investigation |
| 🧪 quality-engineer | Quality assurance | Testing, validation, QA | Comprehensive test strategy |
| 🔄 refactoring-expert | Code improvement | Refactoring, cleanup, quality | Clean code practices |
| 🐍 python-expert | Python development | .py files, Python frameworks | Production Python APIs |
| 📋 requirements-analyst | Requirements discovery | Ambiguous projects, brainstorming | Project specification |
| ✍️ technical-writer | Documentation | Documentation requests | API documentation |
| 👨‍🏫 learning-guide | Learning & teaching | "explain", "learn", tutorials | Educational content |

### Most Useful Agent Combinations

**Full-Stack Development**:
```bash
# Automatically coordinates backend + frontend + architecture
/build modern-web-app/
```

**Security & Performance Review**:
```bash
# Coordinates security + performance + quality analysis
/analyze --comprehensive production-system/
```

**Learning & Development**:
```bash
# Coordinates learning guide + technical writer + domain expert
/explain complex-system --educational
```

**Project Discovery to Implementation**:
```bash
# Requirements → Architecture → Implementation
/brainstorm "e-commerce platform"
# → Automatic handoff through agent coordination
```

## Best Practices 💡

### Getting Started (The Simple Way)
1. **Just use normal commands** - Agents auto-activate based on your needs
2. **Trust the automation** - SuperClaude usually picks better experts than manual selection
3. **Focus on your work** - Not on managing which agent helps you
4. **Let coordination happen** - Multiple agents work together automatically

### Advanced Usage (When You Want Control)
1. **Manual agent selection** - Use agent names in commands when you want specific expertise
2. **Cross-domain perspectives** - Ask security agents about frontend code for different viewpoints
3. **Learning mode** - Use learning-guide for explanation-focused assistance
4. **Quality focus** - Combine quality-engineer with domain experts for comprehensive quality

### Common Patterns

**For New Projects**:
```bash
/brainstorm "your project idea"  # → Requirements discovery
# → Automatic PRD generation and handoff
# → Ready for implementation workflow
```

**For Existing Code**:
```bash
/analyze existing-system/        # → Appropriate domain expert auto-selected
/improve --focus quality code/   # → Quality-focused agent coordination
/secure legacy-application/      # → Security-focused analysis and hardening
```

**For Learning**:
```bash
/explain complex-concept --educational  # → Learning guide with domain expert
/document api/ --audience beginner     # → Technical writer with appropriate level
```

---

## Final Notes 📝

**The real truth about agents** 💯:
- **Auto-activation works remarkably well** - Usually better than trying to pick experts yourself
- **You can completely ignore agent details** and still get excellent expert assistance
- **Agents exist to help you** - Not to create complexity you need to manage
- **Learning happens naturally** through use, not through studying agent descriptions

**Don't feel overwhelmed by the team** 🧘‍♂️:
- You don't need to know what each agent does
- SuperClaude handles expert selection intelligently
- The detailed descriptions above are for curiosity, not necessity
- Focus on your work - the right experts will show up when needed

**When you might want to know about agents**:
- **Curiosity** - "What would a security expert think about this frontend code?"
- **Learning** - "How would different experts approach this problem?"
- **Specialization** - "I specifically need Python architecture expertise"
- **Quality focus** - "I want comprehensive quality analysis from multiple angles"

**Keep it simple** 🎯:
- Use normal commands like `/analyze some-code/` and `/build my-app/`
- Let the right experts automatically show up
- Agent coordination is available when you want it, not because you need it
- Focus on building great software - we'll handle the expertise coordination

---

## Related Guides

**🚀 Getting Started (Essential)**
- [SuperClaude User Guide](superclaude-user-guide.md) - Framework overview and philosophy
- [Examples Cookbook](examples-cookbook.md) - See agents in action with real examples

**🛠️ Working with Agents (Recommended)**
- [Commands Guide](commands-guide.md) - Commands that activate specific agents
- [Behavioral Modes Guide](behavioral-modes-guide.md) - How agents work within different modes
- [Session Management Guide](session-management.md) - Agent coordination across sessions

**⚙️ Control and Optimization (Advanced)**
- [Flags Guide](flags-guide.md) - Manual agent control with --agent flags
- [Best Practices Guide](best-practices.md) - Proven patterns for agent coordination
- [Technical Architecture Guide](technical-architecture.md) - Agent system implementation

**🔧 When Things Go Wrong**
- [Troubleshooting Guide](troubleshooting-guide.md) - Agent activation and coordination issues

**📖 Recommended Learning Path:**
1. [Examples Cookbook](examples-cookbook.md) - See auto-activation in action
2. [Commands Guide](commands-guide.md) - Understand agent triggers
3. [Best Practices Guide](best-practices.md) - Master agent coordination patterns

---

*Behind this sophisticated team of 13 specialists, the SuperClaude Framework remains simple to use. Just start coding and the right experts show up when needed! 🚀*