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,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! 🚀*
|
||||
521
Guides/agents-guide.md
Normal file
521
Guides/agents-guide.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# SuperClaude Agents Guide 🤖
|
||||
|
||||
## Overview
|
||||
|
||||
The SuperClaude Framework features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents provide expert-level assistance across all aspects of software development, from architecture design to documentation writing.
|
||||
|
||||
**The simple truth**: You don't need to pick agents or memorize what they do. SuperClaude automatically brings in the right experts for each situation!
|
||||
|
||||
**Here's what actually happens:**
|
||||
- You type `/analyze auth.js` → Security engineer automatically jumps in 🛡️
|
||||
- You work on React components → Frontend architect often takes over 🎨
|
||||
- You debug performance issues → Performance engineer often helps ⚡
|
||||
- You write documentation → Technical writer usually helps out ✍️
|
||||
|
||||
**It's like having a smart team** that knows when to jump in and help, without you managing who does what.
|
||||
|
||||
## 🚀 Just Try These (No Agent Knowledge Required)
|
||||
|
||||
```bash
|
||||
# These automatically activate the right experts:
|
||||
/analyze payment-system/ # → Security + backend experts auto-activate
|
||||
/build react-app/ # → Frontend architect takes over
|
||||
/improve slow-queries.sql # → Performance engineer jumps in
|
||||
/troubleshoot "auth failing" # → Root cause analyst + security expert coordinate
|
||||
/brainstorm "task manager app" # → Requirements analyst guides discovery
|
||||
```
|
||||
|
||||
**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help.
|
||||
|
||||
---
|
||||
|
||||
## The SuperClaude Agent Team 👥
|
||||
|
||||
### Architecture & System Design Agents 🏗️
|
||||
|
||||
#### 🏗️ `system-architect` - Large-Scale Design Expert
|
||||
**What they do**: Design scalable system architecture with focus on maintainability and long-term technical decisions
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Keywords: "architecture", "design", "scalability", "system", "patterns", "microservices"
|
||||
- Large-scale system design and architectural decisions
|
||||
- Cross-system integration and design pattern implementation
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **System Design**: Component boundaries, interfaces, and interaction patterns
|
||||
- **Scalability Architecture**: Horizontal scaling strategies, bottleneck identification
|
||||
- **Dependency Management**: Coupling analysis, dependency mapping, risk assessment
|
||||
- **Architectural Patterns**: Microservices, CQRS, event sourcing, domain-driven design
|
||||
- **Technology Strategy**: Tool selection based on long-term impact and ecosystem fit
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/design microservices-architecture # → System architecture and service design
|
||||
/analyze --focus architecture system/ # → Architectural review and improvement
|
||||
/plan scalability-improvements # → Scaling strategy and implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ⚙️ `backend-architect` - Reliable Backend Systems Expert
|
||||
**What they do**: Design reliable backend systems with focus on data integrity, security, and fault tolerance
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Backend system design and API development requests
|
||||
- Database design and optimization needs
|
||||
- Security, reliability, and performance requirements
|
||||
- Server-side architecture and scalability challenges
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **API Design**: RESTful services, GraphQL, proper error handling, validation
|
||||
- **Database Architecture**: Schema design, ACID compliance, query optimization
|
||||
- **Security Implementation**: Authentication, authorization, encryption, audit trails
|
||||
- **System Reliability**: Circuit breakers, graceful degradation, monitoring
|
||||
- **Performance Optimization**: Caching strategies, connection pooling, scaling patterns
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/design user-management-api # → Reliable API with proper auth
|
||||
/optimize database-queries/ # → Performance tuning and indexing
|
||||
/implement payment-processing # → Secure, reliable payment system
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 🎨 `frontend-architect` - Accessible UI Systems Expert
|
||||
**What they do**: Create accessible, performant user interfaces with focus on user experience and modern frameworks
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- UI component development and design system requests
|
||||
- Accessibility compliance and WCAG implementation needs
|
||||
- Performance optimization and Core Web Vitals improvements
|
||||
- Responsive design and mobile-first development requirements
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Accessibility**: WCAG 2.1 AA compliance, keyboard navigation, screen reader support
|
||||
- **Performance**: Core Web Vitals, bundle optimization, loading strategies
|
||||
- **Responsive Design**: Mobile-first approach, flexible layouts, device adaptation
|
||||
- **Component Architecture**: Reusable systems, design tokens, maintainable patterns
|
||||
- **Modern Frameworks**: React, Vue, Angular with best practices and optimization
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/build dashboard-components/ # → Accessible React components
|
||||
/improve --focus accessibility ui/ # → WCAG compliance and optimization
|
||||
/optimize bundle-performance # → Core Web Vitals improvement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 `devops-architect` - Infrastructure Automation Expert
|
||||
**What they do**: Automate infrastructure and deployment processes with focus on reliability and observability
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Infrastructure automation and CI/CD pipeline development needs
|
||||
- Deployment strategy and zero-downtime release requirements
|
||||
- Monitoring, observability, and reliability engineering requests
|
||||
- Infrastructure as code and configuration management tasks
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **CI/CD Pipelines**: Automated testing, deployment strategies, rollback capabilities
|
||||
- **Infrastructure as Code**: Version-controlled, reproducible infrastructure management
|
||||
- **Observability**: Comprehensive monitoring, logging, alerting, and metrics
|
||||
- **Container Orchestration**: Kubernetes, Docker, microservices architecture
|
||||
- **Cloud Automation**: Multi-cloud strategies, resource optimization, compliance
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/deploy production-app # → Zero-downtime deployment pipeline
|
||||
/build monitoring-stack # → Comprehensive observability setup
|
||||
/secure infrastructure/ # → Security hardening and compliance
|
||||
```
|
||||
|
||||
### Quality & Analysis Agents 🔍
|
||||
|
||||
#### 🛡️ `security-engineer` - Threat Modeling Expert
|
||||
**What they do**: Identify security vulnerabilities and ensure compliance with security standards and best practices
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Security vulnerability assessment and code audit requests
|
||||
- Compliance verification and security standards implementation needs
|
||||
- Threat modeling and attack vector analysis requirements
|
||||
- Authentication, authorization, and data protection implementation reviews
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Vulnerability Assessment**: OWASP Top 10, CWE patterns, code security analysis
|
||||
- **Threat Modeling**: Attack vector identification, risk assessment, security controls
|
||||
- **Compliance Verification**: Industry standards, regulatory requirements, security frameworks
|
||||
- **Authentication & Authorization**: Identity management, access controls, privilege escalation
|
||||
- **Data Protection**: Encryption implementation, secure data handling, privacy compliance
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/scan --focus security auth-system/ # → Comprehensive security audit
|
||||
/analyze payment-flow --security # → Threat modeling and risk assessment
|
||||
/improve --fix vulnerabilities api/ # → Security hardening and fixes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ⚡ `performance-engineer` - Bottleneck Detection Expert
|
||||
**What they do**: Optimize system performance through measurement-driven analysis and bottleneck elimination
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Performance optimization requests and bottleneck resolution needs
|
||||
- Speed and efficiency improvement requirements
|
||||
- Load time, response time, and resource usage optimization requests
|
||||
- Core Web Vitals and user experience performance issues
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Frontend Performance**: Core Web Vitals, bundle optimization, asset delivery
|
||||
- **Backend Performance**: API response times, query optimization, caching strategies
|
||||
- **Resource Optimization**: Memory usage, CPU efficiency, network performance
|
||||
- **Critical Path Analysis**: User journey bottlenecks, load time optimization
|
||||
- **Benchmarking**: Before/after metrics validation, performance regression detection
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/analyze --focus performance slow-api/ # → Bottleneck identification and fixes
|
||||
/optimize database-queries/ # → Query performance tuning
|
||||
/benchmark application-performance # → Load testing and capacity planning
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 🔍 `root-cause-analyst` - Systematic Investigation Expert
|
||||
**What they do**: Systematically investigate complex problems to identify underlying causes through evidence-based analysis and hypothesis testing
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Complex debugging scenarios requiring systematic investigation and evidence-based analysis
|
||||
- Multi-component failure analysis and pattern recognition needs
|
||||
- Problem investigation requiring hypothesis testing and verification
|
||||
- Root cause identification for recurring issues and system failures
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Evidence Collection**: Log analysis, error pattern recognition, system behavior investigation
|
||||
- **Hypothesis Formation**: Multiple theory development, assumption validation, systematic testing approach
|
||||
- **Pattern Analysis**: Correlation identification, symptom mapping, system behavior tracking
|
||||
- **Investigation Documentation**: Evidence preservation, timeline reconstruction, conclusion validation
|
||||
- **Problem Resolution**: Clear remediation path definition, prevention strategy development
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/troubleshoot "payment processing fails randomly" # → Systematic investigation
|
||||
/analyze mysterious-bug/ # → Evidence-based debugging
|
||||
/investigate system-outage-logs/ # → Root cause analysis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 🧪 `quality-engineer` - Quality Assurance Expert
|
||||
**What they do**: Ensure software quality through comprehensive testing strategies and systematic edge case detection
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Testing strategy design and comprehensive test plan development requests
|
||||
- Quality assurance process implementation and edge case identification needs
|
||||
- Test coverage analysis and risk-based testing prioritization requirements
|
||||
- Automated testing framework setup and integration testing strategy development
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Test Strategy Design**: Comprehensive test planning, risk assessment, coverage analysis
|
||||
- **Edge Case Detection**: Boundary conditions, failure scenarios, negative testing
|
||||
- **Test Automation**: Framework selection, CI/CD integration, automated test development
|
||||
- **Quality Metrics**: Coverage analysis, defect tracking, quality risk assessment
|
||||
- **Testing Methodologies**: Unit, integration, performance, security, and usability testing
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/test --comprehensive user-service/ # → Full testing strategy and implementation
|
||||
/validate --quality critical-features/ # → Quality gate implementation
|
||||
/analyze --focus testing legacy-code/ # → Testing strategy for existing code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 🔄 `refactoring-expert` - Clean Code Specialist
|
||||
**What they do**: Improve code quality and reduce technical debt through systematic refactoring and clean code principles
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Code complexity reduction and technical debt elimination requests
|
||||
- SOLID principles implementation and design pattern application needs
|
||||
- Code quality improvement and maintainability enhancement requirements
|
||||
- Refactoring methodology and clean code principle application requests
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Code Simplification**: Complexity reduction, readability improvement, cognitive load minimization
|
||||
- **Technical Debt Reduction**: Duplication elimination, anti-pattern removal, quality metric improvement
|
||||
- **Pattern Application**: SOLID principles, design patterns, refactoring catalog techniques
|
||||
- **Quality Metrics**: Cyclomatic complexity, maintainability index, code duplication measurement
|
||||
- **Safe Transformation**: Behavior preservation, incremental changes, comprehensive testing validation
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/improve --focus quality legacy-module/ # → Comprehensive code quality improvement
|
||||
/refactor --safe complex-functions/ # → Safe refactoring with test coverage
|
||||
/cleanup --technical-debt codebase/ # → Systematic technical debt reduction
|
||||
```
|
||||
|
||||
### Specialized Development Agents 🎯
|
||||
|
||||
#### 🐍 `python-expert` - Master Python Specialist
|
||||
**What they do**: Deliver production-ready, secure, high-performance Python code following SOLID principles and modern best practices
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Python development requests requiring production-quality code and architecture decisions
|
||||
- Code review and optimization needs for performance and security enhancement
|
||||
- Testing strategy implementation and comprehensive coverage requirements
|
||||
- Modern Python tooling setup and best practices implementation
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Production Quality**: Security-first development, comprehensive testing, error handling, performance optimization
|
||||
- **Modern Architecture**: SOLID principles, clean architecture, dependency injection, separation of concerns
|
||||
- **Testing Excellence**: TDD approach, unit/integration/property-based testing, 95%+ coverage, mutation testing
|
||||
- **Security Implementation**: Input validation, OWASP compliance, secure coding practices, vulnerability prevention
|
||||
- **Performance Engineering**: Profiling-based optimization, async programming, efficient algorithms, memory management
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/build python-api --focus security # → Production-ready FastAPI with security
|
||||
/improve legacy-python/ --focus quality # → Refactor to SOLID principles
|
||||
/test python-service/ --comprehensive # → Full test suite with coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 📋 `requirements-analyst` - Requirements Discovery Expert
|
||||
**What they do**: Transform ambiguous project ideas into concrete specifications through systematic requirements discovery and structured analysis
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Ambiguous project requests requiring requirements clarification and specification development
|
||||
- PRD creation and formal project documentation needs from conceptual ideas
|
||||
- Stakeholder analysis and user story development requirements
|
||||
- Project scope definition and success criteria establishment requests
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Requirements Discovery**: Systematic questioning, stakeholder analysis, user need identification
|
||||
- **Specification Development**: PRD creation, user story writing, acceptance criteria definition
|
||||
- **Scope Definition**: Boundary setting, constraint identification, feasibility validation
|
||||
- **Success Metrics**: Measurable outcome definition, KPI establishment, acceptance condition setting
|
||||
- **Stakeholder Alignment**: Perspective integration, conflict resolution, consensus building
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/brainstorm "task management app" # → Interactive discovery session
|
||||
# → Automatic handoff to requirements analyst
|
||||
# → PRD generation with structured requirements
|
||||
```
|
||||
|
||||
### Communication & Learning Agents 📚
|
||||
|
||||
#### ✍️ `technical-writer` - Documentation Excellence Expert
|
||||
**What they do**: Create clear, comprehensive technical documentation tailored to specific audiences with focus on usability and accessibility
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- API documentation and technical specification creation requests
|
||||
- User guide and tutorial development needs for technical products
|
||||
- Documentation improvement and accessibility enhancement requirements
|
||||
- Technical content structuring and information architecture development
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Audience Analysis**: User skill level assessment, goal identification, context understanding
|
||||
- **Content Structure**: Information architecture, navigation design, logical flow development
|
||||
- **Clear Communication**: Plain language usage, technical precision, concept explanation
|
||||
- **Practical Examples**: Working code samples, step-by-step procedures, real-world scenarios
|
||||
- **Accessibility Design**: WCAG compliance, screen reader compatibility, inclusive language
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/document api-endpoints/ # → Comprehensive API documentation
|
||||
/write user-guide --audience beginner # → User-friendly tutorial and guides
|
||||
/improve --docs project-documentation/ # → Documentation quality enhancement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 👨🏫 `learning-guide` - Learning & Mentorship Expert
|
||||
**What they do**: Teach programming concepts and explain code with focus on understanding through progressive learning and practical examples
|
||||
|
||||
**Auto-activation triggers**:
|
||||
- Code explanation and programming concept education requests
|
||||
- Tutorial creation and progressive learning path development needs
|
||||
- Algorithm breakdown and step-by-step analysis requirements
|
||||
- Educational content design and skill development guidance requests
|
||||
|
||||
**Specialized capabilities**:
|
||||
- **Concept Explanation**: Clear breakdowns, practical examples, real-world application demonstration
|
||||
- **Progressive Learning**: Step-by-step skill building, prerequisite mapping, difficulty progression
|
||||
- **Educational Examples**: Working code demonstrations, variation exercises, practical implementation
|
||||
- **Understanding Verification**: Knowledge assessment, skill application, comprehension validation
|
||||
- **Learning Path Design**: Structured progression, milestone identification, skill development tracking
|
||||
|
||||
**Example use cases**:
|
||||
```bash
|
||||
/explain complex-algorithm --educational # → Step-by-step learning guide
|
||||
/teach react-patterns --beginner # → Progressive React tutorial
|
||||
/mentor junior-developer --focus testing # → Personalized learning guidance
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Coordination & Integration 🤝
|
||||
|
||||
### Automatic Agent Collaboration
|
||||
|
||||
Agents often work together automatically. Here are common collaboration patterns:
|
||||
|
||||
#### **Multi-Domain Projects**
|
||||
```bash
|
||||
/build full-stack-app/
|
||||
# Auto-coordinates: backend-architect + frontend-architect + system-architect
|
||||
```
|
||||
|
||||
#### **Security-Focused Development**
|
||||
```bash
|
||||
/analyze --focus security payment-system/
|
||||
# Auto-coordinates: security-engineer + backend-architect + performance-engineer
|
||||
```
|
||||
|
||||
#### **Quality Improvement**
|
||||
```bash
|
||||
/improve --focus quality legacy-codebase/
|
||||
# Auto-coordinates: refactoring-expert + quality-engineer + system-architect
|
||||
```
|
||||
|
||||
### Integration with MCP Servers
|
||||
|
||||
Each agent leverages specific MCP servers for enhanced capabilities:
|
||||
|
||||
- **Context7**: Documentation patterns, framework best practices, compliance standards
|
||||
- **Sequential**: Complex analysis, systematic problem solving, architectural planning
|
||||
- **Magic**: UI component generation, design system integration, modern frameworks
|
||||
- **Playwright**: Cross-browser testing, visual validation, performance testing
|
||||
- **Morphllm**: Intelligent code transformations, pattern application, optimization
|
||||
- **Serena**: Memory operations, cross-reference management, symbol-level analysis
|
||||
|
||||
### Integration with Commands
|
||||
|
||||
Agents seamlessly integrate with SuperClaude's command system:
|
||||
|
||||
```bash
|
||||
# Commands automatically select appropriate agents
|
||||
/analyze → root-cause-analyst or system-architect (context-dependent)
|
||||
/build → frontend-architect, backend-architect, or python-expert
|
||||
/test → quality-engineer with domain-specific coordination
|
||||
/brainstorm → requirements-analyst for requirements discovery
|
||||
/document → technical-writer with audience-appropriate formatting
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Agent Selection Cheat Sheet
|
||||
|
||||
| Agent | Best For | Auto-Activates On | Example Use |
|
||||
|-------|----------|-------------------|-------------|
|
||||
| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design |
|
||||
| ⚙️ backend-architect | Backend systems | APIs, databases, services | Reliable backend systems |
|
||||
| 🎨 frontend-architect | User interfaces | UI components, accessibility | Accessible web interfaces |
|
||||
| 🚀 devops-architect | Infrastructure | CI/CD, deployment, monitoring | Deployment automation |
|
||||
| 🛡️ security-engineer | Security analysis | Security keywords, auth code | Vulnerability assessment |
|
||||
| ⚡ performance-engineer | Performance tuning | "slow", "bottleneck", profiling | System optimization |
|
||||
| 🔍 root-cause-analyst | Problem solving | "debug", "investigate", bugs | Complex bug investigation |
|
||||
| 🧪 quality-engineer | Quality assurance | Testing, validation, QA | Comprehensive test strategy |
|
||||
| 🔄 refactoring-expert | Code improvement | Refactoring, cleanup, quality | Clean code practices |
|
||||
| 🐍 python-expert | Python development | .py files, Python frameworks | Production Python APIs |
|
||||
| 📋 requirements-analyst | Requirements discovery | Ambiguous projects, brainstorming | Project specification |
|
||||
| ✍️ technical-writer | Documentation | Documentation requests | API documentation |
|
||||
| 👨🏫 learning-guide | Learning & teaching | "explain", "learn", tutorials | Educational content |
|
||||
|
||||
### Most Useful Agent Combinations
|
||||
|
||||
**Full-Stack Development**:
|
||||
```bash
|
||||
# Automatically coordinates backend + frontend + architecture
|
||||
/build modern-web-app/
|
||||
```
|
||||
|
||||
**Security & Performance Review**:
|
||||
```bash
|
||||
# Coordinates security + performance + quality analysis
|
||||
/analyze --comprehensive production-system/
|
||||
```
|
||||
|
||||
**Learning & Development**:
|
||||
```bash
|
||||
# Coordinates learning guide + technical writer + domain expert
|
||||
/explain complex-system --educational
|
||||
```
|
||||
|
||||
**Project Discovery to Implementation**:
|
||||
```bash
|
||||
# Requirements → Architecture → Implementation
|
||||
/brainstorm "e-commerce platform"
|
||||
# → Automatic handoff through agent coordination
|
||||
```
|
||||
|
||||
## Best Practices 💡
|
||||
|
||||
### Getting Started (The Simple Way)
|
||||
1. **Just use normal commands** - Agents auto-activate based on your needs
|
||||
2. **Trust the automation** - SuperClaude usually picks better experts than manual selection
|
||||
3. **Focus on your work** - Not on managing which agent helps you
|
||||
4. **Let coordination happen** - Multiple agents work together automatically
|
||||
|
||||
### Advanced Usage (When You Want Control)
|
||||
1. **Manual agent selection** - Use agent names in commands when you want specific expertise
|
||||
2. **Cross-domain perspectives** - Ask security agents about frontend code for different viewpoints
|
||||
3. **Learning mode** - Use learning-guide for explanation-focused assistance
|
||||
4. **Quality focus** - Combine quality-engineer with domain experts for comprehensive quality
|
||||
|
||||
### Common Patterns
|
||||
|
||||
**For New Projects**:
|
||||
```bash
|
||||
/brainstorm "your project idea" # → Requirements discovery
|
||||
# → Automatic PRD generation and handoff
|
||||
# → Ready for implementation workflow
|
||||
```
|
||||
|
||||
**For Existing Code**:
|
||||
```bash
|
||||
/analyze existing-system/ # → Appropriate domain expert auto-selected
|
||||
/improve --focus quality code/ # → Quality-focused agent coordination
|
||||
/secure legacy-application/ # → Security-focused analysis and hardening
|
||||
```
|
||||
|
||||
**For Learning**:
|
||||
```bash
|
||||
/explain complex-concept --educational # → Learning guide with domain expert
|
||||
/document api/ --audience beginner # → Technical writer with appropriate level
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**The real truth about agents** 💯:
|
||||
- **Auto-activation works remarkably well** - Usually better than trying to pick experts yourself
|
||||
- **You can completely ignore agent details** and still get excellent expert assistance
|
||||
- **Agents exist to help you** - Not to create complexity you need to manage
|
||||
- **Learning happens naturally** through use, not through studying agent descriptions
|
||||
|
||||
**Don't feel overwhelmed by the team** 🧘♂️:
|
||||
- You don't need to know what each agent does
|
||||
- SuperClaude handles expert selection intelligently
|
||||
- The detailed descriptions above are for curiosity, not necessity
|
||||
- Focus on your work - the right experts will show up when needed
|
||||
|
||||
**When you might want to know about agents**:
|
||||
- **Curiosity** - "What would a security expert think about this frontend code?"
|
||||
- **Learning** - "How would different experts approach this problem?"
|
||||
- **Specialization** - "I specifically need Python architecture expertise"
|
||||
- **Quality focus** - "I want comprehensive quality analysis from multiple angles"
|
||||
|
||||
**Keep it simple** 🎯:
|
||||
- Use normal commands like `/analyze some-code/` and `/build my-app/`
|
||||
- Let the right experts automatically show up
|
||||
- Agent coordination is available when you want it, not because you need it
|
||||
- Focus on building great software - we'll handle the expertise coordination
|
||||
|
||||
---
|
||||
|
||||
*Behind this sophisticated team of 13 specialists, the SuperClaude Framework remains simple to use. Just start coding and the right experts show up when needed! 🚀*
|
||||
695
Guides/behavioral-modes-guide.md
Normal file
695
Guides/behavioral-modes-guide.md
Normal file
@@ -0,0 +1,695 @@
|
||||
# SuperClaude Behavioral Modes Guide 🧠
|
||||
|
||||
## 💡 The Simple Truth About Modes
|
||||
|
||||
**You don't need to understand behavioral modes to use SuperClaude.** They work automatically in the background, adapting how Claude Code behaves based on what you're trying to do.
|
||||
|
||||
**Here's what actually happens:**
|
||||
- Type `/sc:brainstorm "app idea"` → Brainstorming mode kicks in with discovery questions 🤔
|
||||
- Work on complex debugging → Introspection mode helps with systematic analysis 🔍
|
||||
- Handle large refactoring → Task Management mode breaks it into coordinated steps 📋
|
||||
- Need multiple tools → Orchestration mode picks the best ones automatically 🎯
|
||||
- Context getting full → Token Efficiency mode compresses without losing meaning ⚡
|
||||
|
||||
**Think of it like this**: SuperClaude has different "personalities" that automatically show up when they'd be most helpful. You just work normally, and the right approach appears! ✨
|
||||
|
||||
---
|
||||
|
||||
**TL;DR**: Behavioral modes are SuperClaude's way of being smarter about how it helps you. They activate automatically. You don't manage them, they manage themselves.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Just Try These (See Modes in Action)
|
||||
|
||||
```bash
|
||||
# Brainstorming Mode - Interactive discovery
|
||||
/sc:brainstorm "task management app" # → Gets curious, asks discovery questions
|
||||
|
||||
# Introspection Mode - Deep thinking
|
||||
/sc:troubleshoot "weird auth behavior" # → Analyzes reasoning patterns systematically
|
||||
|
||||
# Task Management Mode - Complex coordination
|
||||
/sc:implement user-dashboard # → Breaks into phases, delegates subtasks
|
||||
|
||||
# Orchestration Mode - Smart tool selection
|
||||
/sc:analyze large-codebase/ # → Picks best tools, coordinates efficiently
|
||||
|
||||
# Token Efficiency Mode - Compressed communication
|
||||
/sc:improve --uc legacy-code/ # → Uses symbols, abbreviations, stays clear
|
||||
```
|
||||
|
||||
**See the pattern?** You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". 🎯
|
||||
|
||||
---
|
||||
|
||||
## The Five Behavioral Modes 🌟
|
||||
|
||||
### 🧠 Brainstorming Mode - Interactive Discovery
|
||||
|
||||
**What it does**: Turns SuperClaude into a collaborative discovery partner who helps you figure out what you actually want to build.
|
||||
|
||||
#### Automatic Activation 🪄
|
||||
- **Vague requests**: "I want to build something...", "Maybe we could..."
|
||||
- **Exploration words**: brainstorm, explore, discuss, figure out, not sure
|
||||
- **Uncertainty**: "possibly", "thinking about", "could we"
|
||||
- **Manual trigger**: `--brainstorm` or `--bs`
|
||||
|
||||
#### How It Changes SuperClaude 🔄
|
||||
- **Socratic Dialogue**: Asks probing questions instead of jumping to solutions
|
||||
- **Non-Presumptive**: Doesn't assume what you want, lets you guide discovery
|
||||
- **Collaborative**: Partners with you rather than directing you
|
||||
- **Brief Generation**: Turns conversations into structured requirement documents
|
||||
|
||||
#### Real Examples 📝
|
||||
|
||||
**Standard response:**
|
||||
```
|
||||
User: "I want to build a web app"
|
||||
Claude: "I'll help you build a web application. What framework would you like to use?"
|
||||
```
|
||||
|
||||
**Brainstorming mode:**
|
||||
```
|
||||
User: "I want to build a web app"
|
||||
Claude: "🤔 Let's explore this together! Discovery questions:
|
||||
- What problem does this solve for your users?
|
||||
- Who are your target users and what are their main workflows?
|
||||
- What's your expected user volume and performance needs?
|
||||
- Any existing systems it needs to integrate with?
|
||||
- What's your timeline and technical constraints?
|
||||
|
||||
📝 Once we explore these, I'll generate a structured brief for implementation!"
|
||||
```
|
||||
|
||||
#### Perfect For 💫
|
||||
- Early project planning and ideation
|
||||
- Requirements discovery from vague ideas
|
||||
- Turning "I need something that does..." into concrete specs
|
||||
- Preventing scope creep through upfront exploration
|
||||
|
||||
---
|
||||
|
||||
### 🔍 Introspection Mode - Meta-Cognitive Analysis
|
||||
|
||||
**What it does**: Makes SuperClaude consciously analyze its own reasoning and decision-making process, especially when things go wrong or get complex.
|
||||
|
||||
#### Automatic Activation 🪄
|
||||
- **Self-analysis requests**: "analyze my reasoning", "reflect on decision"
|
||||
- **Error recovery**: When outcomes don't match expectations
|
||||
- **Complex problems**: Multi-layered issues requiring conscious oversight
|
||||
- **Pattern recognition**: Recurring behaviors or optimization needs
|
||||
- **Manual trigger**: `--introspect` or `--introspection`
|
||||
|
||||
#### How It Changes SuperClaude 🔄
|
||||
- **Self-Examination**: Consciously analyzes decision logic and reasoning chains
|
||||
- **Transparency**: Exposes thinking with markers (🤔, 🎯, ⚡, 📊, 💡)
|
||||
- **Pattern Detection**: Identifies recurring cognitive patterns and behaviors
|
||||
- **Learning Focus**: Extracts insights for continuous improvement
|
||||
|
||||
#### Real Examples 📝
|
||||
|
||||
**Standard response:**
|
||||
```
|
||||
User: "The solution didn't work as expected"
|
||||
Claude: "Let me look at the code and find the issue."
|
||||
```
|
||||
|
||||
**Introspection mode:**
|
||||
```
|
||||
User: "The solution didn't work as expected"
|
||||
Claude: "🎯 Decision Analysis: Expected X → got Y
|
||||
🔍 Pattern Check: Similar logic errors in auth.js:15, config.js:22
|
||||
📊 Framework Compliance: Missed validation step from quality gates
|
||||
🤔 Reasoning: Why did I choose async/await over promises here?
|
||||
💡 Insight: Need systematic validation before implementation
|
||||
|
||||
Let me apply this learning to fix the current issue properly."
|
||||
```
|
||||
|
||||
#### Perfect For 💫
|
||||
- Debugging complex problems that require meta-thinking
|
||||
- Understanding why certain approaches were chosen
|
||||
- Learning from mistakes and improving patterns
|
||||
- Framework compliance checking and optimization
|
||||
|
||||
---
|
||||
|
||||
### 📋 Task Management Mode - Orchestration & Delegation
|
||||
|
||||
**What it does**: Transforms SuperClaude into a project coordinator that breaks complex work into systematic phases and coordinates multiple sub-tasks efficiently.
|
||||
|
||||
#### Automatic Activation 🪄
|
||||
- **Multi-step operations**: 3+ steps (build, implement, create, fix, refactor)
|
||||
- **Complex scope**: system-wide, feature-complete, comprehensive changes
|
||||
- **File thresholds**: >2 directories OR >3 files OR complexity >0.4
|
||||
- **Quality improvements**: polish, refine, enhance keywords
|
||||
- **Manual triggers**: `--delegate`, `--loop`, `--concurrency`
|
||||
|
||||
#### How It Changes SuperClaude 🔄
|
||||
- **Orchestration Mindset**: Breaks complex work into coordinated layers
|
||||
- **Delegation Strategy**: Parallel processing with intelligent sub-task routing
|
||||
- **State Management**: Single focus protocol with real-time progress tracking
|
||||
- **Quality Gates**: Evidence-based validation before task completion
|
||||
- **Progressive Systems**: Systematic enhancement through compound intelligence
|
||||
|
||||
#### Real Examples 📝
|
||||
|
||||
**Standard response:**
|
||||
```
|
||||
User: "I need to refactor this authentication system"
|
||||
Claude: "I'll refactor the authentication system for you."
|
||||
```
|
||||
|
||||
**Task Management mode:**
|
||||
```
|
||||
User: "I need to refactor this authentication system"
|
||||
Claude: "📋 Detected: system-wide auth refactor → delegation mode activated
|
||||
|
||||
🔄 Phase 1: Security Analysis & Dependencies
|
||||
- Analyze current auth.js, middleware.js, session.js
|
||||
- Map security vulnerabilities and performance bottlenecks
|
||||
- Document current API contracts and integrations
|
||||
|
||||
🔄 Phase 2: Core Implementation
|
||||
- Refactor authentication logic with modern patterns
|
||||
- Update middleware for improved security
|
||||
- Enhance session management with proper cleanup
|
||||
|
||||
🔄 Phase 3: Integration & Validation
|
||||
- Update all dependent components and routes
|
||||
- Run comprehensive security and integration tests
|
||||
- Performance benchmarking and optimization
|
||||
|
||||
📊 Progress tracking: Each phase validates before proceeding
|
||||
✅ Quality gates: Security, performance, compatibility checks"
|
||||
```
|
||||
|
||||
#### Perfect For 💫
|
||||
- Large refactoring projects that span multiple files
|
||||
- Feature implementation requiring coordination
|
||||
- System-wide changes that need careful orchestration
|
||||
- Complex builds that benefit from parallel processing
|
||||
|
||||
---
|
||||
|
||||
### 🎯 Orchestration Mode - Intelligent Tool Selection
|
||||
|
||||
**What it does**: Optimizes SuperClaude's tool selection and resource usage, automatically choosing the most powerful and efficient approach for each task.
|
||||
|
||||
#### Automatic Activation 🪄
|
||||
- **Multi-tool operations**: Tasks requiring coordination between different tools
|
||||
- **Performance constraints**: >75% resource usage detected
|
||||
- **Parallel opportunities**: >3 files or independent operations possible
|
||||
- **Complex routing**: Multiple valid approaches available
|
||||
- **Manual trigger**: `--orchestrate`
|
||||
|
||||
#### How It Changes SuperClaude 🔄
|
||||
- **Smart Tool Selection**: Always chooses the most powerful tool for each task type
|
||||
- **Resource Awareness**: Adapts approach based on system constraints
|
||||
- **Parallel Thinking**: Identifies independent operations for concurrent execution
|
||||
- **Efficiency Focus**: Optimizes for speed and effectiveness over familiarity
|
||||
|
||||
#### Tool Selection Matrix 🛠️
|
||||
|
||||
| Task Type | Best Tool | Alternative | Why Better |
|
||||
|-----------|-----------|-------------|------------|
|
||||
| UI components | Magic MCP | Manual coding | Modern patterns, accessibility |
|
||||
| Deep analysis | Sequential MCP | Native reasoning | Structured multi-step thinking |
|
||||
| Symbol operations | Serena MCP | Manual search | Semantic understanding |
|
||||
| Pattern edits | Morphllm MCP | Individual edits | Bulk operations, consistency |
|
||||
| Documentation | Context7 MCP | Web search | Official patterns, versioned |
|
||||
| Browser testing | Playwright MCP | Unit tests | Real user interactions |
|
||||
| Multi-file edits | MultiEdit | Sequential Edits | Atomic operations, rollback |
|
||||
|
||||
#### Resource Management Zones 📊
|
||||
|
||||
**🟢 Green Zone (0-75%)**
|
||||
- Full capabilities available
|
||||
- Use all tools and features
|
||||
- Normal verbosity and detail
|
||||
|
||||
**🟡 Yellow Zone (75-85%)**
|
||||
- Activate efficiency mode
|
||||
- Reduce verbosity intelligently
|
||||
- Defer non-critical operations
|
||||
|
||||
**🔴 Red Zone (85%+)**
|
||||
- Essential operations only
|
||||
- Minimal output, maximum efficiency
|
||||
- Fail fast on complex requests
|
||||
|
||||
#### Real Examples 📝
|
||||
|
||||
**Standard response:**
|
||||
```
|
||||
User: "/sc:analyze large-project/"
|
||||
Claude: "I'll analyze your project files."
|
||||
[Uses basic file reading and native analysis]
|
||||
```
|
||||
|
||||
**Orchestration mode:**
|
||||
```
|
||||
User: "/sc:analyze large-project/"
|
||||
Claude: "🎯 Orchestration: large-project analysis
|
||||
📊 Resource Status: 45% → Green Zone
|
||||
🛠️ Tool Selection Matrix:
|
||||
- File discovery: Glob (batch patterns)
|
||||
- Code analysis: Sequential MCP (structured reasoning)
|
||||
- Documentation: Context7 MCP (framework patterns)
|
||||
- Parallel execution: 3 concurrent analysis threads
|
||||
|
||||
⚡ Executing optimized analysis workflow..."
|
||||
```
|
||||
|
||||
#### Perfect For 💫
|
||||
- Large codebases requiring efficient analysis
|
||||
- Performance-critical operations
|
||||
- Tasks benefiting from parallel processing
|
||||
- Resource-constrained environments
|
||||
|
||||
---
|
||||
|
||||
### ⚡ Token Efficiency Mode - Compressed Communication
|
||||
|
||||
**What it does**: Transforms SuperClaude's communication style to use symbols, abbreviations, and compressed formats while preserving 95%+ of information quality.
|
||||
|
||||
#### Automatic Activation 🪄
|
||||
- **Context pressure**: >75% context usage or resource constraints
|
||||
- **Large operations**: Complex analysis workflows needing optimization
|
||||
- **User requests**: `--uc`, `--ultracompressed` flags
|
||||
- **Efficiency needs**: When speed and conciseness are priorities
|
||||
|
||||
#### How It Changes SuperClaude 🔄
|
||||
- **Symbol Communication**: Visual symbols for logic, status, and technical domains
|
||||
- **Abbreviation Systems**: Context-aware compression for technical terms
|
||||
- **30-50% Compression**: Significant token reduction while preserving meaning
|
||||
- **Structured Output**: Bullet points, tables, concise explanations
|
||||
|
||||
#### Symbol Reference 🔤
|
||||
|
||||
**Core Logic & Flow**
|
||||
- `→` leads to, implies (`auth.js:45 → 🛡️ security risk`)
|
||||
- `⇒` transforms to (`input ⇒ validated_output`)
|
||||
- `←` rollback, reverse (`migration ← rollback`)
|
||||
- `⇄` bidirectional (`sync ⇄ remote`)
|
||||
- `&` and, combine (`🛡️ security & ⚡ performance`)
|
||||
- `|` separator, or (`react|vue|angular`)
|
||||
- `:` define, specify (`scope: file|module`)
|
||||
- `»` sequence, then (`build » test » deploy`)
|
||||
- `∴` therefore (`tests ❌ ∴ code broken`)
|
||||
- `∵` because (`slow ∵ O(n²) algorithm`)
|
||||
|
||||
**Status & Progress**
|
||||
- `✅` completed, passed
|
||||
- `❌` failed, error
|
||||
- `⚠️` warning, review needed
|
||||
- `🔄` in progress
|
||||
- `⏳` waiting, pending
|
||||
- `🚨` critical, urgent
|
||||
|
||||
**Technical Domains**
|
||||
- `⚡` Performance (speed, optimization)
|
||||
- `🔍` Analysis (search, investigation)
|
||||
- `🔧` Configuration (setup, tools)
|
||||
- `🛡️` Security (protection, safety)
|
||||
- `📦` Deployment (package, bundle)
|
||||
- `🎨` Design (UI, frontend)
|
||||
- `🏗️` Architecture (system structure)
|
||||
|
||||
#### Abbreviation Systems 📝
|
||||
|
||||
**System & Architecture**
|
||||
`cfg` config • `impl` implementation • `arch` architecture • `perf` performance • `ops` operations • `env` environment
|
||||
|
||||
**Development Process**
|
||||
`req` requirements • `deps` dependencies • `val` validation • `test` testing • `docs` documentation • `std` standards
|
||||
|
||||
**Quality & Analysis**
|
||||
`qual` quality • `sec` security • `err` error • `rec` recovery • `sev` severity • `opt` optimization
|
||||
|
||||
#### Real Examples 📝
|
||||
|
||||
**Standard response:**
|
||||
```
|
||||
User: "Analyze the authentication system performance"
|
||||
Claude: "I'll analyze the authentication system's performance. The user validation function in auth.js line 45 has a security vulnerability. The build process completed successfully, now running tests, then deploying. Performance analysis shows the algorithm is slow because it's O(n²) complexity."
|
||||
```
|
||||
|
||||
**Token Efficiency mode:**
|
||||
```
|
||||
User: "Analyze the authentication system performance"
|
||||
Claude: "⚡ auth.js perf analysis:
|
||||
🛡️ auth.js:45 → sec risk in user val()
|
||||
📊 build ✅ » test 🔄 » deploy ⏳
|
||||
🔍 perf: slow ∵ O(n²) algo
|
||||
|
||||
∴ rec: impl O(log n) lookup & fix sec val"
|
||||
```
|
||||
|
||||
#### Perfect For 💫
|
||||
- Large context situations requiring efficiency
|
||||
- Complex analysis that would normally be verbose
|
||||
- Performance-critical operations
|
||||
- Users who prefer concise, information-dense output
|
||||
|
||||
---
|
||||
|
||||
## How Modes Work Together 🤝
|
||||
|
||||
### Mode Coordination Examples
|
||||
|
||||
**Building a New Feature** (Multiple Modes)
|
||||
```bash
|
||||
# Starts in Brainstorming Mode
|
||||
/sc:brainstorm "user dashboard"
|
||||
# 🧠 Discovery questions about requirements
|
||||
|
||||
# Transitions to Task Management Mode
|
||||
/sc:implement user-dashboard-feature
|
||||
# 📋 Breaks into coordinated implementation phases
|
||||
|
||||
# Orchestration Mode kicks in for complex parts
|
||||
# 🎯 Chooses best tools for UI (Magic MCP), testing (Playwright MCP)
|
||||
|
||||
# Token Efficiency if context gets full
|
||||
# ⚡ Compresses communication while maintaining quality
|
||||
```
|
||||
|
||||
**Debugging Complex Issues**
|
||||
```bash
|
||||
# Starts in Introspection Mode
|
||||
/sc:troubleshoot "authentication randomly failing"
|
||||
# 🔍 Systematic analysis of reasoning and patterns
|
||||
|
||||
# Orchestration Mode for tool selection
|
||||
# 🎯 Uses Sequential MCP for structured investigation
|
||||
|
||||
# Task Management if solution is complex
|
||||
# 📋 Coordinates fix across multiple files and systems
|
||||
```
|
||||
|
||||
### Mode Priority System 📊
|
||||
|
||||
1. **User-Triggered** (`--brainstorm`, `--uc`, etc.) - Always override automatic
|
||||
2. **Context-Critical** (Token Efficiency when context >85%) - High priority
|
||||
3. **Task-Appropriate** (Task Management for 3+ steps) - Standard priority
|
||||
4. **Enhancement** (Orchestration for optimization) - Background priority
|
||||
|
||||
### Mode Switching 🔄
|
||||
|
||||
Modes can:
|
||||
- **Layer together**: Task Management + Orchestration + Token Efficiency
|
||||
- **Switch dynamically**: Brainstorming → Task Management → Orchestration
|
||||
- **Enhance each other**: Introspection + Task Management for better quality
|
||||
|
||||
---
|
||||
|
||||
## Manual Control 🎛️
|
||||
|
||||
### Force Specific Modes
|
||||
|
||||
```bash
|
||||
# Force Brainstorming Mode
|
||||
/sc:analyze --brainstorm project-requirements
|
||||
|
||||
# Force Token Efficiency
|
||||
/sc:implement --uc user-authentication
|
||||
|
||||
# Force Task Management
|
||||
/sc:refactor --delegate large-codebase/
|
||||
|
||||
# Force Orchestration
|
||||
/sc:build --orchestrate complex-project/
|
||||
|
||||
# Force Introspection
|
||||
/sc:troubleshoot --introspect "reasoning issues"
|
||||
|
||||
# Disable all modes (baseline Claude)
|
||||
/sc:analyze --no-modes legacy-code/
|
||||
```
|
||||
|
||||
### When to Use Manual Control 🤔
|
||||
|
||||
**Force Brainstorming when:**
|
||||
- You have specific requirements but want to explore alternatives
|
||||
- Working with stakeholders who need guided discovery
|
||||
- Converting existing features into comprehensive specs
|
||||
|
||||
**Force Token Efficiency when:**
|
||||
- Working in resource-constrained environments
|
||||
- Need maximum information density
|
||||
- Dealing with very large contexts
|
||||
|
||||
**Force Task Management when:**
|
||||
- Want explicit task breakdown for complex work
|
||||
- Need to coordinate multiple team members
|
||||
- Require detailed progress tracking
|
||||
|
||||
**Force Orchestration when:**
|
||||
- Performance is critical
|
||||
- Want to see tool selection reasoning
|
||||
- Working with multiple MCP servers
|
||||
|
||||
**Force Introspection when:**
|
||||
- Learning how SuperClaude makes decisions
|
||||
- Debugging framework behavior
|
||||
- Want transparent reasoning for auditing
|
||||
|
||||
---
|
||||
|
||||
## Real-World Scenarios 🌍
|
||||
|
||||
### Scenario 1: Building a Task Management App
|
||||
|
||||
**Phase 1: Discovery** (Brainstorming Mode)
|
||||
```bash
|
||||
/sc:brainstorm "task management app for development teams"
|
||||
|
||||
# Mode activates automatically, provides discovery questions:
|
||||
# - What problems do current tools not solve?
|
||||
# - How do teams currently track tasks?
|
||||
# - Integration needs with existing tools?
|
||||
# - Expected team size and usage patterns?
|
||||
|
||||
# Result: Structured requirements brief ready for implementation
|
||||
```
|
||||
|
||||
**Phase 2: Implementation** (Task Management Mode)
|
||||
```bash
|
||||
/sc:implement task-management-app --from-brief requirements.md
|
||||
|
||||
# Mode activates for complex implementation:
|
||||
# Phase 1: Data models and API design
|
||||
# Phase 2: Core functionality and business logic
|
||||
# Phase 3: UI components and user experience
|
||||
# Phase 4: Integration, testing, and deployment
|
||||
|
||||
# Each phase validates before proceeding
|
||||
```
|
||||
|
||||
**Phase 3: Optimization** (Orchestration + Token Efficiency)
|
||||
```bash
|
||||
/sc:improve performance task-management-app/
|
||||
|
||||
# Orchestration selects best tools for analysis
|
||||
# Token Efficiency kicks in for large codebase analysis
|
||||
# Result: Optimized, production-ready application
|
||||
```
|
||||
|
||||
### Scenario 2: Debugging Authentication Issues
|
||||
|
||||
**Investigation** (Introspection Mode)
|
||||
```bash
|
||||
/sc:troubleshoot "users can't log in on mobile but desktop works"
|
||||
|
||||
# Introspection mode analyzes systematically:
|
||||
# 🔍 Pattern analysis: Mobile vs desktop differences
|
||||
# 🤔 Reasoning: What could cause platform-specific auth issues?
|
||||
# 📊 Evidence gathering: Session handling, cookies, API calls
|
||||
# 💡 Hypothesis formation and testing approach
|
||||
```
|
||||
|
||||
**Systematic Fix** (Task Management + Orchestration)
|
||||
```bash
|
||||
/sc:implement auth-mobile-fix
|
||||
|
||||
# Task Management coordinates the fix:
|
||||
# Phase 1: Mobile session analysis (Playwright MCP for testing)
|
||||
# Phase 2: API compatibility fixes (Sequential MCP for logic)
|
||||
# Phase 3: Cross-platform validation (multiple tools)
|
||||
|
||||
# Orchestration ensures optimal tool usage throughout
|
||||
```
|
||||
|
||||
### Scenario 3: Large Codebase Refactoring
|
||||
|
||||
**Planning** (Brainstorming + Introspection)
|
||||
```bash
|
||||
/sc:brainstorm "refactor legacy PHP app to modern architecture"
|
||||
|
||||
# Brainstorming explores scope and requirements
|
||||
# Introspection analyzes current architecture patterns
|
||||
# Result: Clear migration strategy and requirements
|
||||
```
|
||||
|
||||
**Execution** (Task Management + Token Efficiency)
|
||||
```bash
|
||||
/sc:refactor --delegate legacy-app/ --target modern-architecture
|
||||
|
||||
# Task Management breaks into systematic phases
|
||||
# Token Efficiency handles large codebase analysis efficiently
|
||||
# Phase coordination ensures no breaking changes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ 🙋
|
||||
|
||||
### Do I need to understand behavioral modes?
|
||||
|
||||
**No!** They work automatically. You focus on what you want to do, modes handle how SuperClaude helps you. Think of them like having different experts who automatically step in when needed.
|
||||
|
||||
### How do I know which mode is active?
|
||||
|
||||
Look for **behavioral markers**:
|
||||
- 🤔 **Questions and exploration** = Brainstorming Mode
|
||||
- 🔍 **Reasoning analysis symbols** = Introspection Mode
|
||||
- 📋 **Phase breakdowns and delegation** = Task Management Mode
|
||||
- 🎯 **Tool selection matrices** = Orchestration Mode
|
||||
- ⚡ **Symbols and abbreviations** = Token Efficiency Mode
|
||||
|
||||
### Can I disable behavioral modes?
|
||||
|
||||
**Yes!** Use `--no-modes` flag:
|
||||
```bash
|
||||
/sc:analyze --no-modes simple-file.js
|
||||
```
|
||||
|
||||
This gives you baseline Claude behavior without mode enhancements.
|
||||
|
||||
### Which mode should I use manually?
|
||||
|
||||
**Usually none!** Automatic activation works well 95% of the time. Manual control is for:
|
||||
- **Learning**: Force modes to see how they work
|
||||
- **Special cases**: Unusual requirements or constraints
|
||||
- **Team coordination**: Explicit task breakdowns for collaboration
|
||||
- **Performance**: Force efficiency in resource-constrained environments
|
||||
|
||||
### Can multiple modes be active at once?
|
||||
|
||||
**Yes!** Modes often layer together:
|
||||
- Task Management + Orchestration (complex projects with optimal tools)
|
||||
- Introspection + Token Efficiency (deep analysis with compressed output)
|
||||
- Brainstorming + Task Management (discovery → implementation pipeline)
|
||||
|
||||
### Do modes work with all commands?
|
||||
|
||||
Most commands work with modes, but some have natural affinities:
|
||||
- `/sc:brainstorm` → Always Brainstorming Mode
|
||||
- `/sc:troubleshoot` → Often Introspection Mode
|
||||
- `/sc:implement` (complex) → Usually Task Management Mode
|
||||
- Large operations → Often trigger Orchestration Mode
|
||||
- High context → May activate Token Efficiency Mode
|
||||
|
||||
### Are modes related to agents?
|
||||
|
||||
**Yes, but differently!**
|
||||
- **Agents** = Who helps (security-engineer, frontend-architect, etc.)
|
||||
- **Modes** = How they help (systematically, efficiently, collaboratively)
|
||||
|
||||
Modes determine the behavioral approach, agents provide domain expertise. A security-engineer might work in Task Management mode for complex security implementations, or Introspection mode for security analysis.
|
||||
|
||||
---
|
||||
|
||||
## Technical Reference 🔧
|
||||
|
||||
### Complete Trigger Lists
|
||||
|
||||
**Brainstorming Mode Triggers**
|
||||
- **Keywords**: brainstorm, explore, discuss, figure out, not sure, maybe, possibly, thinking about, could we
|
||||
- **Phrases**: "I want to build...", "thinking about creating...", "not sure how to...", "maybe we could..."
|
||||
- **Context**: Vague requirements, early planning, stakeholder discussions
|
||||
- **Manual**: `--brainstorm`, `--bs`
|
||||
|
||||
**Introspection Mode Triggers**
|
||||
- **Keywords**: analyze reasoning, reflect on, why did, decision logic, pattern check
|
||||
- **Context**: Error recovery, unexpected results, complex problem solving, framework discussions
|
||||
- **Indicators**: Multiple failed approaches, recurring issues, need for meta-analysis
|
||||
- **Manual**: `--introspect`, `--introspection`
|
||||
|
||||
**Task Management Mode Triggers**
|
||||
- **Operations**: build, implement, create, fix, refactor (3+ steps)
|
||||
- **Scope**: system, feature, comprehensive, complete, end-to-end
|
||||
- **Thresholds**: >2 directories OR >3 files OR complexity score >0.4
|
||||
- **Keywords**: polish, refine, enhance, coordinate, manage
|
||||
- **Manual**: `--delegate`, `--loop`, `--concurrency`
|
||||
|
||||
**Orchestration Mode Triggers**
|
||||
- **Conditions**: Multi-tool operations, >3 files, parallel opportunities
|
||||
- **Performance**: >75% resource usage, efficiency requirements
|
||||
- **Complexity**: Multiple valid approaches, tool selection decisions
|
||||
- **Manual**: `--orchestrate`
|
||||
|
||||
**Token Efficiency Mode Triggers**
|
||||
- **Resource**: Context >75%, large-scale operations, memory constraints
|
||||
- **User requests**: `--uc`, `--ultracompressed`, brevity requirements
|
||||
- **Workflow**: Complex analysis needing optimization, high information density
|
||||
- **Manual**: `--uc`, `--ultracompressed`, `--token-efficient`
|
||||
|
||||
### Flag Reference Table 🏳️
|
||||
|
||||
| Flag | Mode | Purpose | Usage |
|
||||
|------|------|---------|-------|
|
||||
| `--brainstorm`, `--bs` | Brainstorming | Force discovery mode | Requirements exploration |
|
||||
| `--introspect` | Introspection | Force reasoning analysis | Decision transparency |
|
||||
| `--delegate` | Task Management | Force delegation mode | Complex coordination |
|
||||
| `--delegate` | Task Management | Enable delegation mode | Parallel processing |
|
||||
| `--loop` | Task Management | Enable iteration cycles | Improvement workflows |
|
||||
| `--orchestrate` | Orchestration | Force tool optimization | Performance priority |
|
||||
| `--uc`, `--ultracompressed` | Token Efficiency | Force compression | Resource constraints |
|
||||
| `--no-modes` | None | Disable all modes | Baseline behavior |
|
||||
|
||||
### Integration with Framework Components
|
||||
|
||||
**With Agents** 🤖
|
||||
- Modes determine **how** agents work
|
||||
- Agents provide **domain expertise**
|
||||
- Example: security-engineer in Task Management mode = systematic security implementation
|
||||
|
||||
**With Commands** 🛠️
|
||||
- Commands trigger mode activation
|
||||
- Modes enhance command execution
|
||||
- Example: `/sc:implement` complex features → Task Management mode activation
|
||||
|
||||
**With MCP Servers** 🔧
|
||||
- Orchestration mode optimizes MCP usage
|
||||
- Task Management coordinates multi-MCP operations
|
||||
- Token Efficiency compresses MCP communications
|
||||
|
||||
### Performance Metrics 📊
|
||||
|
||||
**Mode Efficiency Gains**
|
||||
- **Brainstorming**: 60-80% better requirement clarity
|
||||
- **Introspection**: 40-60% improved decision quality
|
||||
- **Task Management**: 40-70% time savings via delegation
|
||||
- **Orchestration**: 20-40% performance improvement via optimal tools
|
||||
- **Token Efficiency**: 30-50% token reduction with 95%+ information preservation
|
||||
|
||||
**Resource Impact**
|
||||
- Brainstorming: Low overhead, high value for unclear requirements
|
||||
- Introspection: Medium overhead, high value for complex problems
|
||||
- Task Management: Variable overhead, scales with task complexity
|
||||
- Orchestration: Low overhead, improves overall efficiency
|
||||
- Token Efficiency: Negative overhead (saves resources), maintains quality
|
||||
|
||||
---
|
||||
|
||||
*Behavioral modes are SuperClaude's intelligence system - they make Claude Code smarter about how it helps you. You don't manage them, they manage themselves to give you the best experience! 🧠✨*
|
||||
|
||||
---
|
||||
|
||||
**Related Guides:**
|
||||
- 🤖 [Agent System Guide](agents-guide.md) - Understanding the 13 specialized agents
|
||||
- 🛠️ [Commands Guide](commands-guide.md) - All 21 commands with mode integration
|
||||
- 🏳️ [Flags Guide](flags-guide.md) - Manual mode control and behavioral flags
|
||||
- 📖 [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview
|
||||
@@ -12,6 +12,14 @@
|
||||
|
||||
**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! 😊
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
SuperClaude commands work by:
|
||||
- **Intelligent activation**: Right experts and tools activated automatically
|
||||
- **Context awareness**: Understanding your project and frameworks
|
||||
- **Safe operations**: Quality gates and validation throughout
|
||||
- **Progressive enhancement**: Building from simple to complex solutions
|
||||
|
||||
---
|
||||
|
||||
## Quick "Just Try These" List 🚀
|
||||
@@ -33,7 +41,7 @@
|
||||
|
||||
---
|
||||
|
||||
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.
|
||||
A practical guide to all 21 SuperClaude v4.0.0 slash commands. We'll be honest about what works well and what's still rough around the edges.
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
@@ -78,12 +86,12 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
- 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.
|
||||
**The magic**: Auto-activates appropriate expert agents (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 "user authentication system" --agent security --output detailed
|
||||
/sc:workflow payment-api --strategy mvp --risks --dependencies
|
||||
```
|
||||
|
||||
@@ -132,10 +140,10 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
```
|
||||
|
||||
**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
|
||||
- **Frontend**: UI components, React/Vue/Angular → frontend agent + Magic MCP
|
||||
- **Backend**: APIs, services, databases → backend agent + Context7
|
||||
- **Security**: Auth, payments, sensitive data → security agent + validation
|
||||
- **Complex features**: Multi-step implementations → Sequential MCP + architect agent
|
||||
|
||||
**Gotchas**:
|
||||
- Specify `--type` for better results (component vs service vs feature)
|
||||
@@ -275,14 +283,14 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
|
||||
**Useful flags**:
|
||||
- `--logs <file>` - Include log file analysis
|
||||
- `--systematic` - Use structured debugging approach
|
||||
- `--seq` - 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
|
||||
/sc:troubleshoot "build failing" --seq
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
@@ -842,7 +850,7 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
|
||||
### Common Workflows
|
||||
|
||||
**New Project Discovery** (V4 Beta):
|
||||
**New Project Discovery**:
|
||||
```bash
|
||||
/sc:brainstorm "project idea" --prd # Explore and define requirements
|
||||
/sc:load --deep --summary # Understand existing codebase
|
||||
@@ -884,7 +892,7 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
/sc:save --checkpoint "pre-deployment validation"
|
||||
```
|
||||
|
||||
**Complex Task Planning** (V4 Beta):
|
||||
**Complex Task Planning**:
|
||||
```bash
|
||||
/sc:select-tool "migrate to microservices" # Get approach recommendations
|
||||
/sc:reflect --type task "migration strategy" # Validate approach
|
||||
@@ -942,6 +950,65 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest
|
||||
|
||||
**Need help?** Check the GitHub issues or create a new one if you're stuck! 🚀
|
||||
|
||||
## Command Flags & Options
|
||||
|
||||
### Common Flags
|
||||
- `--safe` - Conservative operations with validation
|
||||
- `--interactive` - Guided operation with user input
|
||||
- `--parallel` - Parallel execution where applicable
|
||||
- `--preview` - Show changes without applying
|
||||
- `--analyze` - Deep analysis mode
|
||||
- `--validate` - Enhanced validation and verification
|
||||
- `--depth shallow|normal|deep` - Analysis depth control
|
||||
- `--strategy systematic|agile|enterprise` - Execution strategy
|
||||
|
||||
### Format Options
|
||||
- `--format text|json|yaml|report|diagram` - Output format control
|
||||
- `--type` - Operation type specification (varies by command)
|
||||
- `--style brief|detailed` - Output verbosity control
|
||||
|
||||
## Expert Activation
|
||||
|
||||
The framework automatically activates relevant experts:
|
||||
|
||||
### Technical Specialists
|
||||
- **Backend Architect** - Server architecture, APIs, databases
|
||||
- **DevOps Architect** - Infrastructure, deployment, CI/CD
|
||||
- **Frontend Architect** - UI architecture, state management, performance
|
||||
- **Learning Guide** - Educational content, knowledge transfer
|
||||
- **Performance Engineer** - Optimization, profiling, scalability
|
||||
- **Python Expert** - Python-specific development and best practices
|
||||
- **Quality Engineer** - Testing, quality assurance, code standards
|
||||
- **Refactoring Expert** - Code restructuring and technical debt
|
||||
- **Requirements Analyst** - Requirements gathering and analysis
|
||||
- **Root Cause Analyst** - Problem diagnosis and systematic debugging
|
||||
- **Security Engineer** - Security assessment and hardening
|
||||
- **Technical Writer** - Documentation and communication
|
||||
|
||||
### MCP Server Integration
|
||||
- **Context7** - Official documentation and framework patterns
|
||||
- **Magic** - Modern UI component generation
|
||||
- **Morphllm** - Pattern-based code editing and transformations
|
||||
- **Playwright** - Browser automation and E2E testing
|
||||
- **Sequential** - Complex multi-step reasoning and analysis
|
||||
- **Serena** - Project memory and session management
|
||||
|
||||
## Command Relationships
|
||||
|
||||
### Session Flow
|
||||
`/sc:load` → Work with commands → `/sc:reflect` (validate) → `/sc:save`
|
||||
|
||||
### Development Flow
|
||||
`/sc:analyze` → `/sc:design` → `/sc:implement` → `/sc:test` → `/sc:improve`
|
||||
|
||||
### Project Flow
|
||||
`/sc:brainstorm` → `/sc:workflow` → `/sc:estimate` → `/sc:spawn` or `/sc:task`
|
||||
|
||||
### Maintenance Flow
|
||||
`/sc:troubleshoot` → `/sc:cleanup` → `/sc:improve` → `/sc:document`
|
||||
|
||||
Remember: SuperClaude adapts to your needs. Start with simple requests and let the framework's intelligence guide you to more sophisticated usage patterns!
|
||||
|
||||
---
|
||||
|
||||
*Happy coding! Just remember - you can skip most of this guide and learn by doing. 🎯*
|
||||
@@ -1,4 +1,4 @@
|
||||
# SuperClaude V4 Beta Flags User Guide 🏁
|
||||
# SuperClaude Framework Flags User Guide 🏁
|
||||
|
||||
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
**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`
|
||||
- **Usually activates** security-engineer agent, `--focus security`, `--validate`
|
||||
- You often get expert security analysis without managing any flags
|
||||
|
||||
**When might you manually use flags?**
|
||||
@@ -26,8 +26,8 @@
|
||||
/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
|
||||
/sc:troubleshoot "weird error" # Auto-activates root-cause-analyst and debugging flags
|
||||
/sc:brainstorm "my app idea" # Auto-activates requirements-analyst agent for discovery
|
||||
```
|
||||
|
||||
**See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes.
|
||||
@@ -148,7 +148,7 @@ Enable specialized capabilities through MCP servers.
|
||||
#### `--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
|
||||
**Auto-activates**: UI component requests, frontend architect agent
|
||||
**Example**: `/build dashboard --magic` - Get modern UI components
|
||||
|
||||
#### `--play` / `--playwright`
|
||||
@@ -157,8 +157,8 @@ Enable specialized capabilities through MCP servers.
|
||||
**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
|
||||
#### `--morph` / `--morphllm`
|
||||
**What it does**: Enables Morphllm for intelligent file editing and pattern transformations
|
||||
**When to use**: Multi-file edits, pattern-based transformations
|
||||
**Auto-activates**: Complex refactoring, bulk file updates
|
||||
**Example**: `/refactor --morph pattern-updates/`
|
||||
@@ -199,12 +199,6 @@ For complex operations and workflows.
|
||||
|
||||
**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
|
||||
@@ -232,7 +226,7 @@ For complex operations and workflows.
|
||||
|
||||
### Session & Workflow Flags 🔄
|
||||
|
||||
These V4 Beta flags control session management and advanced workflows.
|
||||
These SuperClaude Framework flags control session management and advanced workflows.
|
||||
|
||||
#### `--brainstorm`
|
||||
**What it does**: Activates brainstorming mode for requirements discovery
|
||||
@@ -251,7 +245,7 @@ These V4 Beta flags control session management and advanced workflows.
|
||||
**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.
|
||||
**💡 Tip**: SuperClaude Framework introduces powerful session management - let brainstorming mode guide requirement discovery naturally.
|
||||
|
||||
---
|
||||
|
||||
@@ -270,9 +264,9 @@ Direct SuperClaude's attention to specific areas.
|
||||
**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
|
||||
**Available agents**: system-architect, backend-architect, frontend-architect, devops-architect, security-engineer, performance-engineer, root-cause-analyst, quality-engineer, refactoring-expert, python-expert, requirements-analyst, technical-writer, learning-guide
|
||||
**What they do**: Activates specialized domain expert agents (SuperClaude Framework enhancement)
|
||||
**Example**: `/analyze --agent security-engineer` - Security-focused analysis with expert agent
|
||||
|
||||
**💡 Tip**: `--focus` is great for targeted analysis. Expert agents auto-activate but manual control helps.
|
||||
|
||||
@@ -295,13 +289,13 @@ Direct SuperClaude's attention to specific areas.
|
||||
### Large Project Work
|
||||
```bash
|
||||
/sc:analyze monorepo/ --delegate auto --uc # Efficient large analysis
|
||||
/sc:improve legacy/ --wave-mode auto --safe-mode # Safe systematic improvement
|
||||
/sc:improve legacy/ --loop --safe-mode # Safe iterative improvement
|
||||
```
|
||||
|
||||
### Learning & Documentation
|
||||
```bash
|
||||
/sc:explain React hooks --c7 --verbose # Detailed explanation with docs
|
||||
/sc:document api/ --persona-scribe # Professional documentation
|
||||
/sc:document api/ --agent technical-writer # Professional documentation
|
||||
```
|
||||
|
||||
### Performance-Focused
|
||||
@@ -313,7 +307,7 @@ Direct SuperClaude's attention to specific areas.
|
||||
### Security-Focused
|
||||
```bash
|
||||
/sc:analyze --focus security --think --validate # Thorough security analysis
|
||||
/sc:scan --persona-security --safe-mode # Conservative security scan
|
||||
/sc:scan --agent security-engineer --safe-mode # Conservative security scan
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
@@ -355,8 +349,8 @@ Direct SuperClaude's attention to specific areas.
|
||||
|
||||
**After** (safe):
|
||||
```bash
|
||||
/sc:improve legacy-system/ --safe-mode --loop --validate --preview
|
||||
# → Safe changes only, iterative approach, validates first, shows preview
|
||||
/sc:improve legacy-system/ --safe-mode --loop --validate
|
||||
# → Safe changes only, iterative approach, validates first, systematic improvement
|
||||
# → Much safer, progressive improvement
|
||||
```
|
||||
|
||||
@@ -378,11 +372,11 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
### Domain-Based
|
||||
```bash
|
||||
/sc:build react-app/
|
||||
# Auto-activates: frontend-specialist agent + --c7
|
||||
# Auto-activates: frontend-architect agent + --c7
|
||||
# Why: Frontend framework detected
|
||||
|
||||
/sc:analyze --focus security
|
||||
# Auto-activates: security-auditor agent + --validate
|
||||
# Auto-activates: security-engineer agent + --validate
|
||||
# Why: Security focus triggers security specialist
|
||||
```
|
||||
|
||||
@@ -405,20 +399,20 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
|
||||
**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
|
||||
/sc:review codebase/ --agent quality-engineer --think-hard --focus quality --validate --c7
|
||||
# → Quality engineer 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
|
||||
/sc:improve legacy/ --delegate auto --agent system-architect --safe-mode --loop --c7
|
||||
# → Systematic 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
|
||||
/sc:scan --agent security-engineer --ultrathink --focus security --validate --seq
|
||||
# → Security engineer agent + maximum thinking + security focus + validation + systematic analysis
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
@@ -440,14 +434,14 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
**Bug Investigation Workflow**:
|
||||
```bash
|
||||
/sc:troubleshoot "specific error" --seq --think --validate
|
||||
/sc:analyze affected-files/ --focus quality --agent root-cause-analyzer
|
||||
/sc:analyze affected-files/ --focus quality --agent root-cause-analyst
|
||||
/sc:test --play --coverage
|
||||
```
|
||||
|
||||
**Feature Development Workflow**:
|
||||
```bash
|
||||
/sc:design new-feature --agent system-architect --c7
|
||||
/sc:build --magic --agent frontend-specialist --validate
|
||||
/sc:build --magic --agent frontend-architect --validate
|
||||
/sc:test --play --coverage
|
||||
/sc:document --agent technical-writer --c7
|
||||
```
|
||||
@@ -471,7 +465,7 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
### Flag Combinations That Work Well
|
||||
```bash
|
||||
# Safe improvement
|
||||
--safe-mode --validate --preview
|
||||
--safe-mode --validate
|
||||
|
||||
# Deep analysis
|
||||
--think --seq --c7
|
||||
@@ -480,13 +474,13 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
--delegate auto --uc --focus
|
||||
|
||||
# Learning
|
||||
--verbose --c7 --agent code-educator
|
||||
--verbose --c7 --agent learning-guide
|
||||
|
||||
# Security work
|
||||
--agent security-auditor --focus security --validate
|
||||
--agent security-engineer --focus security --validate
|
||||
|
||||
# Performance work
|
||||
--agent performance-optimizer --focus performance --play
|
||||
--agent performance-engineer --focus performance --play
|
||||
|
||||
# Requirements discovery
|
||||
--brainstorm --max-rounds 10 --prd
|
||||
@@ -508,7 +502,7 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
### Common Problems
|
||||
|
||||
**"Flags don't seem to work"**
|
||||
- Check spelling (common typos: `--ultracompresed`, `--agent fronted-specialist`)
|
||||
- Check spelling (common typos: `--ultracompresed`, `--agent frontend-architect`)
|
||||
- Some flags need values: `--scope project`, `--focus security`
|
||||
- Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, `--serena`, etc.
|
||||
|
||||
@@ -525,19 +519,19 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
**"Not thorough enough"**
|
||||
- Add `--think` or `--think-hard`
|
||||
- Enable relevant MCP servers: `--seq`, `--c7`
|
||||
- Use appropriate agent: `--agent root-cause-analyzer`
|
||||
- Use appropriate agent: `--agent root-cause-analyst`
|
||||
|
||||
**"Changes too risky"**
|
||||
- Always use `--safe-mode` for important code
|
||||
- Add `--validate` to check first
|
||||
- Use `--preview` to see changes before applying
|
||||
- Use `--validate` to check 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
|
||||
- Last agent flag wins: `--agent frontend-architect --agent backend-architect` → backend-architect
|
||||
|
||||
**Precedence order**:
|
||||
1. Safety flags (`--safe-mode`) beat optimization
|
||||
@@ -554,7 +548,7 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
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
|
||||
1. **Experiment with overrides** - Try `--agent security-engineer` 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
|
||||
@@ -562,8 +556,8 @@ SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
### 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 safety**: `--safe-mode --validate`
|
||||
- **For learning**: `--verbose --c7 --agent learning-guide`
|
||||
- **For project discovery**: `--brainstorm --max-rounds 15 --prd`
|
||||
|
||||
---
|
||||
449
Guides/installation-guide.md
Normal file
449
Guides/installation-guide.md
Normal file
@@ -0,0 +1,449 @@
|
||||
# SuperClaude Installation Guide 📦
|
||||
|
||||
## 🎯 It's Easier Than It Looks!
|
||||
|
||||
**The honest truth**: This guide looks comprehensive because we want to cover all the details, but installation is actually simple. Most people are done in 2 minutes with one command!
|
||||
|
||||
## Quick Start 🚀
|
||||
|
||||
**🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)**
|
||||
|
||||
### Option A: From PyPI (Recommended)
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
|
||||
# Install with interactive selection
|
||||
SuperClaude install
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
|
||||
### Option B: From Source
|
||||
```bash
|
||||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
pip install .
|
||||
|
||||
# Install with interactive selection
|
||||
SuperClaude install
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
|
||||
**What you just got:**
|
||||
- ✅ 21 intelligent commands that auto-activate specialized capabilities
|
||||
- ✅ 13 specialized AI agents with domain expertise and smart routing
|
||||
- ✅ 5 behavioral modes for different types of work
|
||||
- ✅ 6 MCP servers for extended functionality (optional)
|
||||
- ✅ Session lifecycle management with persistent context
|
||||
- ✅ About 2 minutes of your time and ~50MB disk space
|
||||
|
||||
**Nervous about what it will do?** See first with:
|
||||
```bash
|
||||
SuperClaude install --dry-run
|
||||
```
|
||||
|
||||
## 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 Code** - 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 Code is available
|
||||
claude --version
|
||||
|
||||
# Check Node.js (optional, for MCP servers)
|
||||
node --version
|
||||
```
|
||||
|
||||
If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below.
|
||||
|
||||
## Installation Options 🎛️
|
||||
|
||||
### 🎯 Interactive Installation (Default - Recommended)
|
||||
```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
|
||||
- **Available components**: core, commands, agents, modes, mcp, mcp_docs
|
||||
- **Good for**: Users who know exactly what they want
|
||||
|
||||
### 🔍 Other Useful Options
|
||||
```bash
|
||||
# See all available components
|
||||
SuperClaude install --list-components
|
||||
|
||||
# See what would be installed without doing it
|
||||
SuperClaude install --dry-run
|
||||
|
||||
# System diagnostics and installation help
|
||||
SuperClaude install --diagnose
|
||||
|
||||
# Quiet installation (minimal output)
|
||||
SuperClaude install --quiet
|
||||
|
||||
# Install everything
|
||||
SuperClaude install --components all
|
||||
```
|
||||
|
||||
## 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 use winget
|
||||
winget install python
|
||||
```
|
||||
|
||||
**Missing Claude Code?**
|
||||
- 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 use winget
|
||||
winget install nodejs
|
||||
```
|
||||
|
||||
### Getting SuperClaude 📥
|
||||
|
||||
**Option 1: From PyPI (Recommended)**
|
||||
```bash
|
||||
pip install SuperClaude
|
||||
```
|
||||
|
||||
**Option 2: 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 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 specific components
|
||||
SuperClaude install --components core commands agents modes
|
||||
|
||||
# Quiet installation (minimal output)
|
||||
SuperClaude install --quiet
|
||||
```
|
||||
|
||||
### During Installation 📱
|
||||
|
||||
Here's what happens when you install:
|
||||
|
||||
1. **System Check** - Verifies you have required dependencies
|
||||
2. **Component Selection** - Interactive selection of what to install
|
||||
3. **MCP Server Setup** - Downloads and configures MCP servers (if selected)
|
||||
4. **API Key Collection** - Prompts for required API keys for selected servers
|
||||
5. **Framework Installation** - Copies framework documentation files
|
||||
6. **Configuration Setup** - Creates settings and CLAUDE.md imports
|
||||
7. **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, RULES.md, PRINCIPLES.md, etc.
|
||||
```
|
||||
|
||||
**Test with Claude Code:**
|
||||
1. Open Claude Code
|
||||
2. Try typing `/sc:help` - you should see SuperClaude commands
|
||||
3. Try `/sc:analyze --help` - should show command options
|
||||
|
||||
### What Got Installed 📂
|
||||
|
||||
SuperClaude 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
|
||||
├── MCP_*.md # MCP server configurations
|
||||
├── MODE_*.md # Behavioral modes
|
||||
├── settings.json # Configuration file (if created)
|
||||
└── SuperClaude/ # Framework components
|
||||
├── Core/ # Core framework files
|
||||
├── Commands/ # 21 command definitions
|
||||
├── Agents/ # 13 specialized agents
|
||||
├── Modes/ # 5 behavioral modes
|
||||
└── MCP/ # MCP server configurations
|
||||
```
|
||||
|
||||
**What each file does:**
|
||||
- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files
|
||||
- **RULES.md** - Operational rules and workflow patterns
|
||||
- **PRINCIPLES.md** - Development principles and decision frameworks
|
||||
- **FLAGS.md** - Command flags and behavioral controls
|
||||
- **SuperClaude/** - Complete framework with commands, agents, and modes
|
||||
|
||||
### 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 brainstorming mode
|
||||
/sc:load # Initialize session with context
|
||||
```
|
||||
|
||||
**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want.
|
||||
|
||||
## Managing Your Installation 🛠️
|
||||
|
||||
### Updates 📅
|
||||
|
||||
Keep SuperClaude up to date:
|
||||
|
||||
```bash
|
||||
# Update the package
|
||||
pip install --upgrade SuperClaude
|
||||
|
||||
# Reinstall components
|
||||
SuperClaude install --force
|
||||
|
||||
# Update specific components only
|
||||
SuperClaude install --components core commands --force
|
||||
```
|
||||
|
||||
### Backups 💾
|
||||
|
||||
SuperClaude automatically creates backups during installation. You can also create manual backups of your `~/.claude/` directory:
|
||||
|
||||
```bash
|
||||
# Create a backup
|
||||
cp -r ~/.claude/ ~/.claude_backup_$(date +%Y%m%d)
|
||||
|
||||
# Restore from backup
|
||||
rm -rf ~/.claude/
|
||||
cp -r ~/.claude_backup_20250115/ ~/.claude/
|
||||
```
|
||||
|
||||
### Uninstallation 🗑️
|
||||
|
||||
If you need to remove SuperClaude:
|
||||
|
||||
```bash
|
||||
# Remove just the package
|
||||
pip uninstall SuperClaude
|
||||
|
||||
# Remove all SuperClaude files (keeps your other Claude settings)
|
||||
rm -rf ~/.claude/SuperClaude/
|
||||
rm -f ~/.claude/CLAUDE.md ~/.claude/RULES.md ~/.claude/PRINCIPLES.md ~/.claude/FLAGS.md
|
||||
rm -f ~/.claude/MCP_*.md ~/.claude/MODE_*.md
|
||||
```
|
||||
|
||||
**What gets removed:**
|
||||
- All SuperClaude files in `~/.claude/`
|
||||
- The SuperClaude Python package
|
||||
|
||||
**What stays:**
|
||||
- Your other Claude Code settings
|
||||
- Your projects and other files
|
||||
- Any backups you created
|
||||
|
||||
## 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 Code not found"**
|
||||
- Make sure Claude Code is installed first
|
||||
- Visit https://claude.ai/code for installation help
|
||||
|
||||
**"Permission denied"**
|
||||
```bash
|
||||
# Try with explicit Python path
|
||||
/usr/bin/python3 -m SuperClaude install
|
||||
|
||||
# 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: select "Skip MCP Server installation" during interactive setup
|
||||
|
||||
**"Installation fails partway through"**
|
||||
```bash
|
||||
# Try with verbose output to see what's happening
|
||||
SuperClaude install --verbose
|
||||
|
||||
# Or try a dry run first
|
||||
SuperClaude install --dry-run
|
||||
|
||||
# Try system diagnostics
|
||||
SuperClaude install --diagnose
|
||||
```
|
||||
|
||||
### 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 Code version (`claude --version`)
|
||||
- The exact command you ran
|
||||
- The complete error message
|
||||
- What you expected to happen
|
||||
|
||||
## Advanced Options ⚙️
|
||||
|
||||
### Custom Installation Directory
|
||||
```bash
|
||||
# Install to custom location
|
||||
SuperClaude install --install-dir /custom/path
|
||||
|
||||
# Use environment variable
|
||||
export SUPERCLAUDE_DIR=/custom/path
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
If you're planning to contribute or modify SuperClaude:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
|
||||
# Install in development mode
|
||||
pip install -e .
|
||||
|
||||
# Install all components
|
||||
SuperClaude install --components all
|
||||
```
|
||||
|
||||
## What's Next? 🚀
|
||||
|
||||
**Now that SuperClaude is installed:**
|
||||
|
||||
1. **Just start using it** - Try `/sc:analyze some-file.js` or `/sc:build` and see what happens ✨
|
||||
2. **Don't stress about learning** - SuperClaude usually figures out what you need
|
||||
3. **Experiment freely** - Commands like `/sc:improve` and `/sc:troubleshoot` are pretty forgiving
|
||||
4. **Use session management** - Try `/sc:load` and `/sc:save` for persistent context
|
||||
5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically
|
||||
6. **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 `/sc:help` and `/sc:analyze README.md` - you'll see how approachable 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 actively read and respond to issues
|
||||
- **Available commands**: Use `SuperClaude [command]`, `python3 -m SuperClaude [command]`, or `/sc:[command]` in Claude Code
|
||||
|
||||
Thanks for trying SuperClaude! We hope it makes your development workflow smoother and more intelligent. 🙂
|
||||
|
||||
---
|
||||
|
||||
*Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!*
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user