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
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
|
||||
1014
Guides/commands-guide.md
Normal file
1014
Guides/commands-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
593
Guides/flags-guide.md
Normal file
593
Guides/flags-guide.md
Normal file
@@ -0,0 +1,593 @@
|
||||
# SuperClaude Framework Flags User Guide 🏁
|
||||
|
||||
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
|
||||
|
||||
**The honest truth**: You don't need to memorize these flags. SuperClaude usually tries to add helpful ones based on what you're doing!
|
||||
|
||||
**Here's what actually happens:**
|
||||
- You type `/analyze auth.js`
|
||||
- SuperClaude detects it's security-related code
|
||||
- **Usually activates** security-engineer agent, `--focus security`, `--validate`
|
||||
- You often get expert security analysis without managing any flags
|
||||
|
||||
**When might you manually use flags?**
|
||||
- You want to **override** what SuperClaude picked (rare)
|
||||
- You're **curious** about specific aspects (`--focus performance`)
|
||||
- You want to **experiment** with different approaches
|
||||
|
||||
**Bottom line**: Just use basic commands and let the auto-activation work. These flags are here when you want them, not because you need them. 🎯
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Just Try These (No Flag Knowledge Required)
|
||||
|
||||
```bash
|
||||
# These work great with zero flag knowledge:
|
||||
/sc:analyze src/ # Auto-activates appropriate expert agents
|
||||
/sc:build # Auto-optimizes based on your project
|
||||
/sc:improve messy-code.js # Auto-activates quality agents and safety flags
|
||||
/sc:troubleshoot "weird error" # Auto-activates root-cause-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.
|
||||
|
||||
---
|
||||
|
||||
A practical guide to SuperClaude's flag system. Flags are like command-line options that change how SuperClaude behaves - think of them as superpowers for your commands.
|
||||
|
||||
## What Are Flags? 🤔
|
||||
|
||||
**Flags are modifiers** that change how SuperClaude processes your requests. They come after commands and start with `--`.
|
||||
|
||||
**Basic syntax** (but you usually don't need to know this):
|
||||
```bash
|
||||
/sc:command --flag-name
|
||||
/sc:command --flag-name value
|
||||
/sc:analyze src/ --focus security --depth deep
|
||||
```
|
||||
|
||||
**How flags actually work in practice**:
|
||||
1. **Auto-activation** - SuperClaude adds them based on context (this is the main way! 🎯)
|
||||
2. **Manual override** - You can add them explicitly if you want different behavior
|
||||
|
||||
**Why flags exist** (mostly automatic benefits):
|
||||
- Get better, more focused results
|
||||
- Auto-enable the right thinking depth
|
||||
- Connect to special capabilities when useful
|
||||
- Optimize for speed or detail based on your task
|
||||
- Direct attention to what you're actually working on
|
||||
|
||||
**The key point**: SuperClaude handles flag selection intelligently so you don't have to think about it! 🧠
|
||||
|
||||
## Flag Categories 📂
|
||||
|
||||
### Planning & Analysis Flags 🧠
|
||||
|
||||
These control how deeply SuperClaude thinks about your request.
|
||||
|
||||
#### `--plan`
|
||||
**What it does**: Shows execution plan before doing anything
|
||||
**When to use**: When you want to see what SuperClaude will do first
|
||||
**Example**: `/build --plan` - See build steps before running
|
||||
|
||||
#### `--think`
|
||||
**What it does**: Multi-file analysis (~4K tokens)
|
||||
**When to use**: Complex problems involving several files
|
||||
**Auto-activates**: Import chains >5 files, cross-module calls >10 references
|
||||
**Example**: `/analyze complex-system/ --think`
|
||||
|
||||
#### `--think-hard`
|
||||
**What it does**: Deep architectural analysis (~10K tokens)
|
||||
**When to use**: System-wide problems, architectural decisions
|
||||
**Auto-activates**: System refactoring, bottlenecks >3 modules
|
||||
**Example**: `/improve legacy-system/ --think-hard`
|
||||
|
||||
#### `--ultrathink`
|
||||
**What it does**: Maximum depth analysis (~32K tokens)
|
||||
**When to use**: Critical system redesign, complex debugging
|
||||
**Auto-activates**: Legacy modernization, critical vulnerabilities
|
||||
**Example**: `/troubleshoot "entire auth system broken" --ultrathink`
|
||||
|
||||
**💡 Tip**: Start with `--think`, only go deeper if needed. More thinking = slower but more thorough.
|
||||
|
||||
---
|
||||
|
||||
### Efficiency & Control Flags ⚡
|
||||
|
||||
Control output style, safety, and performance.
|
||||
|
||||
#### `--uc` / `--ultracompressed`
|
||||
**What it does**: 60-80% token reduction using symbols
|
||||
**When to use**: Large operations, when context is getting full
|
||||
**Auto-activates**: Context usage >75%, large-scale operations
|
||||
**Example**: `/analyze huge-codebase/ --uc`
|
||||
|
||||
#### `--safe-mode`
|
||||
**What it does**: Maximum validation, conservative execution
|
||||
**When to use**: Production environments, risky operations
|
||||
**Auto-activates**: Resource usage >85%, production environment
|
||||
**Example**: `/improve production-code/ --safe-mode`
|
||||
|
||||
#### `--validate`
|
||||
**What it does**: Pre-operation validation and risk assessment
|
||||
**When to use**: Want to check before making changes
|
||||
**Auto-activates**: Risk score >0.7
|
||||
**Example**: `/cleanup legacy/ --validate`
|
||||
|
||||
#### `--verbose`
|
||||
**What it does**: Maximum detail and explanation
|
||||
**When to use**: Learning, debugging, need full context
|
||||
**Example**: `/build --verbose` - See every build step
|
||||
|
||||
#### `--answer-only`
|
||||
**What it does**: Direct response without task creation
|
||||
**When to use**: Quick questions, don't want workflow automation
|
||||
**Example**: `/explain React hooks --answer-only`
|
||||
|
||||
**💡 Tip**: `--uc` is great for big operations. `--safe-mode` for anything important. `--verbose` when you're learning.
|
||||
|
||||
---
|
||||
|
||||
### MCP Server Flags 🔧
|
||||
|
||||
Enable specialized capabilities through MCP servers.
|
||||
|
||||
#### `--c7` / `--context7`
|
||||
**What it does**: Enables Context7 for official library documentation
|
||||
**When to use**: Working with frameworks, need official docs
|
||||
**Auto-activates**: External library imports, framework questions
|
||||
**Example**: `/build react-app/ --c7` - Get React best practices
|
||||
|
||||
#### `--seq` / `--sequential`
|
||||
**What it does**: Enables Sequential for complex multi-step analysis
|
||||
**When to use**: Complex debugging, system design
|
||||
**Auto-activates**: Complex debugging, `--think` flags
|
||||
**Example**: `/troubleshoot "auth flow broken" --seq`
|
||||
|
||||
#### `--magic`
|
||||
**What it does**: Enables Magic for UI component generation
|
||||
**When to use**: Creating UI components, design systems
|
||||
**Auto-activates**: UI component requests, frontend architect agent
|
||||
**Example**: `/build dashboard --magic` - Get modern UI components
|
||||
|
||||
#### `--play` / `--playwright`
|
||||
**What it does**: Enables Playwright for browser automation and testing
|
||||
**When to use**: E2E testing, performance monitoring
|
||||
**Auto-activates**: Test workflows, QA specialist agent
|
||||
**Example**: `/test e2e --play`
|
||||
|
||||
#### `--morph` / `--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/`
|
||||
|
||||
#### `--serena` / `--semantic`
|
||||
**What it does**: Enables Serena for semantic analysis and memory operations
|
||||
**When to use**: Symbol analysis, project-wide context, session management
|
||||
**Auto-activates**: Complex symbol operations, memory commands
|
||||
**Example**: `/analyze --serena --semantic large-codebase/`
|
||||
|
||||
#### `--all-mcp`
|
||||
**What it does**: Enables all MCP servers simultaneously
|
||||
**When to use**: Complex multi-domain problems
|
||||
**Auto-activates**: Problem complexity >0.8, multi-domain indicators
|
||||
**Example**: `/analyze entire-app/ --all-mcp`
|
||||
|
||||
#### `--no-mcp`
|
||||
**What it does**: Disables all MCP servers, native tools only
|
||||
**When to use**: Faster execution, don't need specialized features
|
||||
**Example**: `/analyze simple-script.js --no-mcp`
|
||||
|
||||
**💡 Tip**: MCP servers add capabilities but use more tokens. `--c7` for docs, `--seq` for thinking, `--magic` for UI, `--serena` for memory & semantic analysis.
|
||||
|
||||
---
|
||||
|
||||
### Advanced Orchestration Flags 🎭
|
||||
|
||||
For complex operations and workflows.
|
||||
|
||||
#### `--delegate [files|folders|auto]`
|
||||
**What it does**: Enables sub-agent delegation for parallel processing
|
||||
**When to use**: Large codebases, complex analysis
|
||||
**Auto-activates**: >7 directories or >50 files
|
||||
**Options**:
|
||||
- `files` - Delegate individual file analysis
|
||||
- `folders` - Delegate directory-level analysis
|
||||
- `auto` - Smart delegation strategy
|
||||
|
||||
**Example**: `/analyze monorepo/ --delegate auto`
|
||||
|
||||
#### `--loop`
|
||||
**What it does**: Iterative improvement mode
|
||||
**When to use**: Quality improvement, refinement operations
|
||||
**Auto-activates**: Polish, refine, enhance keywords
|
||||
**Example**: `/improve messy-code.js --loop`
|
||||
|
||||
#### `--iterations [n]`
|
||||
**What it does**: Control number of improvement cycles (1-10)
|
||||
**When to use**: Controlling iterative enhancement depth
|
||||
**Example**: `/improve --loop --iterations 5`
|
||||
|
||||
#### `--interactive`
|
||||
**What it does**: Enables user confirmation between iterations
|
||||
**When to use**: Want control over iterative process
|
||||
**Example**: `/improve --loop --interactive`
|
||||
|
||||
#### `--concurrency [n]`
|
||||
**What it does**: Control max concurrent sub-agents (1-15)
|
||||
**When to use**: Controlling resource usage
|
||||
**Example**: `/analyze --delegate auto --concurrency 3`
|
||||
|
||||
**💡 Tip**: These are powerful but complex. Start with `--delegate auto` for big projects, `--loop` for improvements.
|
||||
|
||||
---
|
||||
|
||||
### Session & Workflow Flags 🔄
|
||||
|
||||
These SuperClaude Framework flags control session management and advanced workflows.
|
||||
|
||||
#### `--brainstorm`
|
||||
**What it does**: Activates brainstorming mode for requirements discovery
|
||||
**When to use**: Ambiguous project ideas, need specification development
|
||||
**Auto-activates**: Exploration keywords, "not sure", project planning
|
||||
**Example**: `/brainstorm "task management app" --brainstorm`
|
||||
|
||||
#### `--max-rounds [n]`
|
||||
**What it does**: Controls brainstorming dialogue rounds (default: 15)
|
||||
**When to use**: Controlling brainstorming session depth
|
||||
**Example**: `/brainstorm idea --max-rounds 10`
|
||||
|
||||
#### `--prd`
|
||||
**What it does**: Generates Product Requirements Document from brainstorming
|
||||
**When to use**: Convert discussions to formal specifications
|
||||
**Auto-activates**: End of successful brainstorming sessions
|
||||
**Example**: `/brainstorm app-idea --prd`
|
||||
|
||||
**💡 Tip**: SuperClaude Framework introduces powerful session management - let brainstorming mode guide requirement discovery naturally.
|
||||
|
||||
---
|
||||
|
||||
### Focus & Scope Flags 🎯
|
||||
|
||||
Direct SuperClaude's attention to specific areas.
|
||||
|
||||
#### `--scope [level]`
|
||||
**Options**: file, module, project, system
|
||||
**What it does**: Sets analysis scope
|
||||
**Example**: `/analyze --scope module auth/`
|
||||
|
||||
#### `--focus [domain]`
|
||||
**Options**: performance, security, quality, architecture, accessibility, testing
|
||||
**What it does**: Focuses analysis on specific domain
|
||||
**Example**: `/analyze --focus security --scope project`
|
||||
|
||||
#### Agent Flags
|
||||
**Available agents**: system-architect, 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.
|
||||
|
||||
---
|
||||
|
||||
## Common Flag Patterns 🔄
|
||||
|
||||
### Quick Analysis
|
||||
```bash
|
||||
/sc:analyze src/ --focus quality # Quick quality check
|
||||
/sc:analyze --uc --focus security # Fast security scan
|
||||
```
|
||||
|
||||
### Deep Investigation
|
||||
```bash
|
||||
/sc:troubleshoot "bug" --think --seq # Systematic debugging
|
||||
/sc:analyze --think-hard --focus architecture # Architectural analysis
|
||||
```
|
||||
|
||||
### Large Project Work
|
||||
```bash
|
||||
/sc:analyze monorepo/ --delegate auto --uc # Efficient large analysis
|
||||
/sc:improve legacy/ --loop --safe-mode # Safe iterative improvement
|
||||
```
|
||||
|
||||
### Learning & Documentation
|
||||
```bash
|
||||
/sc:explain React hooks --c7 --verbose # Detailed explanation with docs
|
||||
/sc:document api/ --agent technical-writer # Professional documentation
|
||||
```
|
||||
|
||||
### Performance-Focused
|
||||
```bash
|
||||
/sc:analyze --focus performance --play # Performance analysis with testing
|
||||
/sc:build --uc --no-mcp # Fast build without extra features
|
||||
```
|
||||
|
||||
### Security-Focused
|
||||
```bash
|
||||
/sc:analyze --focus security --think --validate # Thorough security analysis
|
||||
/sc:scan --agent security-engineer --safe-mode # Conservative security scan
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
|
||||
### Before/After: Basic Analysis
|
||||
**Before** (basic):
|
||||
```bash
|
||||
/sc:analyze auth.js
|
||||
# → Simple file analysis
|
||||
```
|
||||
|
||||
**After** (with flags):
|
||||
```bash
|
||||
/sc:analyze auth.js --focus security --think --c7
|
||||
# → Security-focused analysis with deep thinking and official docs
|
||||
# → Much more thorough, finds security patterns, checks against best practices
|
||||
```
|
||||
|
||||
### Before/After: Large Project
|
||||
**Before** (slow):
|
||||
```bash
|
||||
/sc:analyze huge-monorepo/
|
||||
# → Tries to analyze everything at once, may timeout or use too many tokens
|
||||
```
|
||||
|
||||
**After** (efficient):
|
||||
```bash
|
||||
/sc:analyze huge-monorepo/ --delegate auto --uc --focus architecture
|
||||
# → Delegates work to sub-agents, compresses output, focuses on architecture
|
||||
# → Faster, more focused, better results
|
||||
```
|
||||
|
||||
### Before/After: Improvement Work
|
||||
**Before** (risky):
|
||||
```bash
|
||||
/sc:improve legacy-system/
|
||||
# → May make too many changes, could break things
|
||||
```
|
||||
|
||||
**After** (safe):
|
||||
```bash
|
||||
/sc:improve legacy-system/ --safe-mode --loop --validate
|
||||
# → Safe changes only, iterative approach, validates first, systematic improvement
|
||||
# → Much safer, progressive improvement
|
||||
```
|
||||
|
||||
## Auto-Activation Examples 🤖
|
||||
|
||||
SuperClaude usually adds flags based on context. Here's when it tries:
|
||||
|
||||
### Complexity-Based
|
||||
```bash
|
||||
/sc:analyze huge-codebase/
|
||||
# Auto-adds: --delegate auto --uc
|
||||
# Why: >50 files detected, context management needed
|
||||
|
||||
/sc:troubleshoot "complex system issue"
|
||||
# Auto-adds: --think --seq
|
||||
# Why: Multi-component problem detected
|
||||
```
|
||||
|
||||
### Domain-Based
|
||||
```bash
|
||||
/sc:build react-app/
|
||||
# Auto-activates: frontend-architect agent + --c7
|
||||
# Why: Frontend framework detected
|
||||
|
||||
/sc:analyze --focus security
|
||||
# Auto-activates: security-engineer agent + --validate
|
||||
# Why: Security focus triggers security specialist
|
||||
```
|
||||
|
||||
### Performance-Based
|
||||
```bash
|
||||
# When context usage >75%
|
||||
/sc:analyze large-project/
|
||||
# Auto-adds: --uc
|
||||
# Why: Token optimization needed
|
||||
|
||||
# When risk score >0.7
|
||||
/sc:improve production-code/
|
||||
# Auto-adds: --safe-mode --validate
|
||||
# Why: High-risk operation detected
|
||||
```
|
||||
|
||||
## Advanced Usage 🚀
|
||||
|
||||
### Complex Flag Combinations
|
||||
|
||||
**Comprehensive Code Review**:
|
||||
```bash
|
||||
/sc:review codebase/ --agent quality-engineer --think-hard --focus quality --validate --c7
|
||||
# → Quality engineer agent + deep thinking + quality focus + validation + docs
|
||||
```
|
||||
|
||||
**Legacy System Modernization**:
|
||||
```bash
|
||||
/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-engineer --ultrathink --focus security --validate --seq
|
||||
# → Security engineer agent + maximum thinking + security focus + validation + systematic analysis
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
**For Speed**:
|
||||
```bash
|
||||
/sc:analyze --no-mcp --uc --scope file
|
||||
# → Disable extra features, compress output, limit scope
|
||||
```
|
||||
|
||||
**For Thoroughness**:
|
||||
```bash
|
||||
/sc:analyze --all-mcp --think-hard --delegate auto
|
||||
# → All capabilities, deep thinking, parallel processing
|
||||
```
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
**Bug Investigation Workflow**:
|
||||
```bash
|
||||
/sc:troubleshoot "specific error" --seq --think --validate
|
||||
/sc:analyze affected-files/ --focus quality --agent root-cause-analyst
|
||||
/sc:test --play --coverage
|
||||
```
|
||||
|
||||
**Feature Development Workflow**:
|
||||
```bash
|
||||
/sc:design new-feature --agent system-architect --c7
|
||||
/sc:build --magic --agent frontend-architect --validate
|
||||
/sc:test --play --coverage
|
||||
/sc:document --agent technical-writer --c7
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Most Useful Flags
|
||||
| Flag | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| `--think` | Deeper analysis | Complex problems |
|
||||
| `--uc` | Compress output | Large operations |
|
||||
| `--safe-mode` | Conservative execution | Important code |
|
||||
| `--c7` | Official docs | Framework work |
|
||||
| `--seq` | Systematic analysis | Debugging |
|
||||
| `--focus security` | Security focus | Security concerns |
|
||||
| `--delegate auto` | Parallel processing | Large codebases |
|
||||
| `--validate` | Check before action | Risky operations |
|
||||
| `--brainstorm` | Requirements discovery | Ambiguous projects |
|
||||
| `--serena` | Semantic analysis | Symbol operations |
|
||||
|
||||
### Flag Combinations That Work Well
|
||||
```bash
|
||||
# Safe improvement
|
||||
--safe-mode --validate
|
||||
|
||||
# Deep analysis
|
||||
--think --seq --c7
|
||||
|
||||
# Large project
|
||||
--delegate auto --uc --focus
|
||||
|
||||
# Learning
|
||||
--verbose --c7 --agent learning-guide
|
||||
|
||||
# Security work
|
||||
--agent security-engineer --focus security --validate
|
||||
|
||||
# Performance work
|
||||
--agent performance-engineer --focus performance --play
|
||||
|
||||
# Requirements discovery
|
||||
--brainstorm --max-rounds 10 --prd
|
||||
```
|
||||
|
||||
### Auto-Activation Triggers
|
||||
- **--think**: Complex imports, cross-module calls
|
||||
- **--uc**: Context >75%, large operations
|
||||
- **--safe-mode**: Resource usage >85%, production
|
||||
- **--delegate**: >7 directories or >50 files
|
||||
- **--c7**: Framework imports, documentation requests
|
||||
- **--seq**: Debugging keywords, --think flags
|
||||
- **--serena**: Symbol operations, memory commands
|
||||
- **--brainstorm**: Exploration keywords, ambiguous requests
|
||||
- **Expert Agents**: Domain-specific keywords and patterns
|
||||
|
||||
## Troubleshooting Flag Issues 🚨
|
||||
|
||||
### Common Problems
|
||||
|
||||
**"Flags don't seem to work"**
|
||||
- Check spelling (common typos: `--ultracompresed`, `--agent frontend-architect`)
|
||||
- Some flags need values: `--scope project`, `--focus security`
|
||||
- Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, `--serena`, etc.
|
||||
|
||||
**"Operation too slow"**
|
||||
- Try `--uc` for compression
|
||||
- Use `--no-mcp` to disable extra features
|
||||
- Limit scope: `--scope file` instead of `--scope project`
|
||||
|
||||
**"Too much output"**
|
||||
- Add `--uc` for compression
|
||||
- Remove `--verbose` if present
|
||||
- Use `--answer-only` for simple questions
|
||||
|
||||
**"Not thorough enough"**
|
||||
- Add `--think` or `--think-hard`
|
||||
- Enable relevant MCP servers: `--seq`, `--c7`
|
||||
- Use appropriate agent: `--agent root-cause-analyst`
|
||||
|
||||
**"Changes too risky"**
|
||||
- Always use `--safe-mode` for important code
|
||||
- Add `--validate` to check first
|
||||
- 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-architect --agent backend-architect` → backend-architect
|
||||
|
||||
**Precedence order**:
|
||||
1. Safety flags (`--safe-mode`) beat optimization
|
||||
2. Explicit flags beat auto-activation
|
||||
3. Thinking depth: `--ultrathink` > `--think-hard` > `--think`
|
||||
4. Scope: system > project > module > file
|
||||
|
||||
## Tips for Effective Flag Usage 💡
|
||||
|
||||
### Starting Out (The Honest Truth)
|
||||
1. **Just ignore flags at first** - Auto-activation handles most cases pretty well
|
||||
2. **Watch what gets auto-activated** - You'll learn by seeing what SuperClaude picks
|
||||
3. **Use `--help` when curious** - Many commands show what flags are available
|
||||
4. **Trust the automation** - SuperClaude usually picks reasonable defaults
|
||||
|
||||
### Getting Advanced (If You Want To)
|
||||
1. **Experiment with overrides** - Try `--agent security-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
|
||||
|
||||
### 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`
|
||||
- **For learning**: `--verbose --c7 --agent learning-guide`
|
||||
- **For project discovery**: `--brainstorm --max-rounds 15 --prd`
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**The real truth about flags** 💯:
|
||||
- **Auto-activation usually works pretty well** compared to manual flag selection
|
||||
- **You can ignore most of this guide** and just use basic commands
|
||||
- **Flags are here when you want them** - not because you need them
|
||||
- **Learning happens naturally** through use, not through studying guides 😊
|
||||
|
||||
**Don't feel overwhelmed** 🧘♂️:
|
||||
- SuperClaude tries to work well without flag knowledge
|
||||
- The detailed info above is for curiosity, not necessity
|
||||
- Auto-activation keeps getting smarter based on usage patterns
|
||||
- You're not missing out by not memorizing flags
|
||||
|
||||
**When you actually need flags**:
|
||||
- Overriding auto-activation (rare)
|
||||
- Experimenting with different approaches (fun)
|
||||
- Optimizing for specific performance needs (advanced)
|
||||
- Learning about what happened (educational)
|
||||
|
||||
**Start simple, stay simple** 🎯:
|
||||
- Use basic commands: `/analyze`, `/build`, `/improve`
|
||||
- Let auto-activation handle the complexity
|
||||
- Add manual flags only when you want to experiment
|
||||
- Trust that SuperClaude knows what it's doing
|
||||
|
||||
---
|
||||
|
||||
*Remember: Behind all this apparent complexity, SuperClaude is actually simple to use. Just start typing commands! 🚀*
|
||||
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!*
|
||||
3247
Guides/superclaude-user-guide.md
Normal file
3247
Guides/superclaude-user-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user