mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Consolidate documentation: Extract valuable content from Docs/ into Guides/
- Added Core Philosophy section from Docs/commands-guide.md to Guides/ - Added Command Flags & Options section with comprehensive flag documentation - Added Expert Activation section with complete technical specialists list - Added Command Relationships section showing workflow patterns - Removed Docs/ directory to eliminate duplication - Guides/ now serves as single source of truth for all documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
@@ -1,641 +0,0 @@
|
||||
# SuperClaude Agents Guide 🤖
|
||||
|
||||
## Overview
|
||||
|
||||
SuperClaude V4 Beta features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents replace the previous persona system with more advanced, focused capabilities that provide expert-level assistance across all aspects of software development.
|
||||
|
||||
**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 auditor automatically jumps in 🛡️
|
||||
- You work on React components → Frontend specialist often takes over 🎨
|
||||
- You debug performance issues → Performance optimizer 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:
|
||||
/sc:analyze payment-system/ # → Security + backend experts auto-activate
|
||||
/sc:build react-app/ # → Frontend specialist takes over
|
||||
/sc:improve slow-queries.sql # → Performance optimizer jumps in
|
||||
/sc:troubleshoot "auth failing" # → Root cause analyzer + security expert coordinate
|
||||
/sc:brainstorm "task manager app" # → Brainstorm-PRD agent guides discovery
|
||||
```
|
||||
|
||||
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help.
|
||||
|
||||
---
|
||||
|
||||
## The SuperClaude Agent Team 👥
|
||||
|
||||
### Core Development Agents 🔧
|
||||
|
||||
#### 🐍 `python-ultimate-expert` - Master Python Architect
|
||||
**What they do**: Production-ready Python development with SOLID principles, clean architecture, and comprehensive testing
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Python file detection (.py, requirements.txt, pyproject.toml)
|
||||
- Keywords: "python", "django", "fastapi", "flask", "asyncio"
|
||||
- Python-specific patterns and frameworks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Production Standards**: SOLID principles, clean architecture, domain-driven design
|
||||
- **Testing Excellence**: TDD with 95%+ coverage, pytest, property-based testing
|
||||
- **Security First**: OWASP compliance, input validation, secrets management
|
||||
- **Performance Optimization**: Profiling, async programming, memory management
|
||||
- **Modern Tooling**: uv/poetry, black, ruff, mypy, pre-commit hooks
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:build python-api --focus security # → Production-ready FastAPI with security
|
||||
/sc:improve legacy-python/ --focus quality # → Refactor to SOLID principles
|
||||
/sc:test python-service/ --comprehensive # → Full test suite with coverage
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: Python framework documentation and best practices
|
||||
- **Sequential**: Complex architecture analysis and system design
|
||||
- **Magic**: Python web framework UI components
|
||||
|
||||
---
|
||||
|
||||
#### ⚙️ `backend-engineer` - Reliable Systems Specialist
|
||||
**What they do**: Server-side development, APIs, databases, and reliability engineering
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "API", "database", "server", "microservices", "reliability"
|
||||
- Backend file patterns (server.js, app.py, database schemas)
|
||||
- Infrastructure and service-related tasks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Reliability First**: 99.9% uptime targets, fault tolerance, graceful degradation
|
||||
- **API Excellence**: RESTful design, GraphQL, comprehensive validation
|
||||
- **Database Mastery**: Schema design, query optimization, ACID compliance
|
||||
- **Security Implementation**: Authentication, authorization, zero trust architecture
|
||||
- **Observable Systems**: Structured logging, monitoring, alerting
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: 99.9% uptime with zero data loss tolerance
|
||||
- Secondary: <200ms API response time, comprehensive error handling
|
||||
- Success: Fault-tolerant systems meeting all reliability requirements
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:design user-management-api # → Reliable API with proper auth
|
||||
/sc:optimize database-queries/ # → Performance tuning and indexing
|
||||
/sc:implement payment-processing # → Secure, reliable payment system
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: Backend framework patterns and database documentation
|
||||
- **Sequential**: System architecture analysis and reliability planning
|
||||
- **Serena**: Cross-service dependency analysis and integration testing
|
||||
|
||||
---
|
||||
|
||||
#### 🎨 `frontend-specialist` - Accessible UI Expert
|
||||
**What they do**: User interface development with focus on accessibility, performance, and user experience
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "component", "responsive", "accessibility", "UI", "UX", "react", "vue"
|
||||
- Frontend file patterns (.jsx, .vue, .component.ts, CSS files)
|
||||
- User interface and design-related tasks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Accessibility by Default**: WCAG 2.1 AA compliance, screen reader support
|
||||
- **Performance Budget**: Core Web Vitals optimization, bundle size management
|
||||
- **Responsive Design**: Mobile-first approach, progressive enhancement
|
||||
- **Modern Frameworks**: React, Vue, Angular with best practices
|
||||
- **Design Systems**: Component libraries, design tokens, consistent patterns
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: WCAG 2.1 AA compliance (100%) with Core Web Vitals in green zone
|
||||
- Secondary: <3s load time on 3G networks, zero accessibility errors
|
||||
- Success: Accessible, performant UI meeting all compliance standards
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:build dashboard-components/ # → Accessible React components
|
||||
/sc:improve --focus accessibility ui/ # → WCAG compliance and optimization
|
||||
/sc:optimize bundle-performance # → Core Web Vitals improvement
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Magic**: Advanced UI component generation and design system integration
|
||||
- **Context7**: Frontend framework documentation and accessibility patterns
|
||||
- **Playwright**: Cross-browser testing and visual regression detection
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 `devops-engineer` - Infrastructure Automation Expert
|
||||
**What they do**: Infrastructure automation, deployment pipelines, monitoring, and reliability engineering
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "deploy", "infrastructure", "CI/CD", "docker", "kubernetes", "monitoring"
|
||||
- DevOps file patterns (Dockerfile, docker-compose.yml, .github/workflows)
|
||||
- Infrastructure and deployment-related tasks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Infrastructure as Code**: Terraform, CloudFormation, automated provisioning
|
||||
- **CI/CD Excellence**: GitHub Actions, automated testing, deployment pipelines
|
||||
- **Container Orchestration**: Docker, Kubernetes, microservices deployment
|
||||
- **Monitoring & Observability**: Logging, metrics, alerting, performance tracking
|
||||
- **Security Operations**: Security scanning, compliance, vulnerability management
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Zero-downtime deployments with automated rollback capability
|
||||
- Secondary: Infrastructure as code, comprehensive monitoring coverage
|
||||
- Success: Fully automated, observable, secure deployment infrastructure
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:deploy production-app # → Zero-downtime deployment pipeline
|
||||
/sc:build monitoring-stack # → Comprehensive observability setup
|
||||
/sc:secure infrastructure/ # → Security hardening and compliance
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: DevOps tools documentation and best practices
|
||||
- **Sequential**: Infrastructure architecture analysis and optimization
|
||||
- **Playwright**: Deployment validation and smoke testing
|
||||
|
||||
### Analysis & Quality Agents 🔍
|
||||
|
||||
#### 🛡️ `security-auditor` - Threat Modeling Expert
|
||||
**What they do**: Security vulnerability identification, threat modeling, and compliance verification
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "security", "vulnerability", "auth", "compliance", "penetration", "audit"
|
||||
- Security-sensitive code patterns (authentication, data handling, API endpoints)
|
||||
- Security assessment and review requests
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Vulnerability Assessment**: OWASP Top 10, CWE compliance, penetration testing mindset
|
||||
- **Threat Modeling**: Attack vector analysis, security risk assessment
|
||||
- **Compliance Verification**: Industry standards, regulatory requirements
|
||||
- **Security Architecture**: Zero trust principles, defense in depth
|
||||
- **Remediation Guidance**: Specific fixes with security rationale
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Zero critical vulnerabilities in production with OWASP Top 10 compliance
|
||||
- Secondary: All findings include remediation steps, clear severity classifications
|
||||
- Success: Complete security assessment with actionable remediation plan
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:scan --focus security auth-system/ # → Comprehensive security audit
|
||||
/sc:analyze payment-flow --security # → Threat modeling and risk assessment
|
||||
/sc:improve --fix vulnerabilities api/ # → Security hardening and fixes
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: Security framework documentation and compliance standards
|
||||
- **Sequential**: Complex threat modeling and vulnerability chain analysis
|
||||
- **Playwright**: Security testing and penetration validation
|
||||
|
||||
---
|
||||
|
||||
#### ⚡ `performance-optimizer` - Bottleneck Detection Expert
|
||||
**What they do**: Performance analysis, optimization, and bottleneck identification across all system layers
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "performance", "optimization", "slow", "bottleneck", "latency", "memory"
|
||||
- Performance-related issues and optimization requests
|
||||
- System profiling and benchmarking tasks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Bottleneck Identification**: Systematic performance profiling and analysis
|
||||
- **Optimization Strategy**: Database queries, application code, infrastructure tuning
|
||||
- **Performance Monitoring**: Metrics collection, alerting, continuous optimization
|
||||
- **Load Testing**: Capacity planning, stress testing, scalability analysis
|
||||
- **Resource Management**: Memory optimization, CPU utilization, I/O efficiency
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Measurable performance improvements with baseline metrics
|
||||
- Secondary: Comprehensive profiling, optimization rationale documentation
|
||||
- Success: Performance targets met with sustainable optimization strategies
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:analyze --focus performance slow-api/ # → Bottleneck identification and fixes
|
||||
/sc:optimize database-queries/ # → Query performance tuning
|
||||
/sc:benchmark application-performance # → Load testing and capacity planning
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Sequential**: Complex performance analysis and systematic optimization
|
||||
- **Context7**: Performance optimization patterns and best practices
|
||||
- **Playwright**: Performance testing and real-world load simulation
|
||||
|
||||
---
|
||||
|
||||
#### 🔍 `root-cause-analyzer` - Systematic Investigation Expert
|
||||
**What they do**: Debugging, root cause analysis, and evidence-based problem solving
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "debug", "investigate", "troubleshoot", "root cause", "analyze", "broken"
|
||||
- Bug reports, system failures, and complex problem investigation
|
||||
- Unknown system behavior and mysterious issues
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Systematic Investigation**: Evidence collection, hypothesis testing, pattern analysis
|
||||
- **Debug Methodology**: Step-by-step problem isolation and reproduction
|
||||
- **Root Cause Identification**: Deep analysis beyond surface symptoms
|
||||
- **Solution Validation**: Testing fixes and preventing regression
|
||||
- **Knowledge Transfer**: Documenting findings and prevention strategies
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Evidence-based conclusions with reproducible findings
|
||||
- Secondary: Systematic investigation methodology, complete analysis
|
||||
- Success: Root cause identified with validated solution and prevention
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:troubleshoot "payment processing fails randomly" # → Systematic investigation
|
||||
/sc:analyze mysterious-bug/ # → Evidence-based debugging
|
||||
/sc:investigate system-outage-logs/ # → Root cause analysis
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Sequential**: Complex problem decomposition and systematic analysis
|
||||
- **Serena**: Code analysis and symbol-level investigation
|
||||
- **Context7**: Debugging patterns and troubleshooting methodologies
|
||||
|
||||
---
|
||||
|
||||
#### 🧪 `qa-specialist` - Quality Assurance Expert
|
||||
**What they do**: Testing strategy, quality gates, edge case detection, and comprehensive validation
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "test", "quality", "validation", "QA", "edge case", "coverage"
|
||||
- Testing-related tasks and quality assurance requests
|
||||
- Quality gate implementation and validation processes
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Testing Strategy**: Comprehensive test planning, risk-based testing
|
||||
- **Quality Assurance**: Edge case identification, failure mode analysis
|
||||
- **Test Automation**: Unit, integration, and end-to-end testing frameworks
|
||||
- **Quality Gates**: Automated quality validation and compliance checking
|
||||
- **Risk Assessment**: Quality risk analysis and mitigation strategies
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Comprehensive test coverage with edge case validation
|
||||
- Secondary: Automated quality gates, risk-based testing priorities
|
||||
- Success: Quality assurance processes preventing defects in production
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:test --comprehensive user-service/ # → Full testing strategy and implementation
|
||||
/sc:validate --quality critical-features/ # → Quality gate implementation
|
||||
/sc:analyze --focus testing legacy-code/ # → Testing strategy for existing code
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Playwright**: End-to-end testing and cross-browser validation
|
||||
- **Sequential**: Complex testing strategy and quality analysis
|
||||
- **Context7**: Testing framework documentation and QA best practices
|
||||
|
||||
### Architecture & Code Quality Agents 🏗️
|
||||
|
||||
#### 🏗️ `system-architect` - Large-Scale Design Expert
|
||||
**What they do**: System architecture, design patterns, and scalability planning
|
||||
|
||||
**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 Architecture**: Large-scale system design, microservices architecture
|
||||
- **Design Patterns**: Architectural patterns, design principle application
|
||||
- **Scalability Planning**: Performance at scale, distributed system design
|
||||
- **Integration Design**: Cross-system integration, API design, service mesh
|
||||
- **Technology Strategy**: Technology selection, architectural decision records
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Scalable, maintainable architecture supporting business requirements
|
||||
- Secondary: Design pattern adherence, comprehensive architectural documentation
|
||||
- Success: Architecture enabling development team productivity and system reliability
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:design microservices-architecture # → System architecture and service design
|
||||
/sc:analyze --focus architecture system/ # → Architectural review and improvement
|
||||
/sc:plan scalability-improvements # → Scaling strategy and implementation
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Sequential**: Complex architectural analysis and design validation
|
||||
- **Context7**: Architectural patterns and framework documentation
|
||||
- **Serena**: Cross-system analysis and dependency management
|
||||
|
||||
---
|
||||
|
||||
#### 🔄 `code-refactorer` - Clean Code Specialist
|
||||
**What they do**: Code quality improvement, technical debt management, and clean code practices
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "refactor", "cleanup", "quality", "technical debt", "maintainability"
|
||||
- Code improvement and cleanup requests
|
||||
- Legacy code modernization and quality enhancement
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Code Quality**: Clean code principles, SOLID design patterns
|
||||
- **Refactoring Strategy**: Safe refactoring, incremental improvement
|
||||
- **Technical Debt**: Debt identification, prioritization, systematic reduction
|
||||
- **Design Patterns**: Pattern application, code structure improvement
|
||||
- **Maintainability**: Code readability, documentation, consistency
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Improved code maintainability with reduced technical debt
|
||||
- Secondary: Design pattern adherence, comprehensive test coverage
|
||||
- Success: Clean, maintainable code supporting long-term development productivity
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:improve --focus quality legacy-module/ # → Comprehensive code quality improvement
|
||||
/sc:refactor --safe complex-functions/ # → Safe refactoring with test coverage
|
||||
/sc:cleanup --technical-debt codebase/ # → Systematic technical debt reduction
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Morphllm**: Pattern-based code transformations and intelligent refactoring
|
||||
- **Serena**: Symbol-level analysis and large-scale refactoring coordination
|
||||
- **Sequential**: Complex refactoring strategy and impact analysis
|
||||
|
||||
### Communication & Knowledge Agents 📚
|
||||
|
||||
#### ✍️ `technical-writer` - Documentation Excellence Expert
|
||||
**What they do**: Technical documentation, API references, user guides, and knowledge management
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "document", "README", "guide", "documentation", "API docs", "tutorial"
|
||||
- Documentation creation and improvement requests
|
||||
- Knowledge transfer and educational content needs
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Technical Documentation**: API documentation, user guides, technical specifications
|
||||
- **Audience Analysis**: Content tailored to different technical expertise levels
|
||||
- **Information Architecture**: Structured, navigable documentation systems
|
||||
- **Accessibility**: WCAG compliant documentation, inclusive design principles
|
||||
- **Content Strategy**: Documentation planning, maintenance, and lifecycle management
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Flesch Reading Score 60-70 with zero ambiguity in instructions
|
||||
- Secondary: WCAG 2.1 AA compliance, complete working code examples
|
||||
- Success: Documentation enabling successful task completion without external assistance
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:document api-endpoints/ # → Comprehensive API documentation
|
||||
/sc:write user-guide --audience beginner # → User-friendly tutorial and guides
|
||||
/sc:improve --docs project-documentation/ # → Documentation quality enhancement
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: Documentation patterns and technical writing best practices
|
||||
- **Serena**: Documentation persistence and cross-reference management
|
||||
- **Sequential**: Complex documentation planning and content strategy
|
||||
|
||||
---
|
||||
|
||||
#### 👨🏫 `code-educator` - Learning & Mentorship Expert
|
||||
**What they do**: Code explanation, educational content, and knowledge transfer facilitation
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "explain", "learn", "understand", "teach", "tutorial", "example"
|
||||
- Educational content and learning-focused requests
|
||||
- Code explanation and mentorship needs
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Educational Content**: Clear, progressive learning materials and tutorials
|
||||
- **Code Explanation**: Complex concept breakdown with practical examples
|
||||
- **Mentorship**: Guided learning experiences and skill development
|
||||
- **Knowledge Transfer**: Best practices education and team learning facilitation
|
||||
- **Interactive Learning**: Hands-on examples and practical exercises
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Clear, progressive learning experiences appropriate to audience level
|
||||
- Secondary: Comprehensive examples, practical exercises, concept reinforcement
|
||||
- Success: Learners successfully apply concepts and develop practical skills
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/sc:explain complex-algorithm --educational # → Step-by-step learning guide
|
||||
/sc:teach react-patterns --beginner # → Progressive React tutorial
|
||||
/sc:mentor junior-developer --focus testing # → Personalized learning guidance
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Context7**: Educational resources and learning materials
|
||||
- **Sequential**: Complex concept breakdown and progressive learning design
|
||||
- **Magic**: Interactive examples and educational component creation
|
||||
|
||||
### Special Purpose Agents 🎯
|
||||
|
||||
#### 🧠 `brainstorm-PRD` - Requirements Discovery Expert
|
||||
**What they do**: Transform ambiguous project ideas into concrete specifications through structured brainstorming
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Ambiguous project requests ("I want to build something that...")
|
||||
- Exploration keywords: brainstorm, explore, discuss, figure out, not sure
|
||||
- PRD creation and requirements discovery needs
|
||||
- `/sc:brainstorm` command usage
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Requirements Discovery**: Socratic questioning, stakeholder analysis
|
||||
- **PRD Creation**: Comprehensive product requirement documentation
|
||||
- **Brainstorming Facilitation**: Creative exploration with practical constraints
|
||||
- **Specification Development**: Abstract concepts to concrete requirements
|
||||
- **Risk Assessment**: Early constraint and dependency identification
|
||||
|
||||
**Quality standards**:
|
||||
- Primary: Requirements are complete and unambiguous before project handoff
|
||||
- Secondary: All stakeholder perspectives integrated, feasibility validated
|
||||
- Success: Comprehensive PRD enabling downstream agent execution
|
||||
|
||||
**Integration workflow**:
|
||||
```bash
|
||||
/sc:brainstorm "task management app" # → Interactive discovery session
|
||||
# → Automatic handoff to brainstorm-PRD agent
|
||||
# → PRD generation with structured requirements
|
||||
# → Ready for /sc:workflow implementation
|
||||
```
|
||||
|
||||
**Integration with MCP servers**:
|
||||
- **Sequential**: Complex requirements analysis and systematic discovery
|
||||
- **Context7**: Industry patterns and requirement frameworks
|
||||
- **Serena**: Session persistence and cross-project learning
|
||||
|
||||
---
|
||||
|
||||
## Agent Coordination & Integration 🤝
|
||||
|
||||
### Automatic Agent Collaboration
|
||||
|
||||
Agents often work together automatically. Here are common collaboration patterns:
|
||||
|
||||
#### **Multi-Domain Projects**
|
||||
```bash
|
||||
/sc:build full-stack-app/
|
||||
# Auto-coordinates: backend-engineer + frontend-specialist + system-architect
|
||||
```
|
||||
|
||||
#### **Security-Focused Development**
|
||||
```bash
|
||||
/sc:analyze --focus security payment-system/
|
||||
# Auto-coordinates: security-auditor + backend-engineer + performance-optimizer
|
||||
```
|
||||
|
||||
#### **Quality Improvement**
|
||||
```bash
|
||||
/sc:improve --focus quality legacy-codebase/
|
||||
# Auto-coordinates: code-refactorer + qa-specialist + 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 and Modes
|
||||
|
||||
Agents seamlessly integrate with SuperClaude's command system:
|
||||
|
||||
```bash
|
||||
# Commands automatically select appropriate agents
|
||||
/sc:analyze → root-cause-analyzer or system-architect (context-dependent)
|
||||
/sc:build → frontend-specialist, backend-engineer, or python-ultimate-expert
|
||||
/sc:test → qa-specialist with domain-specific coordination
|
||||
/sc:brainstorm → brainstorm-PRD for requirements discovery
|
||||
/sc:document → technical-writer with audience-appropriate formatting
|
||||
```
|
||||
|
||||
**Mode Integration**:
|
||||
- **Brainstorming Mode**: Activates brainstorm-PRD for discovery sessions
|
||||
- **Task Management Mode**: Coordinates multiple agents across complex workflows
|
||||
- **Token Efficiency Mode**: Optimizes agent communication for resource constraints
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Agent Selection Cheat Sheet
|
||||
|
||||
| Agent | Best For | Auto-Activates On | Example Use |
|
||||
|-------|----------|-------------------|-------------|
|
||||
| 🐍 python-ultimate-expert | Python development | .py files, Python frameworks | Production Python APIs |
|
||||
| ⚙️ backend-engineer | Server-side systems | APIs, databases, services | Reliable backend systems |
|
||||
| 🎨 frontend-specialist | User interfaces | UI components, accessibility | Accessible web interfaces |
|
||||
| 🚀 devops-engineer | Infrastructure | CI/CD, deployment, monitoring | Deployment automation |
|
||||
| 🛡️ security-auditor | Security analysis | Security keywords, auth code | Vulnerability assessment |
|
||||
| ⚡ performance-optimizer | Performance tuning | "slow", "bottleneck", profiling | System optimization |
|
||||
| 🔍 root-cause-analyzer | Problem solving | "debug", "investigate", bugs | Complex bug investigation |
|
||||
| 🧪 qa-specialist | Quality assurance | Testing, validation, QA | Comprehensive test strategy |
|
||||
| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design |
|
||||
| 🔄 code-refactorer | Code improvement | Refactoring, cleanup, quality | Clean code practices |
|
||||
| ✍️ technical-writer | Documentation | Documentation requests | API documentation |
|
||||
| 👨🏫 code-educator | Learning & teaching | "explain", "learn", tutorials | Educational content |
|
||||
| 🧠 brainstorm-PRD | Requirements discovery | Ambiguous projects, brainstorming | Project specification |
|
||||
|
||||
### Most Useful Agent Combinations
|
||||
|
||||
**Full-Stack Development**:
|
||||
```bash
|
||||
# Automatically coordinates backend + frontend + architecture
|
||||
/sc:build modern-web-app/
|
||||
```
|
||||
|
||||
**Security & Performance Review**:
|
||||
```bash
|
||||
# Coordinates security + performance + quality analysis
|
||||
/sc:analyze --comprehensive production-system/
|
||||
```
|
||||
|
||||
**Learning & Development**:
|
||||
```bash
|
||||
# Coordinates educator + technical writer + domain expert
|
||||
/sc:explain complex-system --educational
|
||||
```
|
||||
|
||||
**Project Discovery to Implementation**:
|
||||
```bash
|
||||
# Brainstorm → PRD → Architecture → Implementation
|
||||
/sc: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 code-educator for explanation-focused assistance
|
||||
4. **Quality focus** - Combine qa-specialist with domain experts for comprehensive quality
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**For New Projects**:
|
||||
```bash
|
||||
/sc:brainstorm "your project idea" # → Requirements discovery
|
||||
# → Automatic PRD generation and handoff
|
||||
# → Ready for implementation workflow
|
||||
```
|
||||
|
||||
**For Existing Code**:
|
||||
```bash
|
||||
/sc:analyze existing-system/ # → Appropriate domain expert auto-selected
|
||||
/sc:improve --focus quality code/ # → Quality-focused agent coordination
|
||||
/sc:secure legacy-application/ # → Security-focused analysis and hardening
|
||||
```
|
||||
|
||||
**For Learning**:
|
||||
```bash
|
||||
/sc:explain complex-concept --educational # → Code educator with domain expert
|
||||
/sc: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
|
||||
|
||||
---
|
||||
|
||||
*Behind this sophisticated team of 13 specialists, SuperClaude remains simple to use. Just start coding and the right experts show up when needed! 🚀*
|
||||
@@ -1,947 +0,0 @@
|
||||
# SuperClaude Commands Guide 🛠️
|
||||
|
||||
## 💡 Don't Overthink It - SuperClaude Tries to Help
|
||||
|
||||
**The truth about these 21 commands**: You don't need to memorize them. Just start with `/sc:analyze` or `/sc:implement` and see what happens!
|
||||
|
||||
**Here's how it usually works:**
|
||||
- Type `/` in Claude Code → See available commands
|
||||
- Use basic ones like `/sc:analyze`, `/sc:build`, `/sc:improve`
|
||||
- **SuperClaude tries to pick helpful tools and experts** for each situation
|
||||
- More commands become useful as you get comfortable
|
||||
|
||||
**Auto-activation is pretty neat** 🪄 - SuperClaude attempts to detect what you're trying to do and activate relevant specialists (security expert, performance optimizer, etc.) without you managing it. Usually works well! 😊
|
||||
|
||||
---
|
||||
|
||||
## Quick "Just Try These" List 🚀
|
||||
|
||||
**Start here** (no reading required):
|
||||
```bash
|
||||
/sc:index # See what's available
|
||||
/sc:analyze src/ # Tries to analyze your code smartly
|
||||
/sc:brainstorm "app idea" # Interactive help for exploring ideas
|
||||
/sc:workflow feature-100-prd.md # Creates step-by-step implementation workflow from PRD
|
||||
/sc:implement user-auth # Creates features and components (replaces v2 /build)
|
||||
/sc:build # Attempts intelligent project building
|
||||
/sc:improve messy-file.js # Tries to clean up code
|
||||
/sc:troubleshoot "error" # Attempts to help with problems
|
||||
/sc:save --checkpoint # Save your work and progress
|
||||
```
|
||||
|
||||
**That's honestly enough to get started.** Everything else below is here when you get curious about what other tools are available. 🛠️
|
||||
|
||||
---
|
||||
|
||||
A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest about what works well and what's still rough around the edges.
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
*(You really don't need to memorize this - just pick what sounds useful)*
|
||||
|
||||
| Command | Purpose | Auto-Activates | Best For |
|
||||
|---------|---------|-----------------|----------|
|
||||
| `/sc:analyze` | Smart code analysis | Security/performance experts | Finding issues, understanding codebases |
|
||||
| `/sc:build` | Intelligent building | Frontend/backend specialists | Compilation, bundling, deployment prep |
|
||||
| `/sc:implement` | Feature implementation | Domain-specific experts | Creating features, components, APIs, services |
|
||||
| `/sc:improve` | Automatic code cleanup | Quality experts | Refactoring, optimization, quality fixes |
|
||||
| `/sc:troubleshoot` | Problem investigation | Debug specialists | Debugging, issue investigation |
|
||||
| `/sc:test` | Smart testing | QA experts | Running tests, coverage analysis |
|
||||
| `/sc:document` | Auto documentation | Writing specialists | README files, code comments, guides |
|
||||
| `/sc:git` | Enhanced git workflows | DevOps specialists | Smart commits, branch management |
|
||||
| `/sc:design` | System design help | Architecture experts | Architecture planning, API design |
|
||||
| `/sc:explain` | Learning assistant | Teaching specialists | Learning concepts, understanding code |
|
||||
| `/sc:cleanup` | Debt reduction | Refactoring experts | Removing dead code, organizing files |
|
||||
| `/sc:load` | Context understanding | Analysis experts | Project analysis, codebase understanding |
|
||||
| `/sc:estimate` | Smart estimation | Planning experts | Time/effort planning, complexity analysis |
|
||||
| `/sc:spawn` | Complex workflows | Orchestration system | Multi-step operations, workflow automation |
|
||||
| `/sc:task` | Project management | Planning system | Long-term feature planning, task tracking |
|
||||
| `/sc:workflow` | Implementation planning | Workflow system | Creating step-by-step workflows from PRDs |
|
||||
| `/sc:index` | Command navigation | Help system | Finding the right command for your task |
|
||||
| `/sc:brainstorm` | Interactive discovery | Socratic dialogue | Requirements gathering, idea exploration |
|
||||
| `/sc:reflect` | Task validation | Serena intelligence | Progress checking, completion validation |
|
||||
| `/sc:save` | Session persistence | Checkpoint system | Context saving, session management |
|
||||
| `/sc:select-tool` | Tool selection | Intelligence routing | Complex operation optimization |
|
||||
|
||||
**Pro tip**: Just try the ones that sound useful. SuperClaude usually tries to activate helpful experts and tools for each situation! 🎯
|
||||
|
||||
## Development Commands 🔨
|
||||
|
||||
### `/workflow` - Implementation Workflow Generator 🗺️
|
||||
**What it does**: Analyzes PRDs and feature requirements to create comprehensive step-by-step implementation workflows.
|
||||
|
||||
**The helpful part**: Takes your PRD and breaks it down into a structured implementation plan with expert guidance, dependency mapping, and task orchestration! 🎯
|
||||
|
||||
**When to use it**:
|
||||
- Starting a new feature from a PRD or specification
|
||||
- Need a clear implementation roadmap
|
||||
- Want expert guidance on implementation strategy
|
||||
- Planning complex features with multiple dependencies
|
||||
|
||||
**The magic**: Auto-activates appropriate expert personas (architect, security, frontend, backend) and MCP servers (Context7 for patterns, Sequential for complex analysis) based on your feature requirements.
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
/sc:workflow docs/feature-100-prd.md --strategy systematic --c7 --sequential
|
||||
/sc:workflow "user authentication system" --persona security --output detailed
|
||||
/sc:workflow payment-api --strategy mvp --risks --dependencies
|
||||
```
|
||||
|
||||
**What you get**:
|
||||
- **Roadmap Format**: Phase-based implementation plan with timelines
|
||||
- **Tasks Format**: Organized epics, stories, and actionable tasks
|
||||
- **Detailed Format**: Step-by-step instructions with time estimates
|
||||
- **Risk Assessment**: Potential issues and mitigation strategies
|
||||
- **Dependency Mapping**: Internal and external dependencies
|
||||
- **Expert Guidance**: Domain-specific best practices and patterns
|
||||
|
||||
### `/implement` - Feature Implementation
|
||||
**What it does**: Implements features, components, and functionality with intelligent expert activation.
|
||||
|
||||
**The helpful part**: SuperClaude auto-activates the right experts (frontend, backend, security) and tools based on what you're implementing! 🎯
|
||||
|
||||
**When to use it**:
|
||||
- Creating new features or components (replaces v2's `/build` functionality)
|
||||
- Implementing APIs, services, or modules
|
||||
- Building UI components with modern frameworks
|
||||
- Developing business logic and integrations
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:implement user authentication system # Implement complete feature
|
||||
/sc:implement --type component LoginForm # Create specific component
|
||||
/sc:implement --type api user-management # Build API endpoints
|
||||
/sc:implement --framework react dashboard # Framework-specific implementation
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type component|api|service|feature|module` - Implementation type
|
||||
- `--framework react|vue|express|django|etc` - Target framework
|
||||
- `--safe` - Conservative implementation approach
|
||||
- `--iterative` - Step-by-step development with validation
|
||||
- `--with-tests` - Include test implementation
|
||||
- `--documentation` - Generate docs alongside code
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:implement user authentication --type feature --with-tests
|
||||
/sc:implement dashboard component --type component --framework react
|
||||
/sc:implement REST API for orders --type api --safe
|
||||
/sc:implement payment processing --type service --iterative
|
||||
/sc:implement search functionality --framework vue --documentation
|
||||
```
|
||||
|
||||
**Auto-activation patterns**:
|
||||
- **Frontend**: UI components, React/Vue/Angular → frontend persona + Magic MCP
|
||||
- **Backend**: APIs, services, databases → backend persona + Context7
|
||||
- **Security**: Auth, payments, sensitive data → security persona + validation
|
||||
- **Complex features**: Multi-step implementations → Sequential MCP + architect persona
|
||||
|
||||
**Gotchas**:
|
||||
- Specify `--type` for better results (component vs service vs feature)
|
||||
- Use `--framework` when working with specific tech stacks
|
||||
- Try `--safe` for production code or `--iterative` for complex features
|
||||
- Remember: this replaces v2's `/build` for actual code implementation
|
||||
|
||||
---
|
||||
|
||||
### `/build` - Project Building
|
||||
**What it does**: Builds, compiles, and packages projects with smart error handling.
|
||||
|
||||
**The easy way**: Just type `/sc:build` and SuperClaude tries to figure out your build system! 🎯
|
||||
|
||||
**When to use it**:
|
||||
- You need to compile/bundle your project (just try `/sc:build`)
|
||||
- Build process is failing and you want help debugging
|
||||
- Setting up build optimization (it tries to detect what you need)
|
||||
- Preparing for deployment
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:build # Build current project
|
||||
/sc:build --type prod # Production build
|
||||
/sc:build --clean # Clean build (remove old artifacts)
|
||||
/sc:build --optimize # Enable optimizations
|
||||
/sc:build src/ # Build specific directory
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type dev|prod|test` - Build type
|
||||
- `--clean` - Clean before building
|
||||
- `--optimize` - Enable build optimizations
|
||||
- `--verbose` - Show detailed build output
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:build --type prod --optimize # Production build with optimizations
|
||||
/sc:build --clean --verbose # Clean build with detailed output
|
||||
/sc:build src/components # Build just the components folder
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Works best with common build tools (npm, webpack, etc.)
|
||||
- May struggle with very custom build setups
|
||||
- Check your build tool is in PATH
|
||||
|
||||
---
|
||||
|
||||
### `/design` - System & Component Design
|
||||
**What it does**: Creates system architecture, API designs, and component specifications.
|
||||
|
||||
**When to use it**:
|
||||
- Planning new features or systems
|
||||
- Need API or database design
|
||||
- Creating component architecture
|
||||
- Documenting system relationships
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:design user-auth-system # Design a user authentication system
|
||||
/sc:design --type api auth # Design just the API part
|
||||
/sc:design --format spec payment # Create formal specification
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type architecture|api|component|database` - Design focus
|
||||
- `--format diagram|spec|code` - Output format
|
||||
- `--iterative` - Refine design through iterations
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:design --type api user-management # Design user management API
|
||||
/sc:design --format spec chat-system # Create chat system specification
|
||||
/sc:design --type database ecommerce # Design database schema
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- More conceptual than code-generating
|
||||
- Output quality depends on how clearly you describe requirements
|
||||
- Great for planning phase, less for implementation details
|
||||
|
||||
## Analysis Commands 🔍
|
||||
|
||||
### `/analyze` - Code Analysis
|
||||
**What it does**: Comprehensive analysis of code quality, security, performance, and architecture.
|
||||
|
||||
**The helpful part**: SuperClaude tries to detect what kind of analysis you need and usually picks relevant experts! 🔍
|
||||
|
||||
**When to use it**:
|
||||
- Understanding unfamiliar codebases (just point it at any folder)
|
||||
- Finding security vulnerabilities (security expert usually jumps in)
|
||||
- Performance bottleneck hunting (performance expert usually helps)
|
||||
- Code quality assessment (quality specialist often takes over)
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:analyze src/ # Analyze entire src directory
|
||||
/sc:analyze --focus security # Focus on security issues
|
||||
/sc:analyze --depth deep app.js # Deep analysis of specific file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--focus quality|security|performance|architecture` - Analysis focus
|
||||
- `--depth quick|deep` - Analysis thoroughness
|
||||
- `--format text|json|report` - Output format
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:analyze --focus security --depth deep # Deep security analysis
|
||||
/sc:analyze --focus performance src/api/ # Performance analysis of API
|
||||
/sc:analyze --format report . # Generate analysis report
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can take a while on large codebases
|
||||
- Security analysis is pretty good, performance analysis varies
|
||||
- Works best with common languages (JS, Python, etc.)
|
||||
|
||||
---
|
||||
|
||||
### `/troubleshoot` - Problem Investigation
|
||||
**What it does**: Systematic debugging and problem investigation.
|
||||
|
||||
**When to use it**:
|
||||
- Something's broken and you're not sure why
|
||||
- Need systematic debugging approach
|
||||
- Error messages are confusing
|
||||
- Performance issues investigation
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:troubleshoot "login not working" # Investigate login issue
|
||||
/sc:troubleshoot --logs error.log # Analyze error logs
|
||||
/sc:troubleshoot performance # Performance troubleshooting
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--logs <file>` - Include log file analysis
|
||||
- `--systematic` - Use structured debugging approach
|
||||
- `--focus network|database|frontend` - Focus area
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:troubleshoot "API returning 500" --logs server.log
|
||||
/sc:troubleshoot --focus database "slow queries"
|
||||
/sc:troubleshoot "build failing" --systematic
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Works better with specific error descriptions
|
||||
- Include relevant error messages and logs when possible
|
||||
- May suggest obvious things first (that's usually good!)
|
||||
|
||||
---
|
||||
|
||||
### `/explain` - Educational Explanations
|
||||
**What it does**: Explains code, concepts, and technologies in an educational way.
|
||||
|
||||
**When to use it**:
|
||||
- Learning new technologies or patterns
|
||||
- Understanding complex code
|
||||
- Need clear explanations for team members
|
||||
- Documenting tricky concepts
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:explain async/await # Explain async/await concept
|
||||
/sc:explain --code src/utils.js # Explain specific code file
|
||||
/sc:explain --beginner React hooks # Beginner-friendly explanation
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--beginner` - Simpler explanations
|
||||
- `--advanced` - Technical depth
|
||||
- `--code <file>` - Explain specific code
|
||||
- `--examples` - Include practical examples
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:explain --beginner "what is REST API"
|
||||
/sc:explain --code src/auth.js --advanced
|
||||
/sc:explain --examples "React context patterns"
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Great for well-known concepts, may struggle with very niche topics
|
||||
- Better with specific questions than vague "explain this codebase"
|
||||
- Include context about your experience level
|
||||
|
||||
## Quality Commands ✨
|
||||
|
||||
### `/improve` - Code Enhancement
|
||||
**What it does**: Systematic improvements to code quality, performance, and maintainability.
|
||||
|
||||
**When to use it**:
|
||||
- Refactoring messy code
|
||||
- Performance optimization
|
||||
- Applying best practices
|
||||
- Modernizing old code
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:improve src/legacy/ # Improve legacy code
|
||||
/sc:improve --type performance # Focus on performance
|
||||
/sc:improve --safe src/utils.js # Safe, low-risk improvements only
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type quality|performance|maintainability|style` - Improvement focus
|
||||
- `--safe` - Only apply low-risk changes
|
||||
- `--preview` - Show what would be changed without doing it
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:improve --type performance --safe src/api/
|
||||
/sc:improve --preview src/components/LegacyComponent.js
|
||||
/sc:improve --type style . --safe
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Always use `--preview` first to see what it wants to change
|
||||
- `--safe` is your friend - prevents risky refactoring
|
||||
- Works best on smaller files/modules rather than entire codebases
|
||||
|
||||
---
|
||||
|
||||
### `/cleanup` - Technical Debt Reduction
|
||||
**What it does**: Removes dead code, unused imports, and organizes file structure.
|
||||
|
||||
**When to use it**:
|
||||
- Codebase feels cluttered
|
||||
- Lots of unused imports/variables
|
||||
- File organization is messy
|
||||
- Before major refactoring
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:cleanup src/ # Clean up src directory
|
||||
/sc:cleanup --dead-code # Focus on dead code removal
|
||||
/sc:cleanup --imports package.js # Clean up imports in specific file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--dead-code` - Remove unused code
|
||||
- `--imports` - Clean up import statements
|
||||
- `--files` - Reorganize file structure
|
||||
- `--safe` - Conservative cleanup only
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:cleanup --dead-code --safe src/utils/
|
||||
/sc:cleanup --imports src/components/
|
||||
/sc:cleanup --files . --safe
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can be aggressive - always review changes carefully
|
||||
- May not catch all dead code (especially dynamic imports)
|
||||
- Better to run on smaller sections than entire projects
|
||||
|
||||
---
|
||||
|
||||
### `/test` - Testing & Quality Assurance
|
||||
**What it does**: Runs tests, generates coverage reports, and maintains test quality.
|
||||
|
||||
**When to use it**:
|
||||
- Running test suites
|
||||
- Checking test coverage
|
||||
- Generating test reports
|
||||
- Setting up continuous testing
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:test # Run all tests
|
||||
/sc:test --type unit # Run only unit tests
|
||||
/sc:test --coverage # Generate coverage report
|
||||
/sc:test --watch src/ # Watch mode for development
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type unit|integration|e2e|all` - Test type
|
||||
- `--coverage` - Generate coverage reports
|
||||
- `--watch` - Run tests in watch mode
|
||||
- `--fix` - Try to fix failing tests automatically
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:test --type unit --coverage
|
||||
/sc:test --watch src/components/
|
||||
/sc:test --type e2e --fix
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Needs your test framework to be properly configured
|
||||
- Coverage reports depend on your existing test setup
|
||||
- `--fix` is experimental - review what it changes
|
||||
|
||||
## Documentation Commands 📝
|
||||
|
||||
### `/document` - Focused Documentation
|
||||
**What it does**: Creates documentation for specific components, functions, or features.
|
||||
|
||||
**When to use it**:
|
||||
- Need README files
|
||||
- Writing API documentation
|
||||
- Adding code comments
|
||||
- Creating user guides
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:document src/api/auth.js # Document authentication module
|
||||
/sc:document --type api # API documentation
|
||||
/sc:document --style brief README # Brief README file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type inline|external|api|guide` - Documentation type
|
||||
- `--style brief|detailed` - Level of detail
|
||||
- `--template` - Use specific documentation template
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:document --type api src/controllers/
|
||||
/sc:document --style detailed --type guide user-onboarding
|
||||
/sc:document --type inline src/utils/helpers.js
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Better with specific files/functions than entire projects
|
||||
- Quality depends on how well-structured your code is
|
||||
- May need some editing to match your project's documentation style
|
||||
|
||||
## Project Management Commands 📊
|
||||
|
||||
### `/estimate` - Project Estimation
|
||||
**What it does**: Estimates time, effort, and complexity for development tasks.
|
||||
|
||||
**When to use it**:
|
||||
- Planning new features
|
||||
- Sprint planning
|
||||
- Understanding project complexity
|
||||
- Resource allocation
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:estimate "add user authentication" # Estimate auth feature
|
||||
/sc:estimate --detailed shopping-cart # Detailed breakdown
|
||||
/sc:estimate --complexity user-dashboard # Complexity analysis
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--detailed` - Detailed breakdown of tasks
|
||||
- `--complexity` - Focus on technical complexity
|
||||
- `--team-size <n>` - Consider team size in estimates
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:estimate --detailed "implement payment system"
|
||||
/sc:estimate --complexity --team-size 3 "migrate to microservices"
|
||||
/sc:estimate "add real-time chat" --detailed
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Estimates are rough - use as starting points, not gospel
|
||||
- Works better with clear, specific feature descriptions
|
||||
- Consider your team's experience with the tech stack
|
||||
|
||||
---
|
||||
|
||||
### `/task` - Long-term Project Management
|
||||
**What it does**: Manages complex, multi-session development tasks and features.
|
||||
|
||||
**When to use it**:
|
||||
- Planning features that take days/weeks
|
||||
- Breaking down large projects
|
||||
- Tracking progress across sessions
|
||||
- Coordinating team work
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:task create "implement user dashboard" # Create new task
|
||||
/sc:task status # Check task status
|
||||
/sc:task breakdown "payment integration" # Break down into subtasks
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `create` - Create new long-term task
|
||||
- `status` - Check current task status
|
||||
- `breakdown` - Break large task into smaller ones
|
||||
- `--priority high|medium|low` - Set task priority
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:task create "migrate from REST to GraphQL" --priority high
|
||||
/sc:task breakdown "e-commerce checkout flow"
|
||||
/sc:task status
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Still experimental - doesn't always persist across sessions reliably 😅
|
||||
- Better for planning than actual project management
|
||||
- Works best when you're specific about requirements
|
||||
|
||||
---
|
||||
|
||||
### `/spawn` - Complex Operation Orchestration
|
||||
**What it does**: Coordinates complex, multi-step operations and workflows.
|
||||
|
||||
**When to use it**:
|
||||
- Operations involving multiple tools/systems
|
||||
- Coordinating parallel workflows
|
||||
- Complex deployment processes
|
||||
- Multi-stage data processing
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:spawn deploy-pipeline # Orchestrate deployment
|
||||
/sc:spawn --parallel migrate-data # Parallel data migration
|
||||
/sc:spawn setup-dev-environment # Complex environment setup
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--parallel` - Run operations in parallel when possible
|
||||
- `--sequential` - Force sequential execution
|
||||
- `--monitor` - Monitor operation progress
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:spawn --parallel "test and deploy to staging"
|
||||
/sc:spawn setup-ci-cd --monitor
|
||||
/sc:spawn --sequential database-migration
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Most complex command - expect some rough edges
|
||||
- Better for well-defined workflows than ad-hoc operations
|
||||
- May need multiple iterations to get right
|
||||
|
||||
## Version Control Commands 🔄
|
||||
|
||||
### `/git` - Enhanced Git Operations
|
||||
**What it does**: Git operations with intelligent commit messages and workflow optimization.
|
||||
|
||||
**When to use it**:
|
||||
- Making commits with better messages
|
||||
- Branch management
|
||||
- Complex git workflows
|
||||
- Git troubleshooting
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:git commit # Smart commit with auto-generated message
|
||||
/sc:git --smart-commit add . # Add and commit with smart message
|
||||
/sc:git branch feature/new-auth # Create and switch to new branch
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--smart-commit` - Generate intelligent commit messages
|
||||
- `--branch-strategy` - Apply branch naming conventions
|
||||
- `--interactive` - Interactive mode for complex operations
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:git --smart-commit "fixed login bug"
|
||||
/sc:git branch feature/user-dashboard --branch-strategy
|
||||
/sc:git merge develop --interactive
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Smart commit messages are pretty good but review them
|
||||
- Assumes you're following common git workflows
|
||||
- Won't fix bad git habits - just makes them easier
|
||||
|
||||
## Utility Commands 🔧
|
||||
|
||||
### `/index` - Command Navigation
|
||||
**What it does**: Helps you find the right command for your task.
|
||||
|
||||
**When to use it**:
|
||||
- Not sure which command to use
|
||||
- Exploring available commands
|
||||
- Learning about command capabilities
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:index # List all commands
|
||||
/sc:index testing # Find commands related to testing
|
||||
/sc:index --category analysis # Commands in analysis category
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--category <cat>` - Filter by command category
|
||||
- `--search <term>` - Search command descriptions
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:index --search "performance"
|
||||
/sc:index --category quality
|
||||
/sc:index git
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Simple but useful for discovery
|
||||
- Better than trying to remember all 21 commands
|
||||
|
||||
---
|
||||
|
||||
### `/load` - Project Context Loading
|
||||
**What it does**: Loads and analyzes project context for better understanding.
|
||||
|
||||
**When to use it**:
|
||||
- Starting work on unfamiliar project
|
||||
- Need to understand project structure
|
||||
- Before making major changes
|
||||
- Onboarding team members
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:load # Load current project context
|
||||
/sc:load src/ # Load specific directory context
|
||||
/sc:load --deep # Deep analysis of project structure
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--deep` - Comprehensive project analysis
|
||||
- `--focus <area>` - Focus on specific project area
|
||||
- `--summary` - Generate project summary
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:load --deep --summary
|
||||
/sc:load src/components/ --focus architecture
|
||||
/sc:load . --focus dependencies
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can take time on large projects
|
||||
- More useful at project start than during development
|
||||
- Helps with onboarding but not a replacement for good docs
|
||||
|
||||
## Session & Intelligence Commands 🧠
|
||||
|
||||
### `/brainstorm` - Interactive Requirements Discovery
|
||||
**What it does**: Interactive Socratic dialogue for exploring ideas and discovering requirements.
|
||||
|
||||
**When to use it**:
|
||||
- Starting with vague project ideas ("I want to build something...")
|
||||
- Need help figuring out what to build
|
||||
- Exploring requirements for new features
|
||||
- Creative problem solving and ideation
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:brainstorm "mobile app idea" # Explore app concept
|
||||
/sc:brainstorm --depth deep startup # Deep exploration of startup idea
|
||||
/sc:brainstorm --focus business ecom # Business-focused e-commerce planning
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--depth normal|deep` - Exploration thoroughness
|
||||
- `--focus business|technical|user` - Conversation focus area
|
||||
- `--prd` - Generate Product Requirements Document after dialogue
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:brainstorm "task management app" --prd
|
||||
/sc:brainstorm --depth deep --focus technical "real-time chat system"
|
||||
/sc:brainstorm "improve user onboarding" --focus user
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Works best when you're genuinely uncertain about requirements
|
||||
- Quality of output depends on engagement in the dialogue
|
||||
- Can take 10-15 minutes for thorough exploration
|
||||
|
||||
---
|
||||
|
||||
### `/reflect` - Task Reflection and Validation
|
||||
**What it does**: Uses Serena intelligence for task validation, progress analysis, and completion verification.
|
||||
|
||||
**When to use it**:
|
||||
- Checking if you're on the right track with a task
|
||||
- Validating task completion before marking done
|
||||
- Analyzing collected information during complex work
|
||||
- Getting intelligent feedback on progress
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:reflect --type task # Reflect on current task approach
|
||||
/sc:reflect --type completion # Validate task completion
|
||||
/sc:reflect --type session # Analyze session progress
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type task|completion|session` - Type of reflection
|
||||
- `--analyze` - Deep analysis of current context
|
||||
- `--validate` - Validation-focused reflection
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:reflect --type completion "implemented user auth"
|
||||
/sc:reflect --analyze --type session
|
||||
/sc:reflect --type task --validate "refactoring approach"
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Requires Serena MCP server to be available
|
||||
- Most effective when you provide context about what you're working on
|
||||
- Best used at natural stopping points in work
|
||||
|
||||
---
|
||||
|
||||
### `/save` - Session Persistence and Checkpointing
|
||||
**What it does**: Saves session context, creates checkpoints, and manages project memory through Serena.
|
||||
|
||||
**When to use it**:
|
||||
- Saving work progress before ending session
|
||||
- Creating checkpoints before risky operations
|
||||
- Preserving insights and decisions for future sessions
|
||||
- Managing long-term project context
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:save # Basic session save
|
||||
/sc:save --checkpoint # Create checkpoint with analysis
|
||||
/sc:save --type summary # Save with session summary
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--checkpoint` - Create detailed checkpoint
|
||||
- `--type session|summary|insights` - Save type
|
||||
- `--analyze` - Include session analysis in save
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:save --checkpoint "before major refactoring"
|
||||
/sc:save --type summary --analyze
|
||||
/sc:save "completed authentication implementation"
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Requires Serena MCP server for full functionality
|
||||
- Checkpoint creation may take a moment for analysis
|
||||
- Most valuable for complex, multi-session projects
|
||||
|
||||
---
|
||||
|
||||
### `/select-tool` - Intelligent Tool Selection
|
||||
**What it does**: Analyzes complex operations and recommends optimal tool combinations and approaches.
|
||||
|
||||
**When to use it**:
|
||||
- Uncertain about best approach for complex tasks
|
||||
- Want to optimize tool selection for efficiency
|
||||
- Need guidance on MCP server coordination
|
||||
- Planning multi-step technical operations
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/sc:select-tool "large codebase refactoring" # Get tool recommendations
|
||||
/sc:select-tool --analyze "performance audit" # Analyze optimal approach
|
||||
/sc:select-tool --context react-app "UI testing" # Context-aware selection
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--analyze` - Deep analysis of optimal approach
|
||||
- `--context <tech>` - Provide technical context
|
||||
- `--efficiency` - Focus on performance optimization
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/sc:select-tool --analyze "migrate 100+ files to TypeScript"
|
||||
/sc:select-tool --context nodejs --efficiency "API performance testing"
|
||||
/sc:select-tool "cross-browser testing setup"
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Recommendations are guidance, not requirements
|
||||
- Most valuable for complex, multi-faceted operations
|
||||
- Consider your specific project context when following recommendations
|
||||
|
||||
## Command Tips & Patterns 💡
|
||||
|
||||
### Effective Flag Combinations
|
||||
```bash
|
||||
# Safe improvement workflow
|
||||
/sc:improve --preview src/component.js # See what would change
|
||||
/sc:improve --safe src/component.js # Apply safe changes only
|
||||
|
||||
# Comprehensive analysis
|
||||
/sc:analyze --focus security --depth deep
|
||||
/sc:test --coverage
|
||||
/sc:document --type api
|
||||
|
||||
# Smart git workflow
|
||||
/sc:git add .
|
||||
/sc:git --smart-commit --branch-strategy
|
||||
|
||||
# Project understanding workflow
|
||||
/sc:load --deep --summary
|
||||
/sc:analyze --focus architecture
|
||||
/sc:document --type guide
|
||||
```
|
||||
|
||||
### Common Workflows
|
||||
|
||||
**New Project Discovery** (V4 Beta):
|
||||
```bash
|
||||
/sc:brainstorm "project idea" --prd # Explore and define requirements
|
||||
/sc:load --deep --summary # Understand existing codebase
|
||||
/sc:workflow requirements.md # Create implementation plan
|
||||
/sc:save --checkpoint "project planning" # Save planning insights
|
||||
```
|
||||
|
||||
**New Project Onboarding**:
|
||||
```bash
|
||||
/sc:load --deep --summary
|
||||
/sc:analyze --focus architecture
|
||||
/sc:test --coverage
|
||||
/sc:document README
|
||||
```
|
||||
|
||||
**Bug Investigation**:
|
||||
```bash
|
||||
/sc:troubleshoot "specific error message" --logs
|
||||
/sc:analyze --focus security
|
||||
/sc:test --type unit affected-component
|
||||
/sc:reflect --type completion "bug analysis"
|
||||
```
|
||||
|
||||
**Code Quality Improvement**:
|
||||
```bash
|
||||
/sc:analyze --focus quality
|
||||
/sc:improve --preview src/
|
||||
/sc:cleanup --safe
|
||||
/sc:test --coverage
|
||||
/sc:reflect --type completion "quality improvements"
|
||||
```
|
||||
|
||||
**Pre-deployment Checklist**:
|
||||
```bash
|
||||
/sc:test --type all --coverage
|
||||
/sc:analyze --focus security
|
||||
/sc:build --type prod --optimize
|
||||
/sc:git --smart-commit
|
||||
/sc:save --checkpoint "pre-deployment validation"
|
||||
```
|
||||
|
||||
**Complex Task Planning** (V4 Beta):
|
||||
```bash
|
||||
/sc:select-tool "migrate to microservices" # Get approach recommendations
|
||||
/sc:reflect --type task "migration strategy" # Validate approach
|
||||
/sc:workflow migration-plan.md # Create detailed workflow
|
||||
/sc:save "migration planning complete" # Preserve insights
|
||||
```
|
||||
|
||||
### Troubleshooting Command Issues
|
||||
|
||||
**Command not working as expected?**
|
||||
- Try adding `--help` to see all options
|
||||
- Use `--preview` or `--safe` flags when available
|
||||
- Start with smaller scope (single file vs. entire project)
|
||||
|
||||
**Analysis taking too long?**
|
||||
- Use `--focus` to narrow scope
|
||||
- Try `--depth quick` instead of deep analysis
|
||||
- Analyze smaller directories first
|
||||
|
||||
**Build/test commands failing?**
|
||||
- Make sure your tools are in PATH
|
||||
- Check that config files are in expected locations
|
||||
- Try running the underlying commands directly first
|
||||
|
||||
**Not sure which command to use?**
|
||||
- Use `/index` to browse available commands
|
||||
- Look at the Quick Reference table above
|
||||
- Try the most specific command first, then broader ones
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**The real truth about these commands** 💯:
|
||||
- **Just try them** - You don't need to study this guide first
|
||||
- **Start with the basics** - `/analyze`, `/build`, `/improve` cover most needs
|
||||
- **Let auto-activation work** - SuperClaude usually picks helpful experts
|
||||
- **Experiment freely** - Use `--preview` if you want to see what would happen first
|
||||
|
||||
**Still rough around the edges:**
|
||||
- Complex orchestration (spawn, task) can be a bit flaky
|
||||
- Some analysis depends heavily on your project setup
|
||||
- Error handling could be better in some commands
|
||||
|
||||
**Getting better all the time:**
|
||||
- We actively improve commands based on user feedback
|
||||
- Newer commands (analyze, improve) tend to work better
|
||||
- Auto-activation keeps getting smarter
|
||||
|
||||
**Don't stress about memorizing this** 🧘♂️
|
||||
- SuperClaude is designed to be discoverable through use
|
||||
- Type `/` to see available commands
|
||||
- Commands suggest what they can do when you use `--help`
|
||||
- The intelligent routing handles most of the complexity
|
||||
|
||||
**Need help?** Check the GitHub issues or create a new one if you're stuck! 🚀
|
||||
|
||||
---
|
||||
|
||||
*Happy coding! Just remember - you can skip most of this guide and learn by doing. 🎯*
|
||||
@@ -1,599 +0,0 @@
|
||||
# SuperClaude V4 Beta Flags User Guide 🏁
|
||||
|
||||
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
|
||||
|
||||
**The honest truth**: You don't need to memorize these flags. SuperClaude usually tries to add helpful ones based on what you're doing!
|
||||
|
||||
**Here's what actually happens:**
|
||||
- You type `/analyze auth.js`
|
||||
- SuperClaude detects it's security-related code
|
||||
- **Usually activates** security-auditor agent, `--focus security`, `--validate`
|
||||
- You often get expert security analysis without managing any flags
|
||||
|
||||
**When might you manually use flags?**
|
||||
- You want to **override** what SuperClaude picked (rare)
|
||||
- You're **curious** about specific aspects (`--focus performance`)
|
||||
- You want to **experiment** with different approaches
|
||||
|
||||
**Bottom line**: Just use basic commands and let the auto-activation work. These flags are here when you want them, not because you need them. 🎯
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Just Try These (No Flag Knowledge Required)
|
||||
|
||||
```bash
|
||||
# These work great with zero flag knowledge:
|
||||
/sc:analyze src/ # Auto-activates appropriate expert agents
|
||||
/sc:build # Auto-optimizes based on your project
|
||||
/sc:improve messy-code.js # Auto-activates quality agents and safety flags
|
||||
/sc:troubleshoot "weird error" # Auto-activates root-cause-analyzer and debugging flags
|
||||
/sc:brainstorm "my app idea" # Auto-activates brainstorm-PRD agent for requirements
|
||||
```
|
||||
|
||||
**See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes.
|
||||
|
||||
---
|
||||
|
||||
A practical guide to SuperClaude's flag system. Flags are like command-line options that change how SuperClaude behaves - think of them as superpowers for your commands.
|
||||
|
||||
## What Are Flags? 🤔
|
||||
|
||||
**Flags are modifiers** that change how SuperClaude processes your requests. They come after commands and start with `--`.
|
||||
|
||||
**Basic syntax** (but you usually don't need to know this):
|
||||
```bash
|
||||
/sc:command --flag-name
|
||||
/sc:command --flag-name value
|
||||
/sc:analyze src/ --focus security --depth deep
|
||||
```
|
||||
|
||||
**How flags actually work in practice**:
|
||||
1. **Auto-activation** - SuperClaude adds them based on context (this is the main way! 🎯)
|
||||
2. **Manual override** - You can add them explicitly if you want different behavior
|
||||
|
||||
**Why flags exist** (mostly automatic benefits):
|
||||
- Get better, more focused results
|
||||
- Auto-enable the right thinking depth
|
||||
- Connect to special capabilities when useful
|
||||
- Optimize for speed or detail based on your task
|
||||
- Direct attention to what you're actually working on
|
||||
|
||||
**The key point**: SuperClaude handles flag selection intelligently so you don't have to think about it! 🧠
|
||||
|
||||
## Flag Categories 📂
|
||||
|
||||
### Planning & Analysis Flags 🧠
|
||||
|
||||
These control how deeply SuperClaude thinks about your request.
|
||||
|
||||
#### `--plan`
|
||||
**What it does**: Shows execution plan before doing anything
|
||||
**When to use**: When you want to see what SuperClaude will do first
|
||||
**Example**: `/build --plan` - See build steps before running
|
||||
|
||||
#### `--think`
|
||||
**What it does**: Multi-file analysis (~4K tokens)
|
||||
**When to use**: Complex problems involving several files
|
||||
**Auto-activates**: Import chains >5 files, cross-module calls >10 references
|
||||
**Example**: `/analyze complex-system/ --think`
|
||||
|
||||
#### `--think-hard`
|
||||
**What it does**: Deep architectural analysis (~10K tokens)
|
||||
**When to use**: System-wide problems, architectural decisions
|
||||
**Auto-activates**: System refactoring, bottlenecks >3 modules
|
||||
**Example**: `/improve legacy-system/ --think-hard`
|
||||
|
||||
#### `--ultrathink`
|
||||
**What it does**: Maximum depth analysis (~32K tokens)
|
||||
**When to use**: Critical system redesign, complex debugging
|
||||
**Auto-activates**: Legacy modernization, critical vulnerabilities
|
||||
**Example**: `/troubleshoot "entire auth system broken" --ultrathink`
|
||||
|
||||
**💡 Tip**: Start with `--think`, only go deeper if needed. More thinking = slower but more thorough.
|
||||
|
||||
---
|
||||
|
||||
### Efficiency & Control Flags ⚡
|
||||
|
||||
Control output style, safety, and performance.
|
||||
|
||||
#### `--uc` / `--ultracompressed`
|
||||
**What it does**: 60-80% token reduction using symbols
|
||||
**When to use**: Large operations, when context is getting full
|
||||
**Auto-activates**: Context usage >75%, large-scale operations
|
||||
**Example**: `/analyze huge-codebase/ --uc`
|
||||
|
||||
#### `--safe-mode`
|
||||
**What it does**: Maximum validation, conservative execution
|
||||
**When to use**: Production environments, risky operations
|
||||
**Auto-activates**: Resource usage >85%, production environment
|
||||
**Example**: `/improve production-code/ --safe-mode`
|
||||
|
||||
#### `--validate`
|
||||
**What it does**: Pre-operation validation and risk assessment
|
||||
**When to use**: Want to check before making changes
|
||||
**Auto-activates**: Risk score >0.7
|
||||
**Example**: `/cleanup legacy/ --validate`
|
||||
|
||||
#### `--verbose`
|
||||
**What it does**: Maximum detail and explanation
|
||||
**When to use**: Learning, debugging, need full context
|
||||
**Example**: `/build --verbose` - See every build step
|
||||
|
||||
#### `--answer-only`
|
||||
**What it does**: Direct response without task creation
|
||||
**When to use**: Quick questions, don't want workflow automation
|
||||
**Example**: `/explain React hooks --answer-only`
|
||||
|
||||
**💡 Tip**: `--uc` is great for big operations. `--safe-mode` for anything important. `--verbose` when you're learning.
|
||||
|
||||
---
|
||||
|
||||
### MCP Server Flags 🔧
|
||||
|
||||
Enable specialized capabilities through MCP servers.
|
||||
|
||||
#### `--c7` / `--context7`
|
||||
**What it does**: Enables Context7 for official library documentation
|
||||
**When to use**: Working with frameworks, need official docs
|
||||
**Auto-activates**: External library imports, framework questions
|
||||
**Example**: `/build react-app/ --c7` - Get React best practices
|
||||
|
||||
#### `--seq` / `--sequential`
|
||||
**What it does**: Enables Sequential for complex multi-step analysis
|
||||
**When to use**: Complex debugging, system design
|
||||
**Auto-activates**: Complex debugging, `--think` flags
|
||||
**Example**: `/troubleshoot "auth flow broken" --seq`
|
||||
|
||||
#### `--magic`
|
||||
**What it does**: Enables Magic for UI component generation
|
||||
**When to use**: Creating UI components, design systems
|
||||
**Auto-activates**: UI component requests, frontend persona
|
||||
**Example**: `/build dashboard --magic` - Get modern UI components
|
||||
|
||||
#### `--play` / `--playwright`
|
||||
**What it does**: Enables Playwright for browser automation and testing
|
||||
**When to use**: E2E testing, performance monitoring
|
||||
**Auto-activates**: Test workflows, QA specialist agent
|
||||
**Example**: `/test e2e --play`
|
||||
|
||||
#### `--morph` / `--fast-apply`
|
||||
**What it does**: Enables Morphllm for intelligent file editing with Fast Apply
|
||||
**When to use**: Multi-file edits, pattern-based transformations
|
||||
**Auto-activates**: Complex refactoring, bulk file updates
|
||||
**Example**: `/refactor --morph pattern-updates/`
|
||||
|
||||
#### `--serena` / `--semantic`
|
||||
**What it does**: Enables Serena for semantic analysis and memory operations
|
||||
**When to use**: Symbol analysis, project-wide context, session management
|
||||
**Auto-activates**: Complex symbol operations, memory commands
|
||||
**Example**: `/analyze --serena --semantic large-codebase/`
|
||||
|
||||
#### `--all-mcp`
|
||||
**What it does**: Enables all MCP servers simultaneously
|
||||
**When to use**: Complex multi-domain problems
|
||||
**Auto-activates**: Problem complexity >0.8, multi-domain indicators
|
||||
**Example**: `/analyze entire-app/ --all-mcp`
|
||||
|
||||
#### `--no-mcp`
|
||||
**What it does**: Disables all MCP servers, native tools only
|
||||
**When to use**: Faster execution, don't need specialized features
|
||||
**Example**: `/analyze simple-script.js --no-mcp`
|
||||
|
||||
**💡 Tip**: MCP servers add capabilities but use more tokens. `--c7` for docs, `--seq` for thinking, `--magic` for UI, `--serena` for memory & semantic analysis.
|
||||
|
||||
---
|
||||
|
||||
### Advanced Orchestration Flags 🎭
|
||||
|
||||
For complex operations and workflows.
|
||||
|
||||
#### `--delegate [files|folders|auto]`
|
||||
**What it does**: Enables sub-agent delegation for parallel processing
|
||||
**When to use**: Large codebases, complex analysis
|
||||
**Auto-activates**: >7 directories or >50 files
|
||||
**Options**:
|
||||
- `files` - Delegate individual file analysis
|
||||
- `folders` - Delegate directory-level analysis
|
||||
- `auto` - Smart delegation strategy
|
||||
|
||||
**Example**: `/analyze monorepo/ --delegate auto`
|
||||
|
||||
#### `--wave-mode [auto|force|off]`
|
||||
**What it does**: Multi-stage execution with compound intelligence
|
||||
**When to use**: Complex improvements, systematic analysis
|
||||
**Auto-activates**: Complexity >0.8 AND files >20 AND operation types >2
|
||||
**Example**: `/improve legacy-system/ --wave-mode force`
|
||||
|
||||
#### `--loop`
|
||||
**What it does**: Iterative improvement mode
|
||||
**When to use**: Quality improvement, refinement operations
|
||||
**Auto-activates**: Polish, refine, enhance keywords
|
||||
**Example**: `/improve messy-code.js --loop`
|
||||
|
||||
#### `--iterations [n]`
|
||||
**What it does**: Control number of improvement cycles (1-10)
|
||||
**When to use**: Controlling iterative enhancement depth
|
||||
**Example**: `/improve --loop --iterations 5`
|
||||
|
||||
#### `--interactive`
|
||||
**What it does**: Enables user confirmation between iterations
|
||||
**When to use**: Want control over iterative process
|
||||
**Example**: `/improve --loop --interactive`
|
||||
|
||||
#### `--concurrency [n]`
|
||||
**What it does**: Control max concurrent sub-agents (1-15)
|
||||
**When to use**: Controlling resource usage
|
||||
**Example**: `/analyze --delegate auto --concurrency 3`
|
||||
|
||||
**💡 Tip**: These are powerful but complex. Start with `--delegate auto` for big projects, `--loop` for improvements.
|
||||
|
||||
---
|
||||
|
||||
### Session & Workflow Flags 🔄
|
||||
|
||||
These V4 Beta flags control session management and advanced workflows.
|
||||
|
||||
#### `--brainstorm`
|
||||
**What it does**: Activates brainstorming mode for requirements discovery
|
||||
**When to use**: Ambiguous project ideas, need specification development
|
||||
**Auto-activates**: Exploration keywords, "not sure", project planning
|
||||
**Example**: `/brainstorm "task management app" --brainstorm`
|
||||
|
||||
#### `--max-rounds [n]`
|
||||
**What it does**: Controls brainstorming dialogue rounds (default: 15)
|
||||
**When to use**: Controlling brainstorming session depth
|
||||
**Example**: `/brainstorm idea --max-rounds 10`
|
||||
|
||||
#### `--prd`
|
||||
**What it does**: Generates Product Requirements Document from brainstorming
|
||||
**When to use**: Convert discussions to formal specifications
|
||||
**Auto-activates**: End of successful brainstorming sessions
|
||||
**Example**: `/brainstorm app-idea --prd`
|
||||
|
||||
**💡 Tip**: V4 Beta introduces powerful session management - let brainstorming mode guide requirement discovery naturally.
|
||||
|
||||
---
|
||||
|
||||
### Focus & Scope Flags 🎯
|
||||
|
||||
Direct SuperClaude's attention to specific areas.
|
||||
|
||||
#### `--scope [level]`
|
||||
**Options**: file, module, project, system
|
||||
**What it does**: Sets analysis scope
|
||||
**Example**: `/analyze --scope module auth/`
|
||||
|
||||
#### `--focus [domain]`
|
||||
**Options**: performance, security, quality, architecture, accessibility, testing
|
||||
**What it does**: Focuses analysis on specific domain
|
||||
**Example**: `/analyze --focus security --scope project`
|
||||
|
||||
#### Agent Flags
|
||||
**Available agents**: system-architect, frontend-specialist, backend-engineer, root-cause-analyzer, security-auditor, code-educator, code-refactorer, performance-optimizer, qa-specialist, devops-engineer, technical-writer, python-ultimate-expert, brainstorm-PRD
|
||||
**What they do**: Activates specialized domain expert agents (V4 Beta enhancement)
|
||||
**Example**: `/analyze --agent security-auditor` - Security-focused analysis with expert agent
|
||||
|
||||
**💡 Tip**: `--focus` is great for targeted analysis. Expert agents auto-activate but manual control helps.
|
||||
|
||||
---
|
||||
|
||||
## Common Flag Patterns 🔄
|
||||
|
||||
### Quick Analysis
|
||||
```bash
|
||||
/sc:analyze src/ --focus quality # Quick quality check
|
||||
/sc:analyze --uc --focus security # Fast security scan
|
||||
```
|
||||
|
||||
### Deep Investigation
|
||||
```bash
|
||||
/sc:troubleshoot "bug" --think --seq # Systematic debugging
|
||||
/sc:analyze --think-hard --focus architecture # Architectural analysis
|
||||
```
|
||||
|
||||
### Large Project Work
|
||||
```bash
|
||||
/sc:analyze monorepo/ --delegate auto --uc # Efficient large analysis
|
||||
/sc:improve legacy/ --wave-mode auto --safe-mode # Safe systematic improvement
|
||||
```
|
||||
|
||||
### Learning & Documentation
|
||||
```bash
|
||||
/sc:explain React hooks --c7 --verbose # Detailed explanation with docs
|
||||
/sc:document api/ --persona-scribe # Professional documentation
|
||||
```
|
||||
|
||||
### Performance-Focused
|
||||
```bash
|
||||
/sc:analyze --focus performance --play # Performance analysis with testing
|
||||
/sc:build --uc --no-mcp # Fast build without extra features
|
||||
```
|
||||
|
||||
### Security-Focused
|
||||
```bash
|
||||
/sc:analyze --focus security --think --validate # Thorough security analysis
|
||||
/sc:scan --persona-security --safe-mode # Conservative security scan
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
|
||||
### Before/After: Basic Analysis
|
||||
**Before** (basic):
|
||||
```bash
|
||||
/sc:analyze auth.js
|
||||
# → Simple file analysis
|
||||
```
|
||||
|
||||
**After** (with flags):
|
||||
```bash
|
||||
/sc:analyze auth.js --focus security --think --c7
|
||||
# → Security-focused analysis with deep thinking and official docs
|
||||
# → Much more thorough, finds security patterns, checks against best practices
|
||||
```
|
||||
|
||||
### Before/After: Large Project
|
||||
**Before** (slow):
|
||||
```bash
|
||||
/sc:analyze huge-monorepo/
|
||||
# → Tries to analyze everything at once, may timeout or use too many tokens
|
||||
```
|
||||
|
||||
**After** (efficient):
|
||||
```bash
|
||||
/sc:analyze huge-monorepo/ --delegate auto --uc --focus architecture
|
||||
# → Delegates work to sub-agents, compresses output, focuses on architecture
|
||||
# → Faster, more focused, better results
|
||||
```
|
||||
|
||||
### Before/After: Improvement Work
|
||||
**Before** (risky):
|
||||
```bash
|
||||
/sc:improve legacy-system/
|
||||
# → May make too many changes, could break things
|
||||
```
|
||||
|
||||
**After** (safe):
|
||||
```bash
|
||||
/sc:improve legacy-system/ --safe-mode --loop --validate --preview
|
||||
# → Safe changes only, iterative approach, validates first, shows preview
|
||||
# → Much safer, progressive improvement
|
||||
```
|
||||
|
||||
## Auto-Activation Examples 🤖
|
||||
|
||||
SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
|
||||
### Complexity-Based
|
||||
```bash
|
||||
/sc:analyze huge-codebase/
|
||||
# Auto-adds: --delegate auto --uc
|
||||
# Why: >50 files detected, context management needed
|
||||
|
||||
/sc:troubleshoot "complex system issue"
|
||||
# Auto-adds: --think --seq
|
||||
# Why: Multi-component problem detected
|
||||
```
|
||||
|
||||
### Domain-Based
|
||||
```bash
|
||||
/sc:build react-app/
|
||||
# Auto-activates: frontend-specialist agent + --c7
|
||||
# Why: Frontend framework detected
|
||||
|
||||
/sc:analyze --focus security
|
||||
# Auto-activates: security-auditor agent + --validate
|
||||
# Why: Security focus triggers security specialist
|
||||
```
|
||||
|
||||
### Performance-Based
|
||||
```bash
|
||||
# When context usage >75%
|
||||
/sc:analyze large-project/
|
||||
# Auto-adds: --uc
|
||||
# Why: Token optimization needed
|
||||
|
||||
# When risk score >0.7
|
||||
/sc:improve production-code/
|
||||
# Auto-adds: --safe-mode --validate
|
||||
# Why: High-risk operation detected
|
||||
```
|
||||
|
||||
## Advanced Usage 🚀
|
||||
|
||||
### Complex Flag Combinations
|
||||
|
||||
**Comprehensive Code Review**:
|
||||
```bash
|
||||
/sc:review codebase/ --agent qa-specialist --think-hard --focus quality --validate --c7
|
||||
# → QA specialist agent + deep thinking + quality focus + validation + docs
|
||||
```
|
||||
|
||||
**Legacy System Modernization**:
|
||||
```bash
|
||||
/sc:improve legacy/ --wave-mode force --agent system-architect --safe-mode --loop --c7
|
||||
# → Wave orchestration + architect agent + safety + iteration + docs
|
||||
```
|
||||
|
||||
**Security Audit**:
|
||||
```bash
|
||||
/sc:scan --agent security-auditor --ultrathink --focus security --validate --seq
|
||||
# → Security auditor agent + maximum thinking + security focus + validation + systematic analysis
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
**For Speed**:
|
||||
```bash
|
||||
/sc:analyze --no-mcp --uc --scope file
|
||||
# → Disable extra features, compress output, limit scope
|
||||
```
|
||||
|
||||
**For Thoroughness**:
|
||||
```bash
|
||||
/sc:analyze --all-mcp --think-hard --delegate auto
|
||||
# → All capabilities, deep thinking, parallel processing
|
||||
```
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
**Bug Investigation Workflow**:
|
||||
```bash
|
||||
/sc:troubleshoot "specific error" --seq --think --validate
|
||||
/sc:analyze affected-files/ --focus quality --agent root-cause-analyzer
|
||||
/sc:test --play --coverage
|
||||
```
|
||||
|
||||
**Feature Development Workflow**:
|
||||
```bash
|
||||
/sc:design new-feature --agent system-architect --c7
|
||||
/sc:build --magic --agent frontend-specialist --validate
|
||||
/sc:test --play --coverage
|
||||
/sc:document --agent technical-writer --c7
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Most Useful Flags
|
||||
| Flag | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| `--think` | Deeper analysis | Complex problems |
|
||||
| `--uc` | Compress output | Large operations |
|
||||
| `--safe-mode` | Conservative execution | Important code |
|
||||
| `--c7` | Official docs | Framework work |
|
||||
| `--seq` | Systematic analysis | Debugging |
|
||||
| `--focus security` | Security focus | Security concerns |
|
||||
| `--delegate auto` | Parallel processing | Large codebases |
|
||||
| `--validate` | Check before action | Risky operations |
|
||||
| `--brainstorm` | Requirements discovery | Ambiguous projects |
|
||||
| `--serena` | Semantic analysis | Symbol operations |
|
||||
|
||||
### Flag Combinations That Work Well
|
||||
```bash
|
||||
# Safe improvement
|
||||
--safe-mode --validate --preview
|
||||
|
||||
# Deep analysis
|
||||
--think --seq --c7
|
||||
|
||||
# Large project
|
||||
--delegate auto --uc --focus
|
||||
|
||||
# Learning
|
||||
--verbose --c7 --agent code-educator
|
||||
|
||||
# Security work
|
||||
--agent security-auditor --focus security --validate
|
||||
|
||||
# Performance work
|
||||
--agent performance-optimizer --focus performance --play
|
||||
|
||||
# Requirements discovery
|
||||
--brainstorm --max-rounds 10 --prd
|
||||
```
|
||||
|
||||
### Auto-Activation Triggers
|
||||
- **--think**: Complex imports, cross-module calls
|
||||
- **--uc**: Context >75%, large operations
|
||||
- **--safe-mode**: Resource usage >85%, production
|
||||
- **--delegate**: >7 directories or >50 files
|
||||
- **--c7**: Framework imports, documentation requests
|
||||
- **--seq**: Debugging keywords, --think flags
|
||||
- **--serena**: Symbol operations, memory commands
|
||||
- **--brainstorm**: Exploration keywords, ambiguous requests
|
||||
- **Expert Agents**: Domain-specific keywords and patterns
|
||||
|
||||
## Troubleshooting Flag Issues 🚨
|
||||
|
||||
### Common Problems
|
||||
|
||||
**"Flags don't seem to work"**
|
||||
- Check spelling (common typos: `--ultracompresed`, `--agent fronted-specialist`)
|
||||
- Some flags need values: `--scope project`, `--focus security`
|
||||
- Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, `--serena`, etc.
|
||||
|
||||
**"Operation too slow"**
|
||||
- Try `--uc` for compression
|
||||
- Use `--no-mcp` to disable extra features
|
||||
- Limit scope: `--scope file` instead of `--scope project`
|
||||
|
||||
**"Too much output"**
|
||||
- Add `--uc` for compression
|
||||
- Remove `--verbose` if present
|
||||
- Use `--answer-only` for simple questions
|
||||
|
||||
**"Not thorough enough"**
|
||||
- Add `--think` or `--think-hard`
|
||||
- Enable relevant MCP servers: `--seq`, `--c7`
|
||||
- Use appropriate agent: `--agent root-cause-analyzer`
|
||||
|
||||
**"Changes too risky"**
|
||||
- Always use `--safe-mode` for important code
|
||||
- Add `--validate` to check first
|
||||
- Use `--preview` to see changes before applying
|
||||
|
||||
### Flag Conflicts
|
||||
|
||||
**These override others**:
|
||||
- `--no-mcp` overrides all MCP flags (`--c7`, `--seq`, `--serena`, etc.)
|
||||
- `--safe-mode` overrides optimization flags
|
||||
- Last agent flag wins: `--agent frontend-specialist --agent backend-engineer` → backend-engineer
|
||||
|
||||
**Precedence order**:
|
||||
1. Safety flags (`--safe-mode`) beat optimization
|
||||
2. Explicit flags beat auto-activation
|
||||
3. Thinking depth: `--ultrathink` > `--think-hard` > `--think`
|
||||
4. Scope: system > project > module > file
|
||||
|
||||
## Tips for Effective Flag Usage 💡
|
||||
|
||||
### Starting Out (The Honest Truth)
|
||||
1. **Just ignore flags at first** - Auto-activation handles most cases pretty well
|
||||
2. **Watch what gets auto-activated** - You'll learn by seeing what SuperClaude picks
|
||||
3. **Use `--help` when curious** - Many commands show what flags are available
|
||||
4. **Trust the automation** - SuperClaude usually picks reasonable defaults
|
||||
|
||||
### Getting Advanced (If You Want To)
|
||||
1. **Experiment with overrides** - Try `--agent security-auditor` on non-security code for different perspectives
|
||||
2. **Learn the useful combos** - `--safe-mode --validate` for important stuff, `--brainstorm --prd` for new projects
|
||||
3. **Understand the performance trade-offs** - Fast (`--uc --no-mcp`) vs thorough (`--think-hard --all-mcp`)
|
||||
4. **Use flags for learning** - `--verbose` when you want to understand what's happening
|
||||
|
||||
### Performance Tips (For Power Users)
|
||||
- **For speed**: `--uc --no-mcp --scope file`
|
||||
- **For thoroughness**: `--think-hard --all-mcp --delegate auto`
|
||||
- **For safety**: `--safe-mode --validate --preview`
|
||||
- **For learning**: `--verbose --c7 --agent code-educator`
|
||||
- **For project discovery**: `--brainstorm --max-rounds 15 --prd`
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**The real truth about flags** 💯:
|
||||
- **Auto-activation usually works pretty well** compared to manual flag selection
|
||||
- **You can ignore most of this guide** and just use basic commands
|
||||
- **Flags are here when you want them** - not because you need them
|
||||
- **Learning happens naturally** through use, not through studying guides 😊
|
||||
|
||||
**Don't feel overwhelmed** 🧘♂️:
|
||||
- SuperClaude tries to work well without flag knowledge
|
||||
- The detailed info above is for curiosity, not necessity
|
||||
- Auto-activation keeps getting smarter based on usage patterns
|
||||
- You're not missing out by not memorizing flags
|
||||
|
||||
**When you actually need flags**:
|
||||
- Overriding auto-activation (rare)
|
||||
- Experimenting with different approaches (fun)
|
||||
- Optimizing for specific performance needs (advanced)
|
||||
- Learning about what happened (educational)
|
||||
|
||||
**Start simple, stay simple** 🎯:
|
||||
- Use basic commands: `/analyze`, `/build`, `/improve`
|
||||
- Let auto-activation handle the complexity
|
||||
- Add manual flags only when you want to experiment
|
||||
- Trust that SuperClaude knows what it's doing
|
||||
|
||||
---
|
||||
|
||||
*Remember: Behind all this apparent complexity, SuperClaude is actually simple to use. Just start typing commands! 🚀*
|
||||
@@ -1,631 +0,0 @@
|
||||
# SuperClaude V4 Beta Installation Guide 📦
|
||||
|
||||
## 🎯 It's Easier Than It Looks!
|
||||
|
||||
**The honest truth**: This guide looks long because we want to cover all the details, but installation is actually pretty simple. Most people are done in 2 minutes with one command!
|
||||
|
||||
### Step 1: Install the Package
|
||||
|
||||
**Option A: From PyPI (Recommended)**
|
||||
```bash
|
||||
uv add SuperClaude
|
||||
```
|
||||
|
||||
**Option B: From Source**
|
||||
```bash
|
||||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
uv sync
|
||||
```
|
||||
### 🔧 UV / UVX Setup Guide
|
||||
|
||||
SuperClaude V4 Beta supports installation via [`uv`](https://github.com/astral-sh/uv) (a faster, modern Python package manager) or `uvx` for cross-platform usage.
|
||||
|
||||
### 🌀 Install with `uv`
|
||||
|
||||
Make sure `uv` is installed:
|
||||
|
||||
```bash
|
||||
curl -Ls https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
> Or follow instructions from: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)
|
||||
|
||||
Once `uv` is available, you can install SuperClaude like this:
|
||||
|
||||
```bash
|
||||
uv venv
|
||||
source .venv/bin/activate
|
||||
uv pip install SuperClaude
|
||||
```
|
||||
|
||||
### ⚡ Install with `uvx` (Cross-platform CLI)
|
||||
|
||||
If you’re using `uvx`, just run:
|
||||
|
||||
```bash
|
||||
uvx pip install SuperClaude
|
||||
```
|
||||
## 🔧 UV / UVX Setup Guide
|
||||
|
||||
SuperClaude V4 Beta supports installation via [`uv`](https://github.com/astral-sh/uv) (a faster, modern Python package manager) or `uvx` for cross-platform usage.
|
||||
|
||||
### 🌀 Install with `uv`
|
||||
|
||||
Make sure `uv` is installed:
|
||||
|
||||
```bash
|
||||
curl -Ls https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
> Or follow instructions from: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)
|
||||
|
||||
Once `uv` is available, you can install SuperClaude like this:
|
||||
|
||||
```bash
|
||||
uv venv
|
||||
source .venv/bin/activate
|
||||
uv pip install SuperClaude
|
||||
```
|
||||
|
||||
### ⚡ Install with `uvx` (Cross-platform CLI)
|
||||
|
||||
If you’re using `uvx`, just run:
|
||||
|
||||
```bash
|
||||
uvx pip install SuperClaude
|
||||
```
|
||||
|
||||
### ✅ Finish Installation
|
||||
|
||||
After installing, continue with the usual installer step:
|
||||
|
||||
```bash
|
||||
python3 -m SuperClaude install
|
||||
```
|
||||
|
||||
Or using bash-style CLI:
|
||||
|
||||
```bash
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
### 🧠 Note:
|
||||
|
||||
* `uv` provides better caching and performance.
|
||||
* Compatible with Python 3.8+ and works smoothly with SuperClaude.
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ Important Note
|
||||
**After installing the SuperClaude.**
|
||||
**You can use `SuperClaude commands`
|
||||
, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`**
|
||||
|
||||
**What just happened?** SuperClaude tried to set up everything you need. Usually no complex configuration, dependency hunting, or setup headaches! 🎉
|
||||
|
||||
---
|
||||
|
||||
A comprehensive guide to installing SuperClaude V4 Beta. But remember - most people never need to read past the quick start above! 😊
|
||||
|
||||
## Before You Start 🔍
|
||||
|
||||
### What You Need 💻
|
||||
|
||||
SuperClaude works on **Windows**, **macOS**, and **Linux**. Here's what you need:
|
||||
|
||||
**Required:**
|
||||
- **Python 3.8 or newer** - The framework is written in Python
|
||||
- **Claude CLI** - SuperClaude enhances Claude Code, so you need it installed first
|
||||
|
||||
**Optional (but recommended):**
|
||||
- **Node.js 16+** - Only needed if you want MCP server integration
|
||||
- **Git** - Helpful for development workflows
|
||||
|
||||
### Quick Check 🔍
|
||||
|
||||
Before installing, let's make sure you have the basics:
|
||||
|
||||
```bash
|
||||
# Check Python version (should be 3.8+)
|
||||
python3 --version
|
||||
|
||||
# Check if Claude CLI is installed
|
||||
claude --version
|
||||
|
||||
# Check Node.js (optional, for MCP servers)
|
||||
node --version
|
||||
```
|
||||
|
||||
If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below.
|
||||
|
||||
## Quick Start 🚀
|
||||
|
||||
**🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)**
|
||||
**Option A: From PyPI (Recommended)**
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
|
||||
# Install with recommended settings
|
||||
SuperClaude install --quick
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
**Option B: From Source**
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone <repository-url>
|
||||
cd SuperClaude
|
||||
pip install .
|
||||
|
||||
# Install with recommended settings
|
||||
SuperClaude install --quick
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
**⚠️ Important Note**
|
||||
**After installing the SuperClaude.**
|
||||
**You can use `SuperClaude commands`
|
||||
, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`**
|
||||
|
||||
**What you just got:**
|
||||
- ✅ All 16 smart commands that auto-activate experts
|
||||
- ✅ 13 specialized domain expert agents that know when to help
|
||||
- ✅ Advanced session management with brainstorming mode
|
||||
- ✅ Python hooks system for intelligent framework coordination
|
||||
- ✅ Intelligent routing that figures out complexity for you
|
||||
- ✅ About 2 minutes of your time and ~50MB disk space
|
||||
|
||||
**Seriously, you're done.** Open Claude Code, type `/help`, and watch SuperClaude work its magic.
|
||||
|
||||
**Nervous about what it will do?** See first with:
|
||||
```bash
|
||||
SuperClaude install --dry-run
|
||||
```
|
||||
|
||||
## Installation Options 🎯
|
||||
|
||||
### 🎛️ Interactive Two-Stage Installation (Default)
|
||||
```bash
|
||||
SuperClaude install
|
||||
```
|
||||
- **Stage 1**: Select MCP servers (Context7, Sequential, Magic, Playwright, etc.)
|
||||
- **Stage 2**: Choose framework components (Core, Commands, Agents, Modes)
|
||||
- **Time**: ~3-5 minutes depending on selections
|
||||
- **Space**: ~50-100MB depending on selections
|
||||
- **Good for**: All users - gives you full control over what gets installed
|
||||
- **Interactive**: Shows detailed descriptions and lets you pick exactly what you want
|
||||
|
||||
### 🎯 Component-Specific Installation
|
||||
```bash
|
||||
SuperClaude install --components core commands modes
|
||||
```
|
||||
- **What**: Install only specific components you need
|
||||
- **Time**: Variable based on selection
|
||||
- **Space**: Variable based on selection
|
||||
- **Good for**: Users who know exactly what they want
|
||||
- **Available components**: core, commands, agents, modes, mcp, mcp_docs
|
||||
|
||||
## Step-by-Step Installation 📋
|
||||
|
||||
### Prerequisites Setup 🛠️
|
||||
|
||||
**Missing Python?**
|
||||
```bash
|
||||
# Linux (Ubuntu/Debian)
|
||||
sudo apt update && sudo apt install python3 python3-pip
|
||||
|
||||
# macOS
|
||||
brew install python3
|
||||
|
||||
# Windows
|
||||
# Download from https://python.org/downloads/
|
||||
#or open command prompt or powershell
|
||||
winget install python
|
||||
```
|
||||
|
||||
**Missing Claude CLI?**
|
||||
- Visit https://claude.ai/code for installation instructions
|
||||
- SuperClaude enhances Claude Code, so you need it first
|
||||
|
||||
**Missing Node.js? (Optional)**
|
||||
```bash
|
||||
# Linux (Ubuntu/Debian)
|
||||
sudo apt update && sudo apt install nodejs npm
|
||||
|
||||
# macOS
|
||||
brew install node
|
||||
|
||||
# Windows
|
||||
# Download from https://nodejs.org/
|
||||
#or open command prompt or powershell
|
||||
winget install nodejs
|
||||
```
|
||||
|
||||
### Getting SuperClaude 📥
|
||||
|
||||
**Option 1: From PyPI (Recommended)**
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
```
|
||||
|
||||
**Option 2: Download the latest release**
|
||||
```bash
|
||||
# Download and extract the latest release
|
||||
# (Replace URL with actual release URL)
|
||||
curl -L <release-url> -o superclaude-v3.zip
|
||||
unzip superclaude-v3.zip
|
||||
cd superclaude-v3
|
||||
pip install .
|
||||
```
|
||||
|
||||
**Option 3: Clone from Git**
|
||||
```bash
|
||||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
pip install .
|
||||
```
|
||||
|
||||
### Running the Installer 🎬
|
||||
|
||||
The installer is pretty smart and will guide you through the process:
|
||||
|
||||
```bash
|
||||
# See all available options
|
||||
SuperClaude install --help
|
||||
|
||||
# Interactive installation (recommended)
|
||||
SuperClaude install
|
||||
|
||||
# Want to see what would happen first?
|
||||
SuperClaude install --dry-run
|
||||
|
||||
# Install everything
|
||||
SuperClaude install --components core commands agents modes mcp mcp_docs
|
||||
|
||||
# Quiet installation (minimal output)
|
||||
SuperClaude install --quiet
|
||||
|
||||
# Force installation (skip confirmations)
|
||||
python3 SuperClaude.py install --quick --force
|
||||
```
|
||||
|
||||
### During Installation 📱
|
||||
|
||||
Here's what happens when you install:
|
||||
|
||||
1. **System Check** - Verifies you have required dependencies
|
||||
2. **Directory Setup** - Creates `~/.claude/` directory structure
|
||||
3. **Core Files** - Copies framework documentation files
|
||||
4. **Commands** - Installs slash command definitions (if selected)
|
||||
5. **MCP Servers** - Downloads and configures MCP servers (if selected)
|
||||
6. **Configuration** - Sets up framework settings and CLAUDE.md imports
|
||||
7. **Settings** - Sets up `settings.json` with your preferences
|
||||
8. **Validation** - Tests that everything works
|
||||
|
||||
The installer shows progress and will tell you if anything goes wrong.
|
||||
|
||||
## After Installation ✅
|
||||
|
||||
### Quick Test 🧪
|
||||
|
||||
Let's make sure everything worked:
|
||||
|
||||
```bash
|
||||
# Check if files were installed
|
||||
ls ~/.claude/
|
||||
|
||||
# Should show: CLAUDE.md, COMMANDS.md, settings.json, etc.
|
||||
```
|
||||
|
||||
**Test with Claude Code:**
|
||||
1. Open Claude Code
|
||||
2. Try typing `/help` - you should see SuperClaude commands
|
||||
3. Try `/analyze --help` - should show command options
|
||||
|
||||
### What Got Installed 📂
|
||||
|
||||
SuperClaude V4 Beta installs to `~/.claude/` by default. Here's what you'll find:
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── CLAUDE.md # Main framework entry point
|
||||
├── FLAGS.md # Command flags and options
|
||||
├── PRINCIPLES.md # Development principles
|
||||
├── RULES.md # Operational rules
|
||||
├── ORCHESTRATOR.md # Intelligent routing
|
||||
├── MCP_*.md # MCP server configurations
|
||||
├── MODE_*.md # Operational modes
|
||||
├── SESSION_LIFECYCLE.md # Session management
|
||||
├── settings.json # Configuration file
|
||||
└── commands/ # Individual command definitions
|
||||
├── analyze.md
|
||||
├── build.md
|
||||
├── improve.md
|
||||
└── ... (13 more)
|
||||
```
|
||||
|
||||
**For Developer Installation (+Hooks System)**:
|
||||
```
|
||||
~/.claude/
|
||||
├── [above files] # Core framework files
|
||||
└── backups/ # Installation backups
|
||||
├── framework_coordinator/
|
||||
├── session_lifecycle/
|
||||
├── performance_monitor/
|
||||
├── quality_gates/
|
||||
└── install_hooks.py # Hook installation script
|
||||
```
|
||||
|
||||
**What each file does:**
|
||||
- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files
|
||||
- **settings.json** - Configuration (MCP servers, hooks, etc.)
|
||||
- **commands/** - Detailed definitions for each slash command
|
||||
- **hooks/** - Python hooks for advanced framework coordination (developer only)
|
||||
|
||||
### First Steps 🎯
|
||||
|
||||
Try these commands to get started:
|
||||
|
||||
```bash
|
||||
# In Claude Code, try these:
|
||||
/sc:help # See available commands
|
||||
/sc:analyze README.md # Analyze a file
|
||||
/sc:build --help # See build options
|
||||
/sc:improve --help # See improvement options
|
||||
/sc:brainstorm "my app idea" # Try V4 Beta brainstorming mode
|
||||
```
|
||||
|
||||
**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want.
|
||||
|
||||
### Installing Hooks System (V4 Beta) 🔗
|
||||
|
||||
If you want to add the Python hooks system to an existing installation:
|
||||
|
||||
```bash
|
||||
# Install hooks to existing SuperClaude installation
|
||||
cd SuperClaude_Framework
|
||||
python3 SuperClaude/Hooks/scripts/install_hooks.py
|
||||
|
||||
# Or upgrade existing installation with hooks
|
||||
SuperClaude install --upgrade --hooks
|
||||
```
|
||||
|
||||
**What the hooks system provides:**
|
||||
- **Framework Coordinator**: Intelligent MCP server suggestions
|
||||
- **Session Lifecycle**: Automatic checkpoint triggers
|
||||
- **Performance Monitor**: Real-time performance tracking (<100ms targets)
|
||||
- **Quality Gates**: 8-step validation system
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
# Test hooks installation
|
||||
python3 SuperClaude/Hooks/scripts/test_hooks.py
|
||||
|
||||
# Check hook status
|
||||
SuperClaude hooks --status
|
||||
```
|
||||
|
||||
## Managing Your Installation 🛠️
|
||||
|
||||
### Updates 📅
|
||||
|
||||
Keep SuperClaude up to date:
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
SuperClaude update
|
||||
|
||||
# Force update (overwrite local changes)
|
||||
SuperClaude update --force
|
||||
|
||||
# Update specific components only
|
||||
SuperClaude update --components core,commands
|
||||
|
||||
# See what would be updated
|
||||
SuperClaude update --dry-run
|
||||
```
|
||||
|
||||
**When to update:**
|
||||
- When new SuperClaude versions are released
|
||||
- If you're having issues (updates often include fixes)
|
||||
- When new MCP servers become available
|
||||
|
||||
### Backups 💾
|
||||
|
||||
Create backups before major changes:
|
||||
|
||||
```bash
|
||||
# Create a backup
|
||||
SuperClaude backup --create
|
||||
|
||||
# List existing backups
|
||||
SuperClaude backup --list
|
||||
|
||||
# Restore from backup
|
||||
SuperClaude backup --restore
|
||||
|
||||
# Create backup with custom name
|
||||
SuperClaude backup --create --name "before-update"
|
||||
```
|
||||
|
||||
**When to backup:**
|
||||
- Before updating SuperClaude
|
||||
- Before experimenting with settings
|
||||
- Before uninstalling
|
||||
- Periodically if you've customized heavily
|
||||
|
||||
### Uninstallation 🗑️
|
||||
|
||||
If you need to remove SuperClaude:
|
||||
|
||||
```bash
|
||||
# Remove SuperClaude (keeps backups)
|
||||
SuperClaude uninstall
|
||||
|
||||
# Complete removal (removes everything)
|
||||
SuperClaude uninstall --complete
|
||||
|
||||
# See what would be removed
|
||||
SuperClaude uninstall --dry-run
|
||||
```
|
||||
|
||||
**What gets removed:**
|
||||
- All files in `~/.claude/`
|
||||
- MCP server configurations
|
||||
- SuperClaude settings from Claude Code
|
||||
|
||||
**What stays:**
|
||||
- Your backups (unless you use `--complete`)
|
||||
- Claude Code itself (SuperClaude doesn't touch it)
|
||||
- Your projects and other files
|
||||
|
||||
## Troubleshooting 🔧
|
||||
|
||||
### Common Issues 🚨
|
||||
|
||||
**"Python not found"**
|
||||
```bash
|
||||
# Try python instead of python3
|
||||
python --version
|
||||
|
||||
# Or check if it's installed but not in PATH
|
||||
which python3
|
||||
```
|
||||
|
||||
**"Claude CLI not found"**
|
||||
- Make sure Claude Code is installed first
|
||||
- Try `claude --version` to verify
|
||||
- Visit https://claude.ai/code for installation help
|
||||
|
||||
**"Permission denied"**
|
||||
```bash
|
||||
# Try with explicit Python path
|
||||
/usr/bin/python3 SuperClaude.py install --quick
|
||||
|
||||
# Or check if you need different permissions
|
||||
ls -la ~/.claude/
|
||||
```
|
||||
|
||||
**"MCP servers won't install"**
|
||||
- Check that Node.js is installed: `node --version`
|
||||
- Check that npm is available: `npm --version`
|
||||
- Try installing without MCP first: `--minimal` or `--quick`
|
||||
|
||||
**"Installation fails partway through"**
|
||||
```bash
|
||||
# Try with verbose output to see what's happening
|
||||
SuperClaude install --quick --verbose
|
||||
|
||||
# Or try a dry run first
|
||||
SuperClaude install --quick --dry-run
|
||||
```
|
||||
|
||||
### Platform-Specific Issues 🖥️
|
||||
|
||||
**Windows:**
|
||||
- Use `python` instead of `python3` if you get "command not found"
|
||||
- Run Command Prompt as Administrator if you get permission errors
|
||||
- Make sure Python is in your PATH
|
||||
|
||||
**macOS:**
|
||||
- You might need to approve SuperClaude in Security & Privacy settings
|
||||
- Use `brew install python3` if you don't have Python 3.8+
|
||||
- Try using `python3` explicitly instead of `python`
|
||||
|
||||
**Linux:**
|
||||
- Make sure you have `python3-pip` installed
|
||||
- You might need `sudo` for some package installations
|
||||
- Check that `~/.local/bin` is in your PATH
|
||||
|
||||
### Still Having Issues? 🤔
|
||||
|
||||
**Check our troubleshooting resources:**
|
||||
- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
|
||||
- Look for existing issues similar to yours
|
||||
- Create a new issue if you can't find a solution
|
||||
|
||||
**When reporting bugs, please include:**
|
||||
- Your operating system and version
|
||||
- Python version (`python3 --version`)
|
||||
- Claude CLI version (`claude --version`)
|
||||
- The exact command you ran
|
||||
- The complete error message
|
||||
- What you expected to happen
|
||||
|
||||
**Getting Help:**
|
||||
- GitHub Discussions for general questions
|
||||
- Check the README.md for latest updates
|
||||
- Look at the ROADMAP.md to see if your issue is known
|
||||
|
||||
## Advanced Options ⚙️
|
||||
|
||||
### Custom Installation Directory
|
||||
|
||||
```bash
|
||||
# Install to custom location
|
||||
SuperClaude install --quick --install-dir /custom/path
|
||||
|
||||
# Use environment variable
|
||||
export SUPERCLAUDE_DIR=/custom/path
|
||||
SuperClaude install --quick
|
||||
```
|
||||
|
||||
### Component Selection
|
||||
|
||||
```bash
|
||||
# See available components
|
||||
SuperClaude install --list-components
|
||||
|
||||
# Install specific components only
|
||||
SuperClaude install --components core,commands
|
||||
|
||||
# Skip certain components
|
||||
SuperClaude install --quick --skip mcp
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
If you're planning to contribute or modify SuperClaude:
|
||||
|
||||
```bash
|
||||
# Developer installation with all components
|
||||
SuperClaude install --components core commands agents modes mcp mcp_docs
|
||||
|
||||
# Install in development mode
|
||||
SuperClaude install --dev-mode
|
||||
```
|
||||
|
||||
## What's Next? 🚀
|
||||
|
||||
**Now that SuperClaude is installed (that was easy, right?):**
|
||||
|
||||
1. **Just start using it** - Try `/analyze some-file.js` or `/build` and see what happens ✨
|
||||
2. **Don't stress about learning** - SuperClaude usually figures out what you need
|
||||
3. **Experiment freely** - Commands like `/improve` and `/troubleshoot` are pretty forgiving
|
||||
4. **Read guides if curious** - Check `Docs/` when you want to understand what just happened
|
||||
5. **Give feedback** - Let us know what works and what doesn't
|
||||
|
||||
**The real secret**: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯
|
||||
|
||||
**Still feeling uncertain?** Start with just `/help` and `/analyze README.md` - you'll see how non-intimidating it actually is.
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
- **Installation takes 1-5 minutes** depending on what you choose
|
||||
- **Disk space needed: 20-100MB** (not much!)
|
||||
- **Works alongside existing tools** - doesn't interfere with your setup
|
||||
- **Easy to uninstall** if you change your mind
|
||||
- **Community supported** - we actually read and respond to issues
|
||||
- ### ⚠️ Important Note
|
||||
**After installing the SuperClaude.**
|
||||
**You can use `SuperClaude commands`
|
||||
, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`**
|
||||
|
||||
Thanks for trying SuperClaude! We hope it makes your development workflow a bit smoother. 🙂
|
||||
|
||||
---
|
||||
|
||||
*Last updated: January 2025 (V4 Beta) - Let us know if anything in this guide is wrong or confusing!*
|
||||
@@ -1,871 +0,0 @@
|
||||
# SuperClaude Personas User Guide 🎭
|
||||
|
||||
## 🎭 Personas Auto-Activate - No Need to Choose!
|
||||
|
||||
**The simple truth**: You don't need to pick personas or memorize what they do. SuperClaude usually tries to bring in helpful experts for each situation!
|
||||
|
||||
**Here's what actually happens:**
|
||||
- You type `/analyze auth.js` → Security expert usually jumps in 🛡️
|
||||
- You work on React components → Frontend specialist often takes over 🎨
|
||||
- You debug performance issues → Performance optimizer often helps ⚡
|
||||
- You write documentation → Professional 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.
|
||||
|
||||
**Manual control available** when you want it (like asking specifically for a security review of frontend code), but most of the time you can just... let it work. 🪄
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Just Try These (No Persona Knowledge Required)
|
||||
|
||||
```bash
|
||||
# These automatically activate the right experts:
|
||||
/sc:analyze payment-system/ # → Security + backend experts auto-activate
|
||||
/sc:build react-app/ # → Frontend specialist takes over
|
||||
/sc:improve slow-queries.sql # → Performance optimizer jumps in
|
||||
/sc:troubleshoot "auth failing" # → Debug specialist + security expert coordinate
|
||||
```
|
||||
|
||||
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. Everything below is for when you get curious about who's on the team.
|
||||
|
||||
---
|
||||
|
||||
Think of SuperClaude personas as having a team of specialists on demand. Each persona brings different expertise, priorities, and perspectives to help you with specific types of work.
|
||||
|
||||
## What Are Personas? 🤔
|
||||
|
||||
**Personas are AI specialists** that try to adapt SuperClaude's behavior for different types of work. Instead of generic responses, you often get expert-level help from relevant specialists.
|
||||
|
||||
**How they actually work in practice:**
|
||||
- **Auto-activation** - SuperClaude usually tries to pick helpful experts (most of the time this works pretty well!)
|
||||
- **Smart detection** - Recognizes security work, frontend tasks, performance issues, etc.
|
||||
- **Seamless switching** - Different experts jump in as needed within the same conversation
|
||||
- **Team coordination** - Multiple experts often coordinate on complex tasks
|
||||
- **Manual override available** - You can explicitly choose with `--persona-name` flags when you want a different perspective
|
||||
|
||||
**Why this matters:**
|
||||
- Often get expert-level advice without knowing which expert to ask
|
||||
- Usually get better decision-making aligned with what you're actually working on
|
||||
- More focused and relevant responses based on the task
|
||||
- Access to specialized workflows that activate when useful
|
||||
|
||||
**The neat part**: You just work on your stuff, and helpful experts usually show up when needed. 🎯
|
||||
|
||||
## The SuperClaude Team 👥
|
||||
|
||||
### Technical Specialists 🔧
|
||||
|
||||
#### 🏗️ `architect` - Systems Design Specialist
|
||||
**What they do**: Long-term architecture planning, system design, scalability decisions
|
||||
|
||||
**Priority**: Long-term maintainability > scalability > performance > quick fixes
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "architecture", "design", "scalability", "system structure"
|
||||
- Complex system modifications involving multiple modules
|
||||
- Planning large features or system changes
|
||||
|
||||
**Great for**:
|
||||
- Planning new systems or major features
|
||||
- Architectural reviews and improvements
|
||||
- Technical debt assessment
|
||||
- Design pattern recommendations
|
||||
- Scalability planning
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:design microservices-migration --persona-architect
|
||||
/sc:analyze --focus architecture large-system/
|
||||
/sc:estimate "redesign auth system" --persona-architect
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Maintainable, understandable code
|
||||
- Loose coupling, high cohesion
|
||||
- Future-proof design decisions
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
#### 🎨 `frontend` - UI/UX & Accessibility Expert
|
||||
**What they do**: User experience, accessibility, frontend performance, design systems
|
||||
|
||||
**Priority**: User needs > accessibility > performance > technical elegance
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "component", "responsive", "accessibility", "UI", "UX"
|
||||
- Frontend development work
|
||||
- User interface related tasks
|
||||
|
||||
**Great for**:
|
||||
- Building UI components
|
||||
- Accessibility compliance (WCAG 2.1 AA)
|
||||
- Frontend performance optimization
|
||||
- Design system work
|
||||
- User experience improvements
|
||||
|
||||
**Performance budgets they enforce**:
|
||||
- Load time: <3s on 3G, <1s on WiFi
|
||||
- Bundle size: <500KB initial, <2MB total
|
||||
- Accessibility: WCAG compliance target
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:build dashboard --persona-frontend
|
||||
/sc:improve --focus accessibility components/
|
||||
/sc:analyze --persona-frontend --focus performance
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Intuitive, user-friendly interfaces
|
||||
- Accessibility for all users
|
||||
- Real-world performance on mobile/3G
|
||||
- Clean, maintainable CSS/JS
|
||||
|
||||
---
|
||||
|
||||
#### ⚙️ `backend` - API & Infrastructure Specialist
|
||||
**What they do**: Server-side development, APIs, databases, reliability engineering
|
||||
|
||||
**Priority**: Reliability > security > performance > features > convenience
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "API", "database", "service", "server", "reliability"
|
||||
- Backend development work
|
||||
- Infrastructure or data-related tasks
|
||||
|
||||
**Great for**:
|
||||
- API design and implementation
|
||||
- Database schema and optimization
|
||||
- Security implementation
|
||||
- Reliability and error handling
|
||||
- Backend performance tuning
|
||||
|
||||
**Reliability budgets they enforce**:
|
||||
- Uptime: 99.9% (8.7h/year downtime)
|
||||
- Error rate: <0.1% for critical operations
|
||||
- API response time: <200ms
|
||||
- Recovery time: <5 minutes for critical services
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:design user-api --persona-backend
|
||||
/sc:analyze --focus security api/
|
||||
/sc:improve --persona-backend database-layer/
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Rock-solid reliability and uptime
|
||||
- Security by default (zero trust)
|
||||
- Data integrity and consistency
|
||||
- Graceful error handling
|
||||
|
||||
---
|
||||
|
||||
#### 🛡️ `security` - Threat Modeling & Vulnerability Expert
|
||||
**What they do**: Security analysis, threat modeling, vulnerability assessment, compliance
|
||||
|
||||
**Priority**: Security > compliance > reliability > performance > convenience
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "security", "vulnerability", "auth", "compliance"
|
||||
- Security scanning or assessment work
|
||||
- Authentication/authorization tasks
|
||||
|
||||
**Great for**:
|
||||
- Security audits and vulnerability scanning
|
||||
- Threat modeling and risk assessment
|
||||
- Secure coding practices
|
||||
- Compliance requirements (OWASP, etc.)
|
||||
- Authentication and authorization systems
|
||||
|
||||
**Threat assessment levels**:
|
||||
- Critical: Immediate action required
|
||||
- High: Fix within 24 hours
|
||||
- Medium: Fix within 7 days
|
||||
- Low: Fix within 30 days
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:scan --persona-security --focus security
|
||||
/sc:analyze auth-system/ --persona-security
|
||||
/sc:improve --focus security --persona-security
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Security by default, fail-safe mechanisms
|
||||
- Zero trust architecture principles
|
||||
- Defense in depth strategies
|
||||
- Clear security documentation
|
||||
|
||||
---
|
||||
|
||||
#### ⚡ `performance` - Optimization & Bottleneck Specialist
|
||||
**What they do**: Performance optimization, bottleneck identification, metrics analysis
|
||||
|
||||
**Priority**: Measure first > optimize critical path > user experience > avoid premature optimization
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "performance", "optimization", "speed", "bottleneck"
|
||||
- Performance analysis or optimization work
|
||||
- When speed/efficiency is mentioned
|
||||
|
||||
**Great for**:
|
||||
- Performance bottleneck identification
|
||||
- Code optimization with metrics validation
|
||||
- Database query optimization
|
||||
- Frontend performance tuning
|
||||
- Load testing and capacity planning
|
||||
|
||||
**Performance budgets they track**:
|
||||
- API responses: <500ms
|
||||
- Database queries: <100ms
|
||||
- Bundle size: <500KB initial
|
||||
- Memory usage: <100MB mobile, <500MB desktop
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:analyze --focus performance --persona-performance
|
||||
/sc:improve --type performance slow-endpoints/
|
||||
/sc:test --benchmark --persona-performance
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Measurement-driven optimization
|
||||
- Real user experience improvements
|
||||
- Critical path performance
|
||||
- Systematic optimization methodology
|
||||
|
||||
### Process & Quality Experts ✨
|
||||
|
||||
#### 🔍 `analyzer` - Root Cause Investigation Specialist
|
||||
**What they do**: Systematic debugging, root cause analysis, evidence-based investigation
|
||||
|
||||
**Priority**: Evidence > systematic approach > thoroughness > speed
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "analyze", "investigate", "debug", "root cause"
|
||||
- Debugging or troubleshooting sessions
|
||||
- Complex problem investigation
|
||||
|
||||
**Great for**:
|
||||
- Debugging complex issues
|
||||
- Root cause analysis
|
||||
- System investigation
|
||||
- Evidence-based problem solving
|
||||
- Understanding unknown codebases
|
||||
|
||||
**Investigation methodology**:
|
||||
1. Evidence collection before conclusions
|
||||
2. Pattern recognition in data
|
||||
3. Hypothesis testing and validation
|
||||
4. Root cause confirmation through tests
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:troubleshoot "auth randomly fails" --persona-analyzer
|
||||
/sc:analyze --persona-analyzer mysterious-bug/
|
||||
/sc:explain --detailed "why is this slow" --persona-analyzer
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Evidence-based conclusions
|
||||
- Systematic investigation methods
|
||||
- Complete analysis before solutions
|
||||
- Reproducible findings
|
||||
|
||||
---
|
||||
|
||||
#### 🧪 `qa` - Quality Assurance & Testing Expert
|
||||
**What they do**: Testing strategy, quality gates, edge case detection, risk assessment
|
||||
|
||||
**Priority**: Prevention > detection > correction > comprehensive coverage
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "test", "quality", "validation", "coverage"
|
||||
- Testing or quality assurance work
|
||||
- Quality gates or edge cases mentioned
|
||||
|
||||
**Great for**:
|
||||
- Test strategy and planning
|
||||
- Quality assurance processes
|
||||
- Edge case identification
|
||||
- Risk-based testing
|
||||
- Test automation
|
||||
|
||||
**Quality risk assessment**:
|
||||
- Critical path analysis for user journeys
|
||||
- Failure impact evaluation
|
||||
- Defect probability assessment
|
||||
- Recovery difficulty estimation
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:test --persona-qa comprehensive-suite
|
||||
/sc:analyze --focus quality --persona-qa
|
||||
/sc:review --persona-qa critical-features/
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Preventing defects over finding them
|
||||
- Comprehensive test coverage
|
||||
- Risk-based testing priorities
|
||||
- Quality built into the process
|
||||
|
||||
---
|
||||
|
||||
#### 🔄 `refactorer` - Code Quality & Cleanup Specialist
|
||||
**What they do**: Code quality improvement, technical debt management, clean code practices
|
||||
|
||||
**Priority**: Simplicity > maintainability > readability > performance > cleverness
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "refactor", "cleanup", "quality", "technical debt"
|
||||
- Code improvement or cleanup work
|
||||
- Maintainability concerns
|
||||
|
||||
**Great for**:
|
||||
- Code refactoring and cleanup
|
||||
- Technical debt reduction
|
||||
- Code quality improvements
|
||||
- Design pattern application
|
||||
- Legacy code modernization
|
||||
|
||||
**Code quality metrics they track**:
|
||||
- Cyclomatic complexity
|
||||
- Code readability scores
|
||||
- Technical debt ratio
|
||||
- Test coverage
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:improve --type quality --persona-refactorer
|
||||
/sc:cleanup legacy-module/ --persona-refactorer
|
||||
/sc:analyze --focus maintainability --persona-refactorer
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Simple, readable solutions
|
||||
- Consistent patterns and conventions
|
||||
- Maintainable code structure
|
||||
- Technical debt management
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 `devops` - Infrastructure & Deployment Expert
|
||||
**What they do**: Infrastructure automation, deployment, monitoring, reliability engineering
|
||||
|
||||
**Priority**: Automation > observability > reliability > scalability > manual processes
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "deploy", "infrastructure", "CI/CD", "monitoring"
|
||||
- Deployment or infrastructure work
|
||||
- DevOps or automation tasks
|
||||
|
||||
**Great for**:
|
||||
- Deployment automation and CI/CD
|
||||
- Infrastructure as code
|
||||
- Monitoring and alerting setup
|
||||
- Performance monitoring
|
||||
- Container and cloud infrastructure
|
||||
|
||||
**Infrastructure automation priorities**:
|
||||
- Zero-downtime deployments
|
||||
- Automated rollback capabilities
|
||||
- Infrastructure as code
|
||||
- Comprehensive monitoring
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:deploy production --persona-devops
|
||||
/sc:analyze infrastructure/ --persona-devops
|
||||
/sc:improve deployment-pipeline --persona-devops
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Automated over manual processes
|
||||
- Comprehensive observability
|
||||
- Reliable, repeatable deployments
|
||||
- Infrastructure as code practices
|
||||
|
||||
### Knowledge & Communication 📚
|
||||
|
||||
#### 👨🏫 `mentor` - Educational Guidance Specialist
|
||||
**What they do**: Teaching, knowledge transfer, educational explanations, learning facilitation
|
||||
|
||||
**Priority**: Understanding > knowledge transfer > teaching > task completion
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "explain", "learn", "understand", "teach"
|
||||
- Educational or knowledge transfer tasks
|
||||
- Step-by-step guidance requests
|
||||
|
||||
**Great for**:
|
||||
- Learning new technologies
|
||||
- Understanding complex concepts
|
||||
- Code explanations and walkthroughs
|
||||
- Best practices education
|
||||
- Team knowledge sharing
|
||||
|
||||
**Learning optimization approach**:
|
||||
- Skill level assessment
|
||||
- Progressive complexity building
|
||||
- Learning style adaptation
|
||||
- Knowledge retention reinforcement
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:explain React hooks --persona-mentor
|
||||
/sc:document --type guide --persona-mentor
|
||||
/sc:analyze complex-algorithm.js --persona-mentor
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Clear, accessible explanations
|
||||
- Complete conceptual understanding
|
||||
- Engaging learning experiences
|
||||
- Practical skill development
|
||||
|
||||
---
|
||||
|
||||
#### ✍️ `scribe` - Professional Documentation Expert
|
||||
**What they do**: Professional writing, documentation, localization, cultural communication
|
||||
|
||||
**Priority**: Clarity > audience needs > cultural sensitivity > completeness > brevity
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "document", "write", "guide", "README"
|
||||
- Documentation or writing tasks
|
||||
- Professional communication needs
|
||||
|
||||
**Great for**:
|
||||
- Technical documentation
|
||||
- User guides and tutorials
|
||||
- README files and wikis
|
||||
- API documentation
|
||||
- Professional communications
|
||||
|
||||
**Language support**: English (default), Spanish, French, German, Japanese, Chinese, Portuguese, Italian, Russian, Korean
|
||||
|
||||
**Content types**: Technical docs, user guides, API docs, commit messages, PR descriptions
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/sc:document api/ --persona-scribe
|
||||
/sc:git commit --persona-scribe
|
||||
/sc:explain --persona-scribe=es complex-feature
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Clear, professional communication
|
||||
- Audience-appropriate language
|
||||
- Cultural sensitivity and adaptation
|
||||
- High writing standards
|
||||
|
||||
## When Each Persona Shines ⭐
|
||||
|
||||
### Development Phase Mapping
|
||||
|
||||
**Planning & Design Phase**:
|
||||
- 🏗️ `architect` - System design and architecture planning
|
||||
- 🎨 `frontend` - UI/UX design and user experience
|
||||
- ✍️ `scribe` - Requirements documentation and specifications
|
||||
|
||||
**Implementation Phase**:
|
||||
- 🎨 `frontend` - UI component development
|
||||
- ⚙️ `backend` - API and service implementation
|
||||
- 🛡️ `security` - Security implementation and hardening
|
||||
|
||||
**Testing & Quality Phase**:
|
||||
- 🧪 `qa` - Test strategy and quality assurance
|
||||
- ⚡ `performance` - Performance testing and optimization
|
||||
- 🔍 `analyzer` - Bug investigation and root cause analysis
|
||||
|
||||
**Maintenance & Improvement Phase**:
|
||||
- 🔄 `refactorer` - Code cleanup and refactoring
|
||||
- ⚡ `performance` - Performance optimization
|
||||
- 👨🏫 `mentor` - Knowledge transfer and documentation
|
||||
|
||||
**Deployment & Operations Phase**:
|
||||
- 🚀 `devops` - Deployment automation and infrastructure
|
||||
- 🛡️ `security` - Security monitoring and compliance
|
||||
- ✍️ `scribe` - Operations documentation and runbooks
|
||||
|
||||
### Problem Type Mapping
|
||||
|
||||
**"My code is slow"** → ⚡ `performance`
|
||||
**"Something's broken and I don't know why"** → 🔍 `analyzer`
|
||||
**"Need to design a new system"** → 🏗️ `architect`
|
||||
**"UI looks terrible"** → 🎨 `frontend`
|
||||
**"Is this secure?"** → 🛡️ `security`
|
||||
**"Code is messy"** → 🔄 `refactorer`
|
||||
**"Need better tests"** → 🧪 `qa`
|
||||
**"Deployment keeps failing"** → 🚀 `devops`
|
||||
**"I don't understand this"** → 👨🏫 `mentor`
|
||||
**"Need documentation"** → ✍️ `scribe`
|
||||
|
||||
## Persona Combinations 🤝
|
||||
|
||||
Personas often work together automatically. Here are common collaboration patterns:
|
||||
|
||||
### Design & Implementation
|
||||
```bash
|
||||
/sc:design user-dashboard
|
||||
# Auto-activates: 🏗️ architect (system design) + 🎨 frontend (UI design)
|
||||
```
|
||||
|
||||
### Security Review
|
||||
```bash
|
||||
/sc:analyze --focus security api/
|
||||
# Auto-activates: 🛡️ security (primary) + ⚙️ backend (API expertise)
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
```bash
|
||||
/sc:improve --focus performance slow-app/
|
||||
# Auto-activates: ⚡ performance (primary) + 🎨 frontend (if UI) or ⚙️ backend (if API)
|
||||
```
|
||||
|
||||
### Quality Improvement
|
||||
```bash
|
||||
/sc:improve --focus quality legacy-code/
|
||||
# Auto-activates: 🔄 refactorer (primary) + 🧪 qa (testing) + 🏗️ architect (design)
|
||||
```
|
||||
|
||||
### Documentation & Learning
|
||||
```bash
|
||||
/sc:document complex-feature --type guide
|
||||
# Auto-activates: ✍️ scribe (writing) + 👨🏫 mentor (educational approach)
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
|
||||
### Before/After: Generic vs Persona-Specific
|
||||
|
||||
**Before** (generic):
|
||||
```bash
|
||||
/sc:analyze auth.js
|
||||
# → Basic analysis, generic advice
|
||||
```
|
||||
|
||||
**After** (security persona):
|
||||
```bash
|
||||
/sc:analyze auth.js --persona-security
|
||||
# → Security-focused analysis
|
||||
# → Threat modeling perspective
|
||||
# → OWASP compliance checking
|
||||
# → Vulnerability pattern detection
|
||||
```
|
||||
|
||||
### Auto-Activation in Action
|
||||
|
||||
**Frontend work detection**:
|
||||
```bash
|
||||
/sc:build react-components/
|
||||
# Auto-activates: 🎨 frontend
|
||||
# → UI-focused build optimization
|
||||
# → Accessibility checking
|
||||
# → Performance budgets
|
||||
# → Bundle size analysis
|
||||
```
|
||||
|
||||
**Complex debugging**:
|
||||
```bash
|
||||
/sc:troubleshoot "payment processing randomly fails"
|
||||
# Auto-activates: 🔍 analyzer
|
||||
# → Systematic investigation approach
|
||||
# → Evidence collection methodology
|
||||
# → Pattern analysis
|
||||
# → Root cause identification
|
||||
```
|
||||
|
||||
### Manual Override Examples
|
||||
|
||||
**Force security perspective**:
|
||||
```bash
|
||||
/sc:analyze react-app/ --persona-security
|
||||
# Even though it's frontend code, analyze from security perspective
|
||||
# → XSS vulnerability checking
|
||||
# → Authentication flow analysis
|
||||
# → Data exposure risks
|
||||
```
|
||||
|
||||
**Get architectural advice on small changes**:
|
||||
```bash
|
||||
/sc:improve small-utility.js --persona-architect
|
||||
# Apply architectural thinking to small code
|
||||
# → Design pattern opportunities
|
||||
# → Future extensibility
|
||||
# → Coupling analysis
|
||||
```
|
||||
|
||||
## Advanced Usage 🚀
|
||||
|
||||
### Manual Persona Control
|
||||
|
||||
**When to override auto-activation**:
|
||||
- You want a different perspective on the same problem
|
||||
- Auto-activation chose wrong persona for your specific needs
|
||||
- You're learning and want to see how different experts approach problems
|
||||
|
||||
**How to override**:
|
||||
```bash
|
||||
# Explicit persona selection
|
||||
/sc:analyze frontend-code/ --persona-security # Security view of frontend
|
||||
/sc:improve backend-api/ --persona-performance # Performance view of backend
|
||||
|
||||
# Multiple persona flags (last one wins)
|
||||
/sc:analyze --persona-frontend --persona-security # Uses security persona
|
||||
```
|
||||
|
||||
### Persona-Specific Flags and Settings
|
||||
|
||||
**Security persona + validation**:
|
||||
```bash
|
||||
/sc:analyze --persona-security --focus security --validate
|
||||
# → Maximum security focus with validation
|
||||
```
|
||||
|
||||
**Performance persona + benchmarking**:
|
||||
```bash
|
||||
/sc:test --persona-performance --benchmark --focus performance
|
||||
# → Performance-focused testing with metrics
|
||||
```
|
||||
|
||||
**Mentor persona + detailed explanations**:
|
||||
```bash
|
||||
/sc:explain complex-concept --persona-mentor --verbose
|
||||
# → Educational explanation with full detail
|
||||
```
|
||||
|
||||
### Cross-Domain Expertise
|
||||
|
||||
**When you need multiple perspectives**:
|
||||
```bash
|
||||
# Sequential analysis with different personas
|
||||
/sc:analyze --persona-security api/auth.js
|
||||
/sc:analyze --persona-performance api/auth.js
|
||||
/sc:analyze --persona-refactorer api/auth.js
|
||||
|
||||
# Or let SuperClaude coordinate automatically
|
||||
/sc:analyze --focus quality api/auth.js
|
||||
# Auto-coordinates: security + performance + refactorer insights
|
||||
```
|
||||
|
||||
## Common Workflows by Persona 💼
|
||||
|
||||
### 🏗️ Architect Workflows
|
||||
```bash
|
||||
# System design
|
||||
/sc:design microservices-architecture --persona-architect
|
||||
/sc:estimate "migrate monolith to microservices" --persona-architect
|
||||
|
||||
# Architecture review
|
||||
/sc:analyze --focus architecture --persona-architect large-system/
|
||||
/sc:review --persona-architect critical-components/
|
||||
```
|
||||
|
||||
### 🎨 Frontend Workflows
|
||||
```bash
|
||||
# Component development
|
||||
/sc:build dashboard-components/ --persona-frontend
|
||||
/sc:improve --focus accessibility --persona-frontend ui/
|
||||
|
||||
# Performance optimization
|
||||
/sc:analyze --focus performance --persona-frontend bundle/
|
||||
/sc:test --persona-frontend --focus performance
|
||||
```
|
||||
|
||||
### ⚙️ Backend Workflows
|
||||
```bash
|
||||
# API development
|
||||
/sc:design rest-api --persona-backend
|
||||
/sc:build api-endpoints/ --persona-backend
|
||||
|
||||
# Reliability improvements
|
||||
/sc:improve --focus reliability --persona-backend services/
|
||||
/sc:analyze --persona-backend --focus security api/
|
||||
```
|
||||
|
||||
### 🛡️ Security Workflows
|
||||
```bash
|
||||
# Security assessment
|
||||
/sc:scan --persona-security --focus security entire-app/
|
||||
/sc:analyze --persona-security auth-flow/
|
||||
|
||||
# Vulnerability fixing
|
||||
/sc:improve --focus security --persona-security vulnerable-code/
|
||||
/sc:review --persona-security --focus security critical-paths/
|
||||
```
|
||||
|
||||
### 🔍 Analyzer Workflows
|
||||
```bash
|
||||
# Bug investigation
|
||||
/sc:troubleshoot "intermittent failures" --persona-analyzer
|
||||
/sc:analyze --persona-analyzer --focus debugging problem-area/
|
||||
|
||||
# System understanding
|
||||
/sc:explain --persona-analyzer complex-system/
|
||||
/sc:load --persona-analyzer unfamiliar-codebase/
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Persona Cheat Sheet
|
||||
|
||||
| Persona | Best For | Auto-Activates On | Manual Flag |
|
||||
|---------|----------|-------------------|-------------|
|
||||
| 🏗️ architect | System design, architecture | "architecture", "design", "scalability" | `--persona-architect` |
|
||||
| 🎨 frontend | UI/UX, accessibility | "component", "responsive", "UI" | `--persona-frontend` |
|
||||
| ⚙️ backend | APIs, databases, reliability | "API", "database", "service" | `--persona-backend` |
|
||||
| 🛡️ security | Security, compliance | "security", "vulnerability", "auth" | `--persona-security` |
|
||||
| ⚡ performance | Optimization, speed | "performance", "optimization", "slow" | `--persona-performance` |
|
||||
| 🔍 analyzer | Debugging, investigation | "analyze", "debug", "investigate" | `--persona-analyzer` |
|
||||
| 🧪 qa | Testing, quality | "test", "quality", "validation" | `--persona-qa` |
|
||||
| 🔄 refactorer | Code cleanup, refactoring | "refactor", "cleanup", "quality" | `--persona-refactorer` |
|
||||
| 🚀 devops | Deployment, infrastructure | "deploy", "infrastructure", "CI/CD" | `--persona-devops` |
|
||||
| 👨🏫 mentor | Learning, explanation | "explain", "learn", "understand" | `--persona-mentor` |
|
||||
| ✍️ scribe | Documentation, writing | "document", "write", "guide" | `--persona-scribe` |
|
||||
|
||||
### Most Useful Combinations
|
||||
|
||||
**Security-focused development**:
|
||||
```bash
|
||||
--persona-security --focus security --validate
|
||||
```
|
||||
|
||||
**Performance optimization**:
|
||||
```bash
|
||||
--persona-performance --focus performance --benchmark
|
||||
```
|
||||
|
||||
**Learning and understanding**:
|
||||
```bash
|
||||
--persona-mentor --verbose --explain
|
||||
```
|
||||
|
||||
**Quality improvement**:
|
||||
```bash
|
||||
--persona-refactorer --focus quality --safe-mode
|
||||
```
|
||||
|
||||
**Professional documentation**:
|
||||
```bash
|
||||
--persona-scribe --type guide --detailed
|
||||
```
|
||||
|
||||
### Auto-Activation Triggers
|
||||
|
||||
**Strong triggers** (usually work well):
|
||||
- "security audit" → 🛡️ security
|
||||
- "UI component" → 🎨 frontend
|
||||
- "API design" → ⚙️ backend
|
||||
- "system architecture" → 🏗️ architect
|
||||
- "debug issue" → 🔍 analyzer
|
||||
|
||||
**Moderate triggers** (often work):
|
||||
- "improve performance" → ⚡ performance
|
||||
- "write tests" → 🧪 qa
|
||||
- "clean up code" → 🔄 refactorer
|
||||
- "deployment issue" → 🚀 devops
|
||||
|
||||
**Context-dependent triggers** (varies):
|
||||
- "document this" → ✍️ scribe or 👨🏫 mentor (depends on audience)
|
||||
- "analyze this" → 🔍 analyzer, 🏗️ architect, or domain specialist (depends on content)
|
||||
|
||||
## Troubleshooting Persona Issues 🚨
|
||||
|
||||
### Common Problems
|
||||
|
||||
**"Wrong persona activated"**
|
||||
- Use explicit persona flags: `--persona-security`
|
||||
- Check if your keywords triggered auto-activation
|
||||
- Try more specific language in your request
|
||||
|
||||
**"Persona doesn't seem to work"**
|
||||
- Verify persona name spelling: `--persona-frontend` not `--persona-fronted`
|
||||
- Some personas work better with specific commands
|
||||
- Try combining with relevant flags: `--focus security --persona-security`
|
||||
|
||||
**"Want multiple perspectives"**
|
||||
- Run same command with different personas manually
|
||||
- Use broader focus flags: `--focus quality` (activates multiple personas)
|
||||
- Let SuperClaude coordinate automatically with complex requests
|
||||
|
||||
**"Persona is too focused"**
|
||||
- Try a different persona that's more general
|
||||
- Use mentor persona for broader explanations
|
||||
- Combine with `--verbose` for more context
|
||||
|
||||
### When to Override Auto-Activation
|
||||
|
||||
**Override when**:
|
||||
- Auto-activation chose the wrong specialist
|
||||
- You want to learn from a different perspective
|
||||
- Working outside typical domain boundaries
|
||||
- Need specific expertise for edge cases
|
||||
|
||||
**How to override effectively**:
|
||||
```bash
|
||||
# Force specific perspective
|
||||
/sc:analyze frontend-code/ --persona-security # Security view of frontend
|
||||
|
||||
# Combine multiple perspectives
|
||||
/sc:analyze api/ --persona-security
|
||||
/sc:analyze api/ --persona-performance # Run separately for different views
|
||||
|
||||
# Use general analysis
|
||||
/sc:analyze --no-persona # Disable persona auto-activation
|
||||
```
|
||||
|
||||
## Tips for Effective Persona Usage 💡
|
||||
|
||||
### Getting Started (The Honest Way)
|
||||
1. **Just ignore personas completely at first** - Auto-activation handles everything
|
||||
2. **Use basic commands normally** - `/analyze`, `/build`, `/improve` work great without persona knowledge
|
||||
3. **Notice what happens** - You'll see different types of expertise emerge naturally
|
||||
4. **Trust the automation** - SuperClaude usually picks better experts than manual selection
|
||||
|
||||
### Getting Advanced (If You Want To)
|
||||
1. **Experiment with manual override** - Try `--persona-security` on frontend code for different perspectives
|
||||
2. **Learn the team members** - Read about individual personas when you get curious
|
||||
3. **Watch persona combinations** - See how multiple experts collaborate on complex problems
|
||||
4. **Use for learning** - Ask different personas the same question to see different approaches
|
||||
|
||||
### Best Practices (Keep It Simple)
|
||||
- **Let auto-activation work first** - Override only when you want different perspectives
|
||||
- **Don't overthink it** - The right experts show up when needed
|
||||
- **Use for experimentation** - Try different personas on the same problem for learning
|
||||
- **Trust the intelligence** - Auto-activation learns from patterns and keeps getting better
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**The real truth about personas** 💯:
|
||||
- **Auto-activation usually works pretty well** compared to trying to pick experts yourself
|
||||
- **You can completely ignore this guide** and still often get helpful expert assistance
|
||||
- **Personas exist to help you** - not to create complexity you need to manage
|
||||
- **Learning happens naturally** through use, not through studying persona descriptions 😊
|
||||
|
||||
**Don't feel overwhelmed by the team** 🧘♂️:
|
||||
- You don't need to know what each persona does
|
||||
- SuperClaude usually handles expert selection reasonably well
|
||||
- The detailed descriptions above are for curiosity, not necessity
|
||||
- You're not missing anything by letting auto-activation work
|
||||
|
||||
**When you might manually choose personas**:
|
||||
- **Curiosity** - "What would a security expert think about this frontend code?"
|
||||
- **Learning** - "How would different experts approach this problem?"
|
||||
- **Experimentation** - "Let me see this through a performance lens"
|
||||
- **Override** - "I want architectural advice on this small utility function"
|
||||
|
||||
**Keep it simple** 🎯:
|
||||
- Use normal commands like `/analyze some-code/`
|
||||
- Let the right experts automatically show up
|
||||
- Manual persona control is available when you want it, not because you need it
|
||||
- Focus on your work, not on managing who helps you
|
||||
|
||||
---
|
||||
|
||||
*Behind all this apparent complexity of having 11 specialists, SuperClaude tries to be simple to use. Just start coding and helpful experts usually show up when needed! 🚀*
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user