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)

# 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 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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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

/build full-stack-app/
# Auto-coordinates: backend-architect + frontend-architect + system-architect

Security-Focused Development

/analyze --focus security payment-system/
# Auto-coordinates: security-engineer + backend-architect + performance-engineer

Quality Improvement

/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:

# 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:

# Automatically coordinates backend + frontend + architecture
/build modern-web-app/

Security & Performance Review:

# Coordinates security + performance + quality analysis
/analyze --comprehensive production-system/

Learning & Development:

# Coordinates learning guide + technical writer + domain expert
/explain complex-system --educational

Project Discovery to Implementation:

# 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:

/brainstorm "your project idea"  # → Requirements discovery
# → Automatic PRD generation and handoff
# → Ready for implementation workflow

For Existing Code:

/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:

/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 - Framework overview and philosophy
• Examples Cookbook - See agents in action with real examples

🛠️ Working with Agents (Recommended)

• Commands Guide - Commands that activate specific agents
• Behavioral Modes Guide - How agents work within different modes
• Session Management Guide - Agent coordination across sessions

⚙️ Control and Optimization (Advanced)

• Flags Guide - Manual agent control with --agent flags
• Best Practices Guide - Proven patterns for agent coordination
• Technical Architecture Guide - Agent system implementation

🔧 When Things Go Wrong

• Troubleshooting Guide - Agent activation and coordination issues

📖 Recommended Learning Path:

1. Examples Cookbook - See auto-activation in action
2. Commands Guide - Understand agent triggers
3. Best Practices Guide - 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! 🚀