SuperClaude/User-Guide/agents.md

SuperClaude Agents Guide 🤖

Overview

SuperClaude employs 13 specialized AI agents that automatically activate based on task context and keywords. The intelligent routing system analyzes your requests and coordinates the most relevant domain experts for optimal results.

Automatic Activation: Type /sc:implement "secure user login" and watch as the security-engineer, backend-architect, and frontend-architect agents coordinate automatically.

Intelligent Coordination: Multiple agents can work together on complex tasks, with each contributing their specialized expertise to different aspects of the problem.

🚀 Just Try These (No Agent Knowledge Required)

Automatic Agent Examples:

# Triggers: security-engineer + backend-architect
/sc:implement "JWT authentication with rate limiting"

# Triggers: frontend-architect + ux-designer
/sc:design "responsive dashboard with accessibility"

# Triggers: devops-architect + performance-engineer
/sc:troubleshoot "slow deployment pipeline"

# Triggers: qa-specialist + security-engineer
/sc:test "payment processing security"

Pattern Recognition Logic:

• Keywords: "auth", "security" → security-engineer
• File types: ".jsx", ".vue" → frontend-architect
• Context: API endpoints → backend-architect
• Complexity: Multi-domain tasks → Multiple agents

---

The SuperClaude Agent Team 👥

Architecture & System Design Agents 🏗️

system-architect 🏢

Expertise: Large-scale system design, microservices, distributed architectures Auto-Activation: "architecture", "microservices", "scalability", "system design" Capabilities: Service boundaries, data flow design, technology selection, scalability planning

Examples: Microservices architecture, event-driven systems, API gateway design, database sharding strategies

---

backend-architect ⚙️

Expertise: Reliable backend systems, APIs, data integrity, fault tolerance Auto-Activation: "API", "backend", "server", "database", "REST", "GraphQL" Capabilities: API design, database modeling, error handling, authentication, caching strategies

Examples: REST API architecture, database schema design, authentication flows, message queue implementation

---

frontend-architect 🎨

Expertise: Accessible UI design, modern frameworks, performance optimization Auto-Activation: "UI", "frontend", "React", "Vue", "component", "accessibility" Capabilities: Component architecture, state management, accessibility compliance, performance optimization

Examples: React component hierarchies, state management patterns, responsive design systems, accessibility implementations

---

devops-architect 🚀

Expertise: Infrastructure automation, CI/CD, deployment strategies, observability Auto-Activation: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring" Capabilities: Pipeline design, containerization, orchestration, monitoring setup, deployment strategies

Examples: CI/CD pipeline configuration, Docker containerization, Kubernetes deployments, monitoring dashboards

Quality & Analysis Agents 🔍

security-engineer 🔒

Expertise: Threat modeling, vulnerability assessment, security compliance Auto-Activation: "security", "auth", "vulnerability", "encryption", "compliance" Capabilities: Security audits, threat analysis, compliance validation, secure coding practices

Examples: Authentication systems, data encryption, vulnerability scanning, compliance reporting

---

performance-engineer ⚡

Expertise: Performance optimization, bottleneck identification, scalability tuning Auto-Activation: "performance", "slow", "optimization", "bottleneck", "latency" Capabilities: Performance profiling, optimization strategies, load testing, caching solutions Examples: Database query optimization, API response time improvement, memory leak detection, caching implementation

---

root-cause-analyst 🔍

Expertise: Systematic problem investigation, evidence-based analysis, hypothesis testing Auto-Activation: "bug", "issue", "problem", "debugging", "investigation" Capabilities: Error analysis, dependency tracking, systematic debugging, evidence collection

Examples: Complex bug investigation, system failure analysis, performance degradation diagnosis

---

quality-engineer ✅

Expertise: Quality assurance, testing strategies, edge case detection Auto-Activation: "test", "quality", "QA", "validation", "coverage" Capabilities: Test strategy design, edge case identification, quality metrics, validation frameworks

Examples: Test suite architecture, quality gate implementation, automated testing, compliance validation

---

refactoring-expert 🔧

Expertise: Code quality improvement, SOLID principles, technical debt reduction Auto-Activation: "refactor", "clean code", "technical debt", "SOLID", "maintainability" Capabilities: Code structure improvement, design pattern application, debt identification, clean code practices

Examples: Legacy code modernization, design pattern implementation, code smell elimination, architecture improvement

Specialized Development Agents 🎯

python-expert 🐍

Expertise: Production-ready Python development, modern frameworks, best practices Auto-Activation: ".py" files, "Python", "Django", "FastAPI", "Flask", "asyncio" Capabilities: Python architecture, framework selection, performance optimization, security practices

Examples: FastAPI applications, Django systems, async programming, Python packaging, data processing pipelines

---

requirements-analyst 📝

Expertise: Requirements discovery, specification development, stakeholder analysis Auto-Activation: "requirements", "specification", "PRD", "user story", "functional" Capabilities: Requirements elicitation, specification writing, stakeholder mapping, acceptance criteria

Examples: Product requirement documents, user story creation, functional specifications, acceptance criteria definition

Communication & Learning Agents 📚

technical-writer 📚

Expertise: Technical documentation, audience analysis, clear communication Auto-Activation: "documentation", "readme", "API docs", "user guide", "technical writing" Capabilities: Documentation architecture, audience targeting, clarity optimization, information design

Examples: API documentation, user guides, technical tutorials, architecture documentation

---

learning-guide 🎓

Expertise: Educational content design, progressive learning, mentorship Auto-Activation: "explain", "learn", "tutorial", "beginner", "teaching" Capabilities: Learning path design, concept explanation, skill progression, educational assessment

Examples: Programming tutorials, concept explanations, skill assessments, learning roadmaps

---

Agent Coordination & Integration 🤝

Agent Collaboration Patterns:

Full-Stack Development: frontend-architect + backend-architect + security-engineer Quality Assurance: quality-engineer + performance-engineer + security-engineer System Design: system-architect + devops-architect + performance-engineer Problem Solving: root-cause-analyst + performance-engineer + security-engineer

Multi-Domain Coordination: Complex projects automatically activate multiple agents based on scope and requirements. Agents coordinate through shared context and complementary expertise.

MCP Server Integration:

• Context7: Provides domain-specific patterns and documentation
• Sequential: Enables systematic multi-step reasoning
• Magic: Enhances UI/UX capabilities for frontend agents
• Playwright: Enables browser automation for testing agents
• Morphllm: Accelerates code transformation for refactoring agents
• Serena: Provides project memory and context for all agents

Command Integration: Each SuperClaude command automatically selects appropriate agents:

• /sc:implement → domain-specific architects (frontend, backend, security)
• /sc:analyze → quality-engineer + security-engineer + performance-engineer
• /sc:troubleshoot → root-cause-analyst + domain specialists
• /sc:improve → refactoring-expert + performance-engineer
• /sc:document → technical-writer + domain specialists

Quick Reference 📋

Agent	Domain	Key Triggers	Best For
system-architect	Architecture	"architecture", "microservices"	Large-scale design
backend-architect	Backend	"API", "server", "database"	Server-side systems
frontend-architect	Frontend	"UI", "React", "component"	User interfaces
devops-architect	Infrastructure	"deploy", "CI/CD", "Docker"	DevOps & deployment
security-engineer	Security	"security", "auth", "vulnerability"	Security & compliance
performance-engineer	Performance	"performance", "optimization"	Speed & efficiency
quality-engineer	Quality	"test", "quality", "validation"	Testing & QA
refactoring-expert	Code Quality	"refactor", "clean code"	Code improvement
root-cause-analyst	Debugging	"bug", "issue", "debugging"	Problem investigation
python-expert	Python	".py", "Python", "Django"	Python development
requirements-analyst	Analysis	"requirements", "PRD"	Requirements gathering
technical-writer	Documentation	"documentation", "API docs"	Technical writing
learning-guide	Education	"explain", "tutorial"	Teaching & learning

Most Useful Agent Combinations:

Web Application: frontend-architect + backend-architect + security-engineer API Development: backend-architect + security-engineer + technical-writer Legacy Modernization: refactoring-expert + system-architect + quality-engineer Security Audit: security-engineer + quality-engineer + root-cause-analyst Performance Optimization: performance-engineer + system-architect + devops-architect

Multi-Agent Workflow Examples:

# E-commerce platform (4 agents activate)
/sc:implement "secure payment processing with fraud detection"
# → backend-architect + security-engineer + quality-engineer + performance-engineer

# Learning platform (3 agents activate)
/sc:design "interactive coding tutorial system"
# → frontend-architect + learning-guide + technical-writer

Best Practices 💡

Getting Started (Simple Approach):

1. Start Simple: Just describe what you want - agents activate automatically
2. Trust the System: SuperClaude selects the right experts for your context
3. Learn from Patterns: Notice which agents activate for different tasks
4. Gradual Complexity: Add more detail to trigger additional specialist agents

Advanced Agent Control:

• Cross-Domain Projects: Combine keywords to trigger multiple agents
• Specific Expertise: Use domain-specific terminology for targeted activation
• Quality Focus: Include "security", "performance", "quality" for comprehensive coverage
• Learning Mode: Add "explain" or "tutorial" to include educational perspective

Common Usage Patterns:

New Project Startup:

/sc:brainstorm "fintech mobile app"
# → Activates: system-architect + frontend-architect + security-engineer

Existing Code Analysis:

/sc:analyze src/ --focus security
# → Activates: security-engineer + quality-engineer + refactoring-expert

Learning & Understanding:

/sc:explain "microservices architecture patterns"
# → Activates: system-architect + learning-guide + technical-writer

Performance Investigation:

/sc:troubleshoot "API response time > 2 seconds"
# → Activates: performance-engineer + root-cause-analyst + backend-architect

Quality Improvement:

/sc:improve legacy-code/ --focus maintainability
# → Activates: refactoring-expert + quality-engineer + technical-writer

---

Final Notes 📝

The Truth About Agent Usage:

SuperClaude agents activate automatically based on keywords and context - you don't need to manage them. The system is designed to be sophisticated under the hood while remaining simple to use.

Agent Knowledge Usefulness:

• Useful: Understanding why certain agents activate can help you craft better commands
• Useful: Knowing agent specialties helps you choose the right keywords and approaches
• Unnecessary: Manual agent selection or micromanagement - the system handles this
• Unnecessary: Memorizing all agent capabilities - the system routes intelligently

Simple Usage Approach:

1. Focus on Your Goal: Describe what you want to accomplish clearly
2. Use Natural Language: Include domain keywords naturally ("security", "performance", "UI")
3. Trust the System: Let SuperClaude activate appropriate agents automatically
4. Learn from Results: Notice which agents activate and why, but don't force it

---

Related Guides

Learning Progression:

🌱 Essential (Week 1)

• Quick Start Guide - Get up and running with basic commands
• Installation Guide - Setup and configuration
• Commands Guide - Master core commands that trigger agents

🌿 Recommended (Week 2-3)

• Behavioral Modes - Context optimization and agent coordination
• Examples Cookbook - Practical patterns and workflows
• Best Practices - Agent optimization strategies

🌳 Advanced (Month 2+)

• MCP Servers - Enhanced capabilities through server integration
• Session Management - Long-term workflows and persistence
• Technical Architecture - System understanding

🔧 Expert Development

• Contributing Code - Framework development
• Testing & Debugging - Quality procedures

---

Your SuperClaude Agent Journey:

SuperClaude's agent system represents the best of both worlds: sophisticated coordination happening automatically behind a simple, intuitive interface. You get the benefit of 13 specialized experts without the complexity of managing them.

The Magic is in the Simplicity:

• Type /sc:implement "secure user login" and watch security engineers, backend architects, and frontend specialists coordinate seamlessly
• No agent configuration, no manual routing, no complex setup - just describe your goal and let the system work
• The more you use SuperClaude, the better you'll understand the patterns, but you never need to micromanage the agents

Start Simple, Stay Simple: Begin with basic commands and let complexity emerge naturally. SuperClaude handles the orchestration so you can focus on building great software. The agent system grows with your needs while maintaining the same straightforward interface.

🚀 Ready to experience intelligent agent coordination? Try /sc:brainstorm and watch the magic happen.