External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434)

Browse Source 
* refactor(docs): rename directories to lowercase for PEP8 compliance

- Developer-Guide → developer-guide
- Getting-Started → getting-started
- Reference → reference
- Templates → templates
- User-Guide → user-guide
- User-Guide-jp → user-guide-jp
- User-Guide-kr → user-guide-kr
- User-Guide-zh → user-guide-zh

This change aligns with Python PEP8 package naming conventions.
All 43 files affected.

* refactor: rename root documentation files to lowercase

- CHANGELOG.md → changelog.md
- CODE_OF_CONDUCT.md → code_of_conduct.md
- CONTRIBUTING.md → contributing.md
- SECURITY.md → security.md

Aligns with Python package naming conventions (PEP8).
README files remain uppercase as per convention.

* refactor: move documentation files to docs/ for cleaner root

Moved OSS standard files to docs/:
- CHANGELOG.md → docs/CHANGELOG.md
- CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md
- CONTRIBUTING.md → docs/CONTRIBUTING.md
- SECURITY.md → docs/SECURITY.md

Root now contains only essential files:
✓ README files (表紙: en, ja, kr, zh)
✓ LICENSE (法的要件)
✓ Build configs (pyproject.toml, setup.py, MANIFEST.in)
✓ VERSION

Rationale:
Cleaner root structure following modern Python project conventions.
All detailed documentation consolidated in docs/ directory.

* refactor: update documentation links after restructure

Auto-updated internal documentation links to reflect new structure:
- docs/ subdirectories now lowercase (PEP8)
- Root files moved to docs/
- All cross-references updated

This commit includes linter-generated link updates.

* chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY)

* chore(docs): remove duplicated PR docs from repo root (moved under docs)

* docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity

* docs: update links to PM_AGENT.md after rename

---------

Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>
This commit is contained in:
kazuki nakai
2025-10-16 00:37:39 +09:00
committed by GitHub
parent 7c14a31bc3
commit d5dfd7da21
60 changed files with 836 additions and 886 deletions
Download Patch File Download Diff File Expand all files Collapse all files

936
docs/user-guide/agents.md Normal file
View File

@@ -0,0 +1,936 @@
# SuperClaude Agents Guide 🤖
SuperClaude provides 16 domain specialist agents that Claude Code can invoke for specialized expertise.
## 🧪 Testing Agent Activation
Before using this guide, verify agent selection works:
```bash
# Test manual agent invocation
@agent-python-expert "explain decorators"
# Example behavior: Python expert responds with detailed explanation
# Test security agent auto-activation
/sc:implement "JWT authentication"
# Example behavior: Security engineer should activate automatically
# Test frontend agent auto-activation
/sc:implement "responsive navigation component"
# Example behavior: Frontend architect + Magic MCP should activate
# Test systematic analysis
/sc:troubleshoot "slow API performance"
# Example behavior: Root-cause analyst + performance engineer activation
# Test combining manual and auto
/sc:analyze src/
@agent-refactoring-expert "suggest improvements"
# Example behavior: Analysis followed by refactoring suggestions
```
**If tests fail**: Check agent files exist in `~/.claude/agents/` or restart Claude Code session
## Core Concepts
### What are SuperClaude Agents?
**Agents** are specialized AI domain experts implemented as context instructions that modify Claude Code's behavior. Each agent is a carefully crafted `.md` file in the `superclaude/Agents/` directory containing domain-specific expertise, behavioral patterns, and problem-solving approaches.
**Important**: Agents are NOT separate AI models or software - they are context configurations that Claude Code reads to adopt specialized behaviors.
### Two Ways to Use Agents
#### 1. Manual Invocation with @agent- Prefix
```bash
# Directly invoke a specific agent
@agent-security "review authentication implementation"
@agent-frontend "design responsive navigation"
@agent-architect "plan microservices migration"
```
#### 2. Auto-Activation (Behavioral Routing)
"Auto-activation" means Claude Code reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests. SuperClaude provides behavioral guidelines that Claude follows to route to the most appropriate specialists.
> **📝 How Agent "Auto-Activation" Works**:
> Agent activation isn't automatic system logic - it's behavioral instructions in context files.
> When documentation says agents "auto-activate", it means Claude Code reads instructions to engage
> specific domain expertise based on keywords and patterns in your request. This creates the
> experience of intelligent routing while being transparent about the underlying mechanism.
```bash
# These commands auto-activate relevant agents
/sc:implement "JWT authentication" # → security-engineer auto-activates
/sc:design "React dashboard" # → frontend-architect auto-activates
/sc:troubleshoot "memory leak" # → performance-engineer auto-activates
```
**MCP Servers** provide enhanced capabilities through specialized tools like Context7 (documentation), Sequential (analysis), Magic (UI), Playwright (testing), and Morphllm (code transformation).
**Domain Specialists** focus on narrow expertise areas to provide deeper, more accurate solutions than generalist approaches.
### Agent Selection Rules
**Priority Hierarchy:**
1. **Manual Override** - @agent-[name] takes precedence over auto-activation
2. **Keywords** - Direct domain terminology triggers primary agents
3. **File Types** - Extensions activate language/framework specialists
4. **Complexity** - Multi-step tasks engage coordination agents
5. **Context** - Related concepts trigger complementary agents
**Conflict Resolution:**
- Manual invocation → Specified agent takes priority
- Multiple matches → Multi-agent coordination
- Unclear context → Requirements analyst activation
- High complexity → System architect oversight
- Quality concerns → Automatic QA agent inclusion
**Selection Decision Tree:**
```
Task Analysis →
├─ Manual @agent-? → Use specified agent
├─ Single Domain? → Activate primary agent
├─ Multi-Domain? → Coordinate specialist agents
├─ Complex System? → Add system-architect oversight
├─ Quality Critical? → Include security + performance + quality agents
└─ Learning Focus? → Add learning-guide + technical-writer
```
## Quick Start Examples
### Manual Agent Invocation
```bash
# Explicitly call specific agents with @agent- prefix
@agent-python-expert "optimize this data processing pipeline"
@agent-quality-engineer "create comprehensive test suite"
@agent-technical-writer "document this API with examples"
@agent-socratic-mentor "explain this design pattern"
```
### Automatic Agent Coordination
```bash
# Commands that trigger auto-activation
/sc:implement "JWT authentication with rate limiting"
# → Triggers: security-engineer + backend-architect + quality-engineer
/sc:design "accessible React dashboard with documentation"
# → Triggers: frontend-architect + learning-guide + technical-writer
/sc:troubleshoot "slow deployment pipeline with intermittent failures"
# → Triggers: devops-architect + performance-engineer + root-cause-analyst
/sc:audit "payment processing security vulnerabilities"
# → Triggers: security-engineer + quality-engineer + refactoring-expert
```
### Combining Manual and Auto Approaches
```bash
# Start with command (auto-activation)
/sc:implement "user profile system"
# Then explicitly add specialist review
@agent-security "review the profile system for OWASP compliance"
@agent-performance-engineer "optimize database queries"
```
---
## The SuperClaude Agent Team 👥
### Meta-Layer Agent 🎯
### pm-agent 📚
**Expertise**: Self-improvement workflow executor that documents implementations, analyzes mistakes, and maintains knowledge base continuously
**Auto-Activation**:
- **Post-Implementation**: After any task completion requiring documentation
- **Mistake Detection**: Immediate analysis when errors or bugs occur
- **Monthly Maintenance**: Regular documentation health reviews
- **Knowledge Gap**: When patterns emerge requiring documentation
- Commands: Automatically activates after `/sc:implement`, `/sc:build`, `/sc:improve` completions
**Capabilities**:
- **Implementation Documentation**: Record new patterns, architectural decisions, edge cases discovered
- **Mistake Analysis**: Root cause analysis, prevention checklists, pattern identification
- **Pattern Recognition**: Extract success patterns, anti-patterns, best practices
- **Knowledge Maintenance**: Monthly reviews, noise reduction, duplication merging, freshness updates
- **Self-Improvement Loop**: Transform every experience into reusable knowledge
**How PM Agent Works** (Meta-Layer):
1. **Specialist Agents Complete Task**: Backend-architect implements feature
2. **PM Agent Auto-Activates**: After implementation completion
3. **Documentation**: Records patterns, decisions, edge cases in docs/
4. **Knowledge Update**: Updates CLAUDE.md if global pattern discovered
5. **Evidence Collection**: Links test results, screenshots, metrics
6. **Learning Integration**: Extracts lessons for future implementations
**Self-Improvement Workflow Examples**:
1. **Post-Implementation Documentation**:
- Scenario: Backend architect just implemented JWT authentication
- PM Agent: Analyzes implementation → Documents JWT pattern → Updates docs/authentication.md → Records security decisions → Creates evidence links
- Output: Comprehensive authentication pattern documentation for future reuse
2. **Immediate Mistake Analysis**:
- Scenario: Direct Supabase import used (Kong Gateway bypassed)
- PM Agent: Stops implementation → Root cause analysis → Documents in self-improvement-workflow.md → Creates prevention checklist → Updates CLAUDE.md
- Output: Mistake recorded with prevention strategy, won't repeat error
3. **Monthly Documentation Maintenance**:
- Scenario: Monthly review on 1st of month
- PM Agent: Reviews docs older than 6 months → Deletes unused documents → Merges duplicates → Updates version numbers → Reduces verbosity
- Output: Fresh, minimal, high-signal documentation maintained
**Integration with Task Execution**:
PM Agent operates as a **meta-layer** above specialist agents:
```
Task Flow:
1. User Request → Auto-activation selects specialist agent
2. Specialist Agent → Executes implementation (backend-architect, frontend-architect, etc.)
3. PM Agent (Auto-triggered) → Documents learnings
4. Knowledge Base → Updated with patterns, mistakes, improvements
```
**Works Best With**: All agents (documents their work, not replaces them)
**Quality Standards**:
- **Latest**: Last Verified dates on all documents
- **Minimal**: Necessary information only, no verbosity
- **Clear**: Concrete examples and copy-paste ready code
- **Practical**: Immediately applicable to real work
**Self-Improvement Loop Phases**:
- **AFTER Phase**: Primary responsibility - document implementations, update docs/, create evidence
- **MISTAKE RECOVERY**: Immediate stop, root cause analysis, documentation update
- **MAINTENANCE**: Monthly pruning, merging, freshness updates, noise reduction
**Verify**: Activates automatically after task completions requiring documentation
**Test**: Should document patterns after backend-architect implements features
**Check**: Should create prevention checklists when mistakes detected
---
### Architecture & System Design Agents 🏗️
### system-architect 🏢
**Expertise**: Large-scale distributed system design with focus on scalability and service architecture
**Auto-Activation**:
- Keywords: "architecture", "microservices", "scalability", "system design", "distributed"
- Context: Multi-service systems, architectural decisions, technology selection
- Complexity: >5 components or cross-domain integration requirements
**Capabilities**:
- Service boundary definition and microservices decomposition
- Technology stack selection and integration strategy
- Scalability planning and performance architecture
- Event-driven architecture and messaging patterns
- Data flow design and system integration
**Examples**:
1. **E-commerce Platform**: Design microservices for user, product, payment, and notification services with event sourcing
2. **Real-time Analytics**: Architecture for high-throughput data ingestion with stream processing and time-series storage
3. **Multi-tenant SaaS**: System design with tenant isolation, shared infrastructure, and horizontal scaling strategies
### Success Criteria
- [ ] System-level thinking evident in responses
- [ ] Mentions service boundaries and integration patterns
- [ ] Includes scalability and reliability considerations
- [ ] Provides technology stack recommendations
**Verify:** `/sc:design "microservices platform"` should activate system-architect
**Test:** Output should include service decomposition and integration patterns
**Check:** Should coordinate with devops-architect for infrastructure concerns
**Works Best With**: devops-architect (infrastructure), performance-engineer (optimization), security-engineer (compliance)
---
### backend-architect ⚙️
**Expertise**: Robust server-side system design with emphasis on API reliability and data integrity
**Auto-Activation**:
- Keywords: "API", "backend", "server", "database", "REST", "GraphQL", "endpoint"
- File Types: API specs, server configs, database schemas
- Context: Server-side logic, data persistence, API development
**Capabilities**:
- RESTful and GraphQL API architecture and design patterns
- Database schema design and query optimization strategies
- Authentication, authorization, and security implementation
- Error handling, logging, and monitoring integration
- Caching strategies and performance optimization
**Examples**:
1. **User Management API**: JWT authentication with role-based access control and rate limiting
2. **Payment Processing**: PCI-compliant transaction handling with idempotency and audit trails
3. **Content Management**: RESTful APIs with caching, pagination, and real-time notifications
**Works Best With**: security-engineer (auth/security), performance-engineer (optimization), quality-engineer (testing)
---
### frontend-architect 🎨
**Expertise**: Modern web application architecture with focus on accessibility and user experience
**Auto-Activation**:
- Keywords: "UI", "frontend", "React", "Vue", "Angular", "component", "accessibility", "responsive"
- File Types: .jsx, .vue, .ts (frontend), .css, .scss
- Context: User interface development, component design, client-side architecture
**Capabilities**:
- Component architecture and design system implementation
- State management patterns (Redux, Zustand, Pinia)
- Accessibility compliance (WCAG 2.1) and inclusive design
- Performance optimization and bundle analysis
- Progressive Web App and mobile-first development
**Examples**:
1. **Dashboard Interface**: Accessible data visualization with real-time updates and responsive grid layout
2. **Form Systems**: Complex multi-step forms with validation, error handling, and accessibility features
3. **Design System**: Reusable component library with consistent styling and interaction patterns
**Works Best With**: learning-guide (user guidance), performance-engineer (optimization), quality-engineer (testing)
---
### devops-architect 🚀
**Expertise**: Infrastructure automation and deployment pipeline design for reliable software delivery
**Auto-Activation**:
- Keywords: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring", "pipeline"
- File Types: Dockerfile, docker-compose.yml, k8s manifests, CI configs
- Context: Deployment processes, infrastructure management, automation
**Capabilities**:
- CI/CD pipeline design with automated testing and deployment
- Container orchestration and Kubernetes cluster management
- Infrastructure as Code with Terraform and cloud platforms
- Monitoring, logging, and observability stack implementation
- Security scanning and compliance automation
**Examples**:
1. **Microservices Deployment**: Kubernetes deployment with service mesh, auto-scaling, and blue-green releases
2. **Multi-Environment Pipeline**: GitOps workflow with automated testing, security scanning, and staged deployments
3. **Monitoring Stack**: Comprehensive observability with metrics, logs, traces, and alerting systems
**Works Best With**: system-architect (infrastructure planning), security-engineer (compliance), performance-engineer (monitoring)
---
### deep-research-agent 🔬
**Expertise**: Comprehensive research with adaptive strategies and multi-hop reasoning
**Auto-Activation**:
- Keywords: "research", "investigate", "discover", "explore", "find out", "search for", "latest", "current"
- Commands: `/sc:research` automatically activates this agent
- Context: Complex queries requiring thorough research, current information needs, fact-checking
- Complexity: Questions spanning multiple domains or requiring iterative exploration
**Capabilities**:
- **Adaptive Planning Strategies**: Planning (direct), Intent (clarify first), Unified (collaborative)
- **Multi-Hop Reasoning**: Up to 5 levels - entity expansion, temporal progression, conceptual deepening, causal chains
- **Self-Reflective Mechanisms**: Progress assessment after each major step with replanning triggers
- **Evidence Management**: Clear citations, relevance scoring, uncertainty acknowledgment
- **Tool Orchestration**: Parallel-first execution with Tavily (search), Playwright (JavaScript content), Sequential (reasoning)
- **Learning Integration**: Pattern recognition and strategy reuse via Serena memory
**Research Depth Levels**:
- **Quick**: Basic search, 1 hop, summary output
- **Standard**: Extended search, 2-3 hops, structured report (default)
- **Deep**: Comprehensive search, 3-4 hops, detailed analysis
- **Exhaustive**: Maximum depth, 5 hops, complete investigation
**Examples**:
1. **Technical Research**: `/sc:research "latest React Server Components patterns"` → Comprehensive technical research with implementation examples
2. **Market Analysis**: `/sc:research "AI coding assistants landscape 2024" --strategy unified` → Collaborative analysis with user input
3. **Academic Investigation**: `/sc:research "quantum computing breakthroughs" --depth exhaustive` → Comprehensive literature review with evidence chains
**Workflow Pattern** (6-Phase):
1. **Understand** (5-10%): Assess query complexity
2. **Plan** (10-15%): Select strategy and identify parallel opportunities
3. **TodoWrite** (5%): Create adaptive task hierarchy (3-15 tasks)
4. **Execute** (50-60%): Parallel searches and extractions
5. **Track** (Continuous): Monitor progress and confidence
6. **Validate** (10-15%): Verify evidence chains
**Output**: Reports saved to `claudedocs/research_[topic]_[timestamp].md`
**Works Best With**: system-architect (technical research), learning-guide (educational research), requirements-analyst (market research)
### Quality & Analysis Agents 🔍
### security-engineer 🔒
**Expertise**: Application security architecture with focus on threat modeling and vulnerability prevention
**Auto-Activation**:
- Keywords: "security", "auth", "authentication", "vulnerability", "encryption", "compliance", "OWASP"
- Context: Security reviews, authentication flows, data protection requirements
- Risk Indicators: Payment processing, user data, API access, regulatory compliance needs
**Capabilities**:
- Threat modeling and attack surface analysis
- Secure authentication and authorization design (OAuth, JWT, SAML)
- Data encryption strategies and key management
- Vulnerability assessment and penetration testing guidance
- Security compliance (GDPR, HIPAA, PCI-DSS) implementation
**Examples**:
1. **OAuth Implementation**: Secure multi-tenant authentication with token refresh and role-based access
2. **API Security**: Rate limiting, input validation, SQL injection prevention, and security headers
3. **Data Protection**: Encryption at rest/transit, key rotation, and privacy-by-design architecture
**Works Best With**: backend-architect (API security), quality-engineer (security testing), root-cause-analyst (incident response)
---
### performance-engineer ⚡
**Expertise**: System performance optimization with focus on scalability and resource efficiency
**Auto-Activation**:
- Keywords: "performance", "slow", "optimization", "bottleneck", "latency", "memory", "CPU"
- Context: Performance issues, scalability concerns, resource constraints
- Metrics: Response times >500ms, high memory usage, poor throughput
**Capabilities**:
- Performance profiling and bottleneck identification
- Database query optimization and indexing strategies
- Caching implementation (Redis, CDN, application-level)
- Load testing and capacity planning
- Memory management and resource optimization
**Examples**:
1. **API Optimization**: Reduce response time from 2s to 200ms through caching and query optimization
2. **Database Scaling**: Implement read replicas, connection pooling, and query result caching
3. **Frontend Performance**: Bundle optimization, lazy loading, and CDN implementation for <3s load times
**Works Best With**: system-architect (scalability), devops-architect (infrastructure), root-cause-analyst (debugging)
---
### root-cause-analyst 🔍
**Expertise**: Systematic problem investigation using evidence-based analysis and hypothesis testing
**Auto-Activation**:
- Keywords: "bug", "issue", "problem", "debugging", "investigation", "troubleshoot", "error"
- Context: System failures, unexpected behavior, complex multi-component issues
- Complexity: Cross-system problems requiring methodical investigation
**Capabilities**:
- Systematic debugging methodology and root cause analysis
- Error correlation and dependency mapping across systems
- Log analysis and pattern recognition for failure investigation
- Hypothesis formation and testing for complex problems
- Incident response and post-mortem analysis procedures
**Examples**:
1. **Database Connection Failures**: Trace intermittent failures across connection pools, network timeouts, and resource limits
2. **Payment Processing Errors**: Investigate transaction failures through API logs, database states, and external service responses
3. **Performance Degradation**: Analyze gradual slowdown through metrics correlation, resource usage, and code changes
**Works Best With**: performance-engineer (performance issues), security-engineer (security incidents), quality-engineer (testing failures)
---
### quality-engineer ✅
**Expertise**: Comprehensive testing strategy and quality assurance with focus on automation and coverage
**Auto-Activation**:
- Keywords: "test", "testing", "quality", "QA", "validation", "coverage", "automation"
- Context: Test planning, quality gates, validation requirements
- Quality Concerns: Code coverage <80%, missing test automation, quality issues
**Capabilities**:
- Test strategy design (unit, integration, e2e, performance testing)
- Test automation framework implementation and CI/CD integration
- Quality metrics definition and monitoring (coverage, defect rates)
- Edge case identification and boundary testing scenarios
- Accessibility testing and compliance validation
**Examples**:
1. **E-commerce Testing**: Comprehensive test suite covering user flows, payment processing, and inventory management
2. **API Testing**: Automated contract testing, load testing, and security testing for REST/GraphQL APIs
3. **Accessibility Validation**: WCAG 2.1 compliance testing with automated and manual accessibility audits
**Works Best With**: security-engineer (security testing), performance-engineer (load testing), frontend-architect (UI testing)
---
### refactoring-expert 🔧
**Expertise**: Code quality improvement through systematic refactoring and technical debt management
**Auto-Activation**:
- Keywords: "refactor", "clean code", "technical debt", "SOLID", "maintainability", "code smell"
- Context: Legacy code improvements, architecture updates, code quality issues
- Quality Indicators: High complexity, duplicated code, poor test coverage
**Capabilities**:
- SOLID principles application and design pattern implementation
- Code smell identification and systematic elimination
- Legacy code modernization strategies and migration planning
- Technical debt assessment and prioritization frameworks
- Code structure improvement and architecture refactoring
**Examples**:
1. **Legacy Modernization**: Transform monolithic application to modular architecture with improved testability
2. **Design Patterns**: Implement Strategy pattern for payment processing to reduce coupling and improve extensibility
3. **Code Cleanup**: Remove duplicated code, improve naming conventions, and extract reusable components
**Works Best With**: system-architect (architecture improvements), quality-engineer (testing strategy), python-expert (language-specific patterns)
### Specialized Development Agents 🎯
### python-expert 🐍
**Expertise**: Production-ready Python development with emphasis on modern frameworks and performance
**Auto-Activation**:
- Keywords: "Python", "Django", "FastAPI", "Flask", "asyncio", "pandas", "pytest"
- File Types: .py, requirements.txt, pyproject.toml, Pipfile
- Context: Python development tasks, API development, data processing, testing
**Capabilities**:
- Modern Python architecture patterns and framework selection
- Asynchronous programming with asyncio and concurrent futures
- Performance optimization through profiling and algorithmic improvements
- Testing strategies with pytest, fixtures, and test automation
- Package management and deployment with pip, poetry, and Docker
**Examples**:
1. **FastAPI Microservice**: High-performance async API with Pydantic validation, dependency injection, and OpenAPI docs
2. **Data Pipeline**: Pandas-based ETL with error handling, logging, and parallel processing for large datasets
3. **Django Application**: Full-stack web app with custom user models, API endpoints, and comprehensive test coverage
**Works Best With**: backend-architect (API design), quality-engineer (testing), performance-engineer (optimization)
---
### requirements-analyst 📝
**Expertise**: Requirements discovery and specification development through systematic stakeholder analysis
**Auto-Activation**:
- Keywords: "requirements", "specification", "PRD", "user story", "functional", "scope", "stakeholder"
- Context: Project initiation, unclear requirements, scope definition needs
- Complexity: Multi-stakeholder projects, unclear objectives, conflicting requirements
**Capabilities**:
- Requirements elicitation through stakeholder interviews and workshops
- User story writing with acceptance criteria and definition of done
- Functional and non-functional specification documentation
- Stakeholder analysis and requirement prioritization frameworks
- Scope management and change control processes
**Examples**:
1. **Product Requirements Document**: Comprehensive PRD for fintech mobile app with user personas, feature specifications, and success metrics
2. **API Specification**: Detailed requirements for payment processing API with error handling, security, and performance criteria
3. **Migration Requirements**: Legacy system modernization requirements with data migration, user training, and rollback procedures
**Works Best With**: system-architect (technical feasibility), technical-writer (documentation), learning-guide (user guidance)
### Communication & Learning Agents 📚
### technical-writer 📚
**Expertise**: Technical documentation and communication with focus on audience analysis and clarity
**Auto-Activation**:
- Keywords: "documentation", "readme", "API docs", "user guide", "technical writing", "manual"
- Context: Documentation requests, API documentation, user guides, technical explanations
- File Types: .md, .rst, API specs, documentation files
**Capabilities**:
- Technical documentation architecture and information design
- Audience analysis and content targeting for different skill levels
- API documentation with working examples and integration guidance
- User guide creation with step-by-step procedures and troubleshooting
- Accessibility standards application and inclusive language usage
**Examples**:
1. **API Documentation**: Comprehensive REST API docs with authentication, endpoints, examples, and SDK integration guides
2. **User Manual**: Step-by-step installation and configuration guide with screenshots, troubleshooting, and FAQ sections
3. **Technical Specification**: System architecture documentation with diagrams, data flows, and implementation details
**Works Best With**: requirements-analyst (specification clarity), learning-guide (educational content), frontend-architect (UI documentation)
---
### learning-guide 🎓
**Expertise**: Educational content design and progressive learning with focus on skill development and mentorship
**Auto-Activation**:
- Keywords: "explain", "learn", "tutorial", "beginner", "teaching", "education", "training"
- Context: Educational requests, concept explanations, skill development, learning paths
- Complexity: Complex topics requiring step-by-step breakdown and progressive understanding
**Capabilities**:
- Learning path design with progressive skill development
- Complex concept explanation through analogies and examples
- Interactive tutorial creation with hands-on exercises
- Skill assessment and competency evaluation frameworks
- Mentorship strategies and personalized learning approaches
**Examples**:
1. **Programming Tutorial**: Interactive React tutorial with hands-on exercises, code examples, and progressive complexity
2. **Concept Explanation**: Database normalization explained through real-world examples with visual diagrams and practice exercises
3. **Skill Assessment**: Comprehensive evaluation framework for full-stack development with practical projects and feedback
**Works Best With**: technical-writer (educational documentation), frontend-architect (interactive learning), requirements-analyst (learning objectives)
---
## Agent Coordination & Integration 🤝
### Coordination Patterns
**Architecture Teams**:
- **Full-Stack Development**: frontend-architect + backend-architect + security-engineer + quality-engineer
- **System Design**: system-architect + devops-architect + performance-engineer + security-engineer
- **Legacy Modernization**: refactoring-expert + system-architect + quality-engineer + technical-writer
**Quality Teams**:
- **Security Audit**: security-engineer + quality-engineer + root-cause-analyst + requirements-analyst
- **Performance Optimization**: performance-engineer + system-architect + devops-architect + root-cause-analyst
- **Testing Strategy**: quality-engineer + security-engineer + performance-engineer + frontend-architect
**Communication Teams**:
- **Documentation Project**: technical-writer + requirements-analyst + learning-guide + domain experts
- **Learning Platform**: learning-guide + frontend-architect + technical-writer + quality-engineer
- **API Documentation**: backend-architect + technical-writer + security-engineer + quality-engineer
### MCP Server Integration
**Enhanced Capabilities through MCP Servers**:
- **Context7**: Official documentation patterns for all architects and specialists
- **Sequential**: Multi-step analysis for root-cause-analyst, system-architect, performance-engineer
- **Magic**: UI generation for frontend-architect, learning-guide interactive content
- **Playwright**: Browser testing for quality-engineer, accessibility validation for frontend-architect
- **Morphllm**: Code transformation for refactoring-expert, bulk changes for python-expert
- **Serena**: Project memory for all agents, context preservation across sessions
### Troubleshooting Agent Activation
## Troubleshooting
For troubleshooting help, see:
- [Common Issues](../reference/common-issues.md) - Quick fixes for frequent problems
- [Troubleshooting Guide](../reference/troubleshooting.md) - Comprehensive problem resolution
### Common Issues
- **No agent activation**: Use domain keywords: "security", "performance", "frontend"
- **Wrong agents selected**: Check trigger keywords in agent documentation
- **Too many agents**: Focus keywords on primary domain or use `/sc:focus [domain]`
- **Agents not coordinating**: Increase task complexity or use multi-domain keywords
- **Agent expertise mismatch**: Use more specific technical terminology
### Immediate Fixes
- **Force agent activation**: Use explicit domain keywords in requests
- **Reset agent selection**: Restart Claude Code session to reset agent state
- **Check agent patterns**: Review trigger keywords in agent documentation
- **Test basic activation**: Try `/sc:implement "security auth"` to test security-engineer
### Agent-Specific Troubleshooting
**No Security Agent:**
```bash
# Problem: Security concerns not triggering security-engineer
# Quick Fix: Use explicit security keywords
"implement authentication" # Generic - may not trigger
"implement JWT authentication security" # Explicit - triggers security-engineer
"secure user login with encryption" # Security focus - triggers security-engineer
```
**No Performance Agent:**
```bash
# Problem: Performance issues not triggering performance-engineer
# Quick Fix: Use performance-specific terminology
"make it faster" # Vague - may not trigger
"optimize slow database queries" # Specific - triggers performance-engineer
"reduce API latency and bottlenecks" # Performance focus - triggers performance-engineer
```
**No Architecture Agent:**
```bash
# Problem: System design not triggering architecture agents
# Quick Fix: Use architectural keywords
"build an app" # Generic - triggers basic agents
"design microservices architecture" # Specific - triggers system-architect
"scalable distributed system design" # Architecture focus - triggers system-architect
```
**Wrong Agent Combination:**
```bash
# Problem: Getting frontend agent for backend tasks
# Quick Fix: Use domain-specific terminology
"create user interface" # May trigger frontend-architect
"create REST API endpoints" # Specific - triggers backend-architect
"implement server-side authentication" # Backend focus - triggers backend-architect
```
### Support Levels
**Quick Fix:**
- Use explicit domain keywords from agent trigger table
- Try restarting Claude Code session
- Focus on single domain to avoid confusion
**Detailed Help:**
- See [Common Issues Guide](../reference/common-issues.md) for agent installation problems
- Review trigger keywords for target agents
**Expert Support:**
- Use `SuperClaude install --diagnose`
- See [Diagnostic Reference Guide](../reference/diagnostic-reference.md) for coordination analysis
**Community Support:**
- Report issues at [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
- Include examples of expected vs actual agent activation
### Success Validation
After applying agent fixes, test with:
- [ ] Domain-specific requests activate correct agents (security → security-engineer)
- [ ] Complex tasks trigger multi-agent coordination (3+ agents)
- [ ] Agent expertise matches task requirements (API → backend-architect)
- [ ] Quality agents auto-include when appropriate (security, performance, testing)
- [ ] Responses show domain expertise and specialized knowledge
## Quick Troubleshooting (Legacy)
- **No agent activation** → Use domain keywords: "security", "performance", "frontend"
- **Wrong agents** → Check trigger keywords in agent documentation
- **Too many agents** → Focus keywords on primary domain
- **Agents not coordinating** → Increase task complexity or use multi-domain keywords
**Agent Not Activating?**
1. **Check Keywords**: Use domain-specific terminology (e.g., "authentication" not "login" for security-engineer)
2. **Add Context**: Include file types, frameworks, or specific technologies
3. **Increase Complexity**: Multi-domain problems trigger more agents
4. **Use Examples**: Reference concrete scenarios that match agent expertise
**Too Many Agents?**
- Focus keywords on primary domain needs
- Use `/sc:focus [domain]` to limit scope
- Start with specific agents, expand as needed
**Wrong Agents?**
- Review trigger keywords in agent documentation
- Use more specific terminology for target domain
- Add explicit requirements or constraints
## Quick Reference 📋
### Agent Trigger Lookup
| Trigger Type | Keywords/Patterns | Activated Agents |
|-------------|-------------------|------------------|
| **Security** | "auth", "security", "vulnerability", "encryption" | security-engineer |
| **Performance** | "slow", "optimization", "bottleneck", "latency" | performance-engineer |
| **Frontend** | "UI", "React", "Vue", "component", "responsive" | frontend-architect |
| **Backend** | "API", "server", "database", "REST", "GraphQL" | backend-architect |
| **Testing** | "test", "QA", "validation", "coverage" | quality-engineer |
| **DevOps** | "deploy", "CI/CD", "Docker", "Kubernetes" | devops-architect |
| **Architecture** | "architecture", "microservices", "scalability" | system-architect |
| **Python** | ".py", "Django", "FastAPI", "asyncio" | python-expert |
| **Problems** | "bug", "issue", "debugging", "troubleshoot" | root-cause-analyst |
| **Code Quality** | "refactor", "clean code", "technical debt" | refactoring-expert |
| **Documentation** | "documentation", "readme", "API docs" | technical-writer |
| **Learning** | "explain", "tutorial", "beginner", "teaching" | learning-guide |
| **Requirements** | "requirements", "PRD", "specification" | requirements-analyst |
| **Research** | "research", "investigate", "latest", "current" | deep-research-agent |
### Command-Agent Mapping
| Command | Primary Agents | Supporting Agents |
|---------|----------------|-------------------|
| `/sc:implement` | Domain architects (frontend, backend) | security-engineer, quality-engineer |
| `/sc:analyze` | quality-engineer, security-engineer | performance-engineer, root-cause-analyst |
| `/sc:troubleshoot` | root-cause-analyst | Domain specialists, performance-engineer |
| `/sc:improve` | refactoring-expert | quality-engineer, performance-engineer |
| `/sc:document` | technical-writer | Domain specialists, learning-guide |
| `/sc:design` | system-architect | Domain architects, requirements-analyst |
| `/sc:test` | quality-engineer | security-engineer, performance-engineer |
| `/sc:explain` | learning-guide | technical-writer, domain specialists |
| `/sc:research` | deep-research-agent | Technical specialists, learning-guide |
### Effective Agent Combinations
**Development Workflows**:
- Web application: frontend-architect + backend-architect + security-engineer + quality-engineer + devops-architect
- API development: backend-architect + security-engineer + technical-writer + quality-engineer
- Data platform: python-expert + performance-engineer + security-engineer + system-architect
**Analysis Workflows**:
- Security audit: security-engineer + quality-engineer + root-cause-analyst + technical-writer
- Performance investigation: performance-engineer + root-cause-analyst + system-architect + devops-architect
- Legacy assessment: refactoring-expert + system-architect + quality-engineer + security-engineer + technical-writer
**Communication Workflows**:
- Technical documentation: technical-writer + requirements-analyst + domain experts + learning-guide
- Educational content: learning-guide + technical-writer + frontend-architect + quality-engineer
## Best Practices 💡
### Getting Started (Simple Approach)
**Natural Language First:**
1. **Describe Your Goal**: Use natural language with domain-specific keywords
2. **Trust Auto-Activation**: Let the system route to appropriate agents automatically
3. **Learn from Patterns**: Observe which agents activate for different request types
4. **Iterate and Refine**: Add specificity to engage additional specialist agents
### Optimizing Agent Selection
**Effective Keyword Usage:**
- **Specific > Generic**: Use "authentication" instead of "login" for security-engineer
- **Technical Terms**: Include framework names, technologies, and specific challenges
- **Context Clues**: Mention file types, project scope, and complexity indicators
- **Quality Keywords**: Add "security", "performance", "accessibility" for comprehensive coverage
**Request Optimization Examples:**
```bash
# Generic (limited agent activation)
"Fix the login feature"
# Optimized (multi-agent coordination)
"Implement secure JWT authentication with rate limiting and accessibility compliance"
# → Triggers: security-engineer + backend-architect + frontend-architect + quality-engineer
```
### Common Usage Patterns
**Development Workflows:**
```bash
# Full-stack feature development
/sc:implement "responsive user dashboard with real-time notifications"
# → frontend-architect + backend-architect + performance-engineer
# API development with documentation
/sc:create "REST API for payment processing with comprehensive docs"
# → backend-architect + security-engineer + technical-writer + quality-engineer
# Performance optimization investigation
/sc:troubleshoot "slow database queries affecting user experience"
# → performance-engineer + root-cause-analyst + backend-architect
```
**Analysis Workflows:**
```bash
# Security assessment
/sc:analyze "authentication system for GDPR compliance vulnerabilities"
# → security-engineer + quality-engineer + requirements-analyst
# Code quality review
/sc:review "legacy codebase for modernization opportunities"
# → refactoring-expert + system-architect + quality-engineer + technical-writer
# Learning and explanation
/sc:explain "microservices patterns with hands-on examples"
# → system-architect + learning-guide + technical-writer
```
### Advanced Agent Coordination
**Multi-Domain Projects:**
- **Start Broad**: Begin with system-level keywords to engage architecture agents
- **Add Specificity**: Include domain-specific needs to activate specialist agents
- **Quality Integration**: Automatically include security, performance, and testing perspectives
- **Documentation Inclusion**: Add learning or documentation needs for comprehensive coverage
**Troubleshooting Agent Selection:**
**Problem: Wrong agents activating**
- Solution: Use more specific domain terminology
- Example: "database optimization" → performance-engineer + backend-architect
**Problem: Not enough agents**
- Solution: Increase complexity indicators and cross-domain keywords
- Example: Add "security", "performance", "documentation" to requests
**Problem: Too many agents**
- Solution: Focus on primary domain with specific technical terms
- Example: Use "/sc:focus backend" to limit scope
### Quality-Driven Development
**Security-First Approach:**
Always include security considerations in development requests to automatically engage security-engineer alongside domain specialists.
**Performance Integration:**
Include performance keywords ("fast", "efficient", "scalable") to ensure performance-engineer coordination from the start.
**Accessibility Compliance:**
Use "accessible", "WCAG", or "inclusive" to automatically include accessibility validation in frontend development.
**Documentation Culture:**
Add "documented", "explained", or "tutorial" to requests for automatic technical-writer inclusion and knowledge transfer.
---
## Understanding Agent Intelligence 🧠
### What Makes Agents Effective
**Domain Expertise**: Each agent has specialized knowledge patterns, behavioral approaches, and problem-solving methodologies specific to their domain.
**Contextual Activation**: Agents analyze request context, not just keywords, to determine relevance and engagement level.
**Collaborative Intelligence**: Multi-agent coordination produces synergistic results that exceed individual agent capabilities.
**Adaptive Learning**: Agent selection improves based on request patterns and successful coordination outcomes.
### Agent vs. Traditional AI
**Traditional Approach**: Single AI handles all domains with varying levels of expertise
**Agent Approach**: Specialized experts collaborate with deep domain knowledge and focused problem-solving
**Benefits**:
- Higher accuracy in domain-specific tasks
- More sophisticated problem-solving methodologies
- Better quality assurance through specialist review
- Coordinated multi-perspective analysis
### Trust the System, Understand the Patterns
**What to Expect**:
- Automatic routing to appropriate domain experts
- Multi-agent coordination for complex tasks
- Quality integration through automatic QA agent inclusion
- Learning opportunities through educational agent activation
**What Not to Worry About**:
- Manual agent selection or configuration
- Complex routing rules or agent management
- Agent configuration or coordination
- Micromanaging agent interactions
---
## Related Resources 📚
### Essential Documentation
- **[Commands Guide](commands.md)** - Master SuperClaude commands that trigger optimal agent coordination
- **[MCP Servers](mcp-servers.md)** - Enhanced agent capabilities through specialized tool integration
- **[Session Management](session-management.md)** - Long-term workflows with persistent agent context
### Advanced Usage
- **[Behavioral Modes](modes.md)** - Context optimization for enhanced agent coordination
- **[Getting Started](../getting-started/quick-start.md)** - Expert techniques for agent optimization
- **[Examples Cookbook](../reference/examples-cookbook.md)** - Real-world agent coordination patterns
### Development Resources
- **[Technical Architecture](../developer-guide/technical-architecture.md)** - Understanding SuperClaude's agent system design
- **[Contributing](../developer-guide/contributing-code.md)** - Extending agent capabilities and coordination patterns
---
## Your Agent Journey 🚀
**Week 1: Natural Usage**
Start with natural language descriptions. Notice which agents activate and why. Build intuition for keyword patterns without overthinking the process.
**Week 2-3: Pattern Recognition**
Observe agent coordination patterns. Understand how complexity and domain keywords influence agent selection. Begin optimizing request phrasing for better coordination.
**Month 2+: Expert Coordination**
Master multi-domain requests that trigger optimal agent combinations. Leverage troubleshooting techniques for effective agent selection. Use advanced patterns for complex workflows.
**The SuperClaude Advantage:**
Experience the power of 14 specialized AI experts working in coordinated response, all through simple, natural language requests. No configuration, no management, just intelligent collaboration that scales with your needs.
🎯 **Ready to experience intelligent agent coordination? Start with `/sc:implement` and discover the magic of specialized AI collaboration.**

367
docs/user-guide/commands.md Normal file
View File

@@ -0,0 +1,367 @@
# SuperClaude Commands Guide
SuperClaude provides 25 commands for Claude Code: `/sc:*` commands for workflows and `@agent-*` for specialists.
## Command Types
| Type | Where Used | Format | Example |
|------|------------|--------|---------|
| **Slash Commands** | Claude Code | `/sc:[command]` | `/sc:implement "feature"` |
| **Agents** | Claude Code | `@agent-[name]` | `@agent-security "review"` |
| **Installation** | Terminal | `SuperClaude [command]` | `SuperClaude install` |
## Quick Test
```bash
# Terminal: Verify installation
python3 -m SuperClaude --version
# Claude Code CLI verification: claude --version
# Claude Code: Test commands
/sc:brainstorm "test project" # Should ask discovery questions
/sc:analyze README.md # Should provide analysis
```
**Workflow**: `/sc:brainstorm "idea"` → `/sc:implement "feature"` → `/sc:test`
## 🎯 Understanding SuperClaude Commands
## How SuperClaude Works
SuperClaude provides behavioral context files that Claude Code reads to adopt specialized behaviors. When you type `/sc:implement`, Claude Code reads the `implement.md` context file and follows its behavioral instructions.
**SuperClaude commands are NOT executed by software** - they are context triggers that modify Claude Code's behavior through reading specialized instruction files from the framework.
### Command Types:
- **Slash Commands** (`/sc:*`): Trigger workflow patterns and behavioral modes
- **Agent Invocations** (`@agent-*`): Manually activate specific domain specialists
- **Flags** (`--think`, `--safe-mode`): Modify command behavior and depth
### The Context Mechanism:
1. **User Input**: You type `/sc:implement "auth system"`
2. **Context Loading**: Claude Code reads `~/.claude/superclaude/Commands/implement.md`
3. **Behavior Adoption**: Claude applies domain expertise, tool selection, and validation patterns
4. **Enhanced Output**: Structured implementation with security considerations and best practices
**Key Point**: This creates sophisticated development workflows through context management rather than traditional software execution.
### Installation vs Usage Commands
**🖥️ Terminal Commands** (Actual CLI software):
- `SuperClaude install` - Installs the framework components
- `SuperClaude update` - Updates existing installation
- `SuperClaude uninstall` - Removes framework installation
- `python3 -m SuperClaude --version` - Check installation status
**💬 Claude Code Commands** (Context triggers):
- `/sc:brainstorm` - Activates requirements discovery context
- `/sc:implement` - Activates feature development context
- `@agent-security` - Activates security specialist context
- All commands work inside Claude Code chat interface only
> **Quick Start**: Try `/sc:brainstorm "your project idea"` → `/sc:implement "feature name"` → `/sc:test` to experience the core workflow.
## 🧪 Testing Your Setup
### 🖥️ Terminal Verification (Run in Terminal/CMD)
```bash
# Verify SuperClaude is working (primary method)
python3 -m SuperClaude --version
# Example output: SuperClaude 4.1.5
# Claude Code CLI version check
claude --version
# Check installed components
python3 -m SuperClaude install --list-components | grep mcp
# Example output: Shows installed MCP components
```
### 💬 Claude Code Testing (Type in Claude Code Chat)
```
# Test basic /sc: command
/sc:brainstorm "test project"
# Example behavior: Interactive requirements discovery starts
# Test command help
/sc:help
# Example behavior: List of available commands
```
**If tests fail**: Check [Installation Guide](../getting-started/installation.md) or [Troubleshooting](#troubleshooting)
### 📝 Command Quick Reference
| Command Type | Where to Run | Format | Purpose | Example |
|-------------|--------------|--------|---------|----------|
| **🖥️ Installation** | Terminal/CMD | `SuperClaude [command]` | Setup and maintenance | `SuperClaude install` |
| **🔧 Configuration** | Terminal/CMD | `python3 -m SuperClaude [command]` | Advanced configuration | `python3 -m SuperClaude --version` |
| **💬 Slash Commands** | Claude Code | `/sc:[command]` | Workflow automation | `/sc:implement "feature"` |
| **🤖 Agent Invocation** | Claude Code | `@agent-[name]` | Manual specialist activation | `@agent-security "review"` |
| **⚡ Enhanced Flags** | Claude Code | `/sc:[command] --flags` | Behavior modification | `/sc:analyze --think-hard` |
> **Remember**: All `/sc:` commands and `@agent-` invocations work inside Claude Code chat, not your terminal. They trigger Claude Code to read specific context files from the SuperClaude framework.
## Table of Contents
- [Essential Commands](#essential-commands) - Start here (8 core commands)
- [Common Workflows](#common-workflows) - Command combinations that work
- [Full Command Reference](#full-command-reference) - All 25 commands organized by category
- [Troubleshooting](#troubleshooting) - Common issues and solutions
- [Command Index](#command-index) - Find commands by category
---
## Essential Commands
**Core workflow commands for immediate productivity:**
### `/sc:brainstorm` - Project Discovery
**Purpose**: Interactive requirements discovery and project planning
**Syntax**: `/sc:brainstorm "your idea"` `[--strategy systematic|creative]`
**Use Cases**:
- New project planning: `/sc:brainstorm "e-commerce platform"`
- Feature exploration: `/sc:brainstorm "user authentication system"`
- Problem solving: `/sc:brainstorm "slow database queries"`
### `/sc:help` - Command Reference
**Purpose**: Displays a list of all available `/sc` commands and their descriptions.
**Syntax**: `/sc:help`
**Use Cases**:
- Discovering available commands: `/sc:help`
- Getting a quick reminder of command names: `/sc:help`
### `/sc:research` - Deep Research Command
**Purpose**: Comprehensive web research with adaptive planning and intelligent search
**Syntax**: `/sc:research "[query]"` `[--depth quick|standard|deep|exhaustive] [--strategy planning|intent|unified]`
**Use Cases**:
- Technical research: `/sc:research "latest React 19 features" --depth deep`
- Market analysis: `/sc:research "AI coding assistant landscape 2024" --strategy unified`
- Academic investigation: `/sc:research "quantum computing breakthroughs" --depth exhaustive`
- Current events: `/sc:research "latest AI developments 2024"`
**Key Capabilities**:
- **6-Phase Workflow**: Understand → Plan → TodoWrite → Execute → Track → Validate
- **Adaptive Depth**: Quick (basic search), Standard (extended), Deep (comprehensive), Exhaustive (maximum depth)
- **Planning Strategies**: Planning (direct), Intent (clarify first), Unified (collaborative)
- **Parallel Execution**: Default parallel searches and extractions
- **Evidence Management**: Clear citations with relevance scoring
- **Output Standards**: Reports saved to `claudedocs/research_[topic]_[timestamp].md`
### `/sc:implement` - Feature Development
**Purpose**: Full-stack feature implementation with intelligent specialist routing
**Syntax**: `/sc:implement "feature description"` `[--type frontend|backend|fullstack] [--focus security|performance]`
**Use Cases**:
- Authentication: `/sc:implement "JWT login system"`
- UI components: `/sc:implement "responsive dashboard"`
- APIs: `/sc:implement "REST user endpoints"`
- Database: `/sc:implement "user schema with relationships"`
### `/sc:analyze` - Code Assessment
**Purpose**: Comprehensive code analysis across quality, security, and performance
**Syntax**: `/sc:analyze [path]` `[--focus quality|security|performance|architecture]`
**Use Cases**:
- Project health: `/sc:analyze .`
- Security audit: `/sc:analyze --focus security`
- Performance review: `/sc:analyze --focus performance`
### `/sc:business-panel` - Strategic Business Analysis
**Purpose**: Multi-expert business strategy analysis with 9 renowned thought leaders
**Syntax**: `/sc:business-panel "content"` `[--mode discussion|debate|socratic] [--experts "name1,name2"]`
**Use Cases**:
- Strategy evaluation: `/sc:business-panel "our go-to-market strategy"`
- Competitive analysis: `/sc:business-panel @competitor_analysis.pdf --mode debate`
- Innovation assessment: `/sc:business-panel "AI product idea" --experts "christensen,drucker"`
- Strategic learning: `/sc:business-panel "competitive strategy" --mode socratic`
**Expert Panel**: Christensen, Porter, Drucker, Godin, Kim/Mauborgne, Collins, Taleb, Meadows, Doumont
### `/sc:spec-panel` - Expert Specification Review
**Purpose**: Multi-expert specification review and improvement using renowned specification and software engineering experts
**Syntax**: `/sc:spec-panel [content|@file]` `[--mode discussion|critique|socratic] [--focus requirements|architecture|testing|compliance]`
**Use Cases**:
- Specification review: `/sc:spec-panel @api_spec.yml --mode critique --focus requirements,architecture`
- Requirements workshop: `/sc:spec-panel "user story content" --mode discussion`
- Architecture validation: `/sc:spec-panel @microservice.spec.yml --mode socratic --focus architecture`
- Compliance review: `/sc:spec-panel @security_requirements.yml --focus compliance`
- Iterative improvement: `/sc:spec-panel @complex_system.spec.yml --iterations 3`
**Expert Panel**: Wiegers, Adzic, Cockburn, Fowler, Nygard, Newman, Hohpe, Crispin, Gregory, Hightower
### `/sc:troubleshoot` - Problem Diagnosis
**Purpose**: Systematic issue diagnosis with root cause analysis
**Syntax**: `/sc:troubleshoot "issue description"` `[--type build|runtime|performance]`
**Use Cases**:
- Runtime errors: `/sc:troubleshoot "500 error on login"`
- Build failures: `/sc:troubleshoot --type build`
- Performance problems: `/sc:troubleshoot "slow page load"`
### `/sc:test` - Quality Assurance
**Purpose**: Comprehensive testing with coverage analysis
**Syntax**: `/sc:test` `[--type unit|integration|e2e] [--coverage] [--fix]`
**Use Cases**:
- Full test suite: `/sc:test --coverage`
- Unit testing: `/sc:test --type unit --watch`
- E2E validation: `/sc:test --type e2e`
### `/sc:improve` - Code Enhancement
**Purpose**: Apply systematic code improvements and optimizations
**Syntax**: `/sc:improve [path]` `[--type performance|quality|security] [--preview]`
**Use Cases**:
- General improvements: `/sc:improve src/`
- Performance optimization: `/sc:improve --type performance`
- Security hardening: `/sc:improve --type security`
### `/sc:document` - Documentation Generation
**Purpose**: Generate comprehensive documentation for code and APIs
**Syntax**: `/sc:document [path]` `[--type api|user-guide|technical] [--format markdown|html]`
**Use Cases**:
- API docs: `/sc:document --type api`
- User guides: `/sc:document --type user-guide`
- Technical docs: `/sc:document --type technical`
### `/sc:workflow` - Implementation Planning
**Purpose**: Generate structured implementation plans from requirements
**Syntax**: `/sc:workflow "feature description"` `[--strategy agile|waterfall] [--format markdown]`
**Use Cases**:
- Feature planning: `/sc:workflow "user authentication"`
- Sprint planning: `/sc:workflow --strategy agile`
- Architecture planning: `/sc:workflow "microservices migration"`
---
## Common Workflows
**Proven command combinations:**
### New Project Setup
```bash
/sc:brainstorm "project concept" # Define requirements
/sc:design "system architecture" # Create technical design
/sc:workflow "implementation plan" # Generate development roadmap
```
### Feature Development
```bash
/sc:implement "feature name" # Build the feature
/sc:test --coverage # Validate with tests
/sc:document --type api # Generate documentation
```
### Code Quality Improvement
```bash
/sc:analyze --focus quality # Assess current state
/sc:improve --preview # Preview improvements
/sc:test --coverage # Validate changes
```
### Bug Investigation
```bash
/sc:troubleshoot "issue description" # Diagnose the problem
/sc:analyze --focus problem-area # Deep analysis
/sc:improve --fix --safe-mode # Apply targeted fixes
```
### Specification Development
```bash
/sc:spec-panel @existing_spec.yml --mode critique # Expert review
/sc:spec-panel @improved_spec.yml --iterations 2 # Iterative refinement
/sc:document --type technical # Generate documentation
```
## Full Command Reference
### Development Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **workflow** | Implementation planning | Project roadmaps, sprint planning |
| **implement** | Feature development | Full-stack features, API development |
| **build** | Project compilation | CI/CD, production builds |
| **design** | System architecture | API specs, database schemas |
### Analysis Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **analyze** | Code assessment | Quality audits, security reviews |
| **research** | Web research with intelligent search | Technical research, current events, market analysis |
| **business-panel** | Strategic analysis | Business decisions, competitive assessment |
| **spec-panel** | Specification review | Requirements validation, architecture analysis |
| **troubleshoot** | Problem diagnosis | Bug investigation, performance issues |
| **explain** | Code explanation | Learning, code reviews |
### Quality Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **improve** | Code enhancement | Performance optimization, refactoring |
| **cleanup** | Technical debt | Dead code removal, organization |
| **test** | Quality assurance | Test automation, coverage analysis |
| **document** | Documentation | API docs, user guides |
### Project Management
| Command | Purpose | Best For |
|---------|---------|----------|
| **estimate** | Project estimation | Timeline planning, resource allocation |
| **task** | Task management | Complex workflows, task tracking |
| **spawn** | Meta-orchestration | Large-scale projects, parallel execution |
### Utility Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **help** | List all commands | Discovering available commands |
| **git** | Version control | Commit management, branch strategies |
| **index** | Command discovery | Exploring capabilities, finding commands |
### Session Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **load** | Context loading | Session initialization, project onboarding |
| **save** | Session persistence | Checkpointing, context preservation |
| **reflect** | Task validation | Progress assessment, completion validation |
| **select-tool** | Tool optimization | Performance optimization, tool selection |
---
## Command Index
**By Function:**
- **Planning**: brainstorm, design, workflow, estimate
- **Development**: implement, build, git
- **Analysis**: analyze, business-panel, spec-panel, troubleshoot, explain
- **Quality**: improve, cleanup, test, document
- **Management**: task, spawn, load, save, reflect
- **Utility**: help, index, select-tool
**By Complexity:**
- **Beginner**: brainstorm, implement, analyze, test, help
- **Intermediate**: workflow, design, business-panel, spec-panel, improve, document
- **Advanced**: spawn, task, select-tool, reflect
## Troubleshooting
**Command Issues:**
- **Command not found**: Verify installation: `python3 -m SuperClaude --version`
- **No response**: Restart Claude Code session
- **Processing delays**: Use `--no-mcp` to test without MCP servers
**Quick Fixes:**
- Reset session: `/sc:load` to reinitialize
- Check status: `SuperClaude install --list-components`
- Get help: [Troubleshooting Guide](../reference/troubleshooting.md)
## Next Steps
- [Flags Guide](flags.md) - Control command behavior
- [Agents Guide](agents.md) - Specialist activation
- [Examples Cookbook](../reference/examples-cookbook.md) - Real usage patterns

273
docs/user-guide/flags.md Normal file
View File

@@ -0,0 +1,273 @@
# SuperClaude Flags Guide 🏁
**Most flags activate automatically** - Claude Code reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests.
## Essential Auto-Activation Flags (90% of Use Cases)
### Core Analysis Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--think` | 5+ files OR complex analysis | Standard structured analysis (~4K tokens) |
| `--think-hard` | Architectural analysis, system dependencies | Deep analysis (~10K tokens) with enhanced tools |
| `--ultrathink` | Critical system redesign, legacy modernization | Maximum depth analysis (~32K tokens) with all tools |
### MCP Server Flags
| Flag | Server | Purpose | Auto-Triggers |
|------|---------|---------|---------------|
| `--c7` / `--context7` | Context7 | Official docs, framework patterns | Library imports, framework questions |
| `--seq` / `--sequential` | Sequential | Multi-step reasoning, debugging | Complex debugging, system design |
| `--magic` | Magic | UI component generation | `/ui` commands, frontend keywords |
| `--play` / `--playwright` | Playwright | Browser testing, E2E validation | Testing requests, visual validation |
| `--chrome` / `--devtools` | Chrome DevTools | Performance analysis, debugging | Performance auditing, debugging, layout issues |
| `--tavily` | Tavily | Web search, real-time info | Web search requests, research queries |
| `--morph` / `--morphllm` | Morphllm | Bulk transformations, pattern edits | Bulk operations, style enforcement |
| `--serena` | Serena | Project memory, symbol operations | Symbol operations, large codebases |
### Behavioral Mode Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--brainstorm` | Vague requests, exploration keywords | Collaborative discovery mindset |
| `--introspect` | Self-analysis, error recovery | Expose reasoning process with transparency |
| `--task-manage` | >3 steps, complex scope | Orchestrate through delegation |
| `--orchestrate` | Multi-tool operations, performance needs | Optimize tool selection and parallel execution |
| `--token-efficient` / `--uc` | Context >75%, efficiency needs | Symbol-enhanced communication, 30-50% reduction |
### Execution Control Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--loop` | "improve", "polish", "refine" keywords | Iterative enhancement cycles |
| `--safe-mode` | Production, >85% resource usage | Maximum validation, conservative execution |
| `--validate` | Risk >0.7, production environment | Pre-execution risk assessment |
| `--delegate` | >7 directories OR >50 files | Sub-agent parallel processing |
## Command-Specific Flags
### Analysis Command Flags (`/sc:analyze`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--focus` | Target specific domain | `security`, `performance`, `quality`, `architecture` |
| `--depth` | Analysis thoroughness | `quick`, `deep` |
| `--format` | Output format | `text`, `json`, `report` |
### Build Command Flags (`/sc:build`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Build configuration | `dev`, `prod`, `test` |
| `--clean` | Clean before build | Boolean |
| `--optimize` | Enable optimizations | Boolean |
| `--verbose` | Detailed output | Boolean |
### Design Command Flags (`/sc:design`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Design target | `architecture`, `api`, `component`, `database` |
| `--format` | Output format | `diagram`, `spec`, `code` |
### Explain Command Flags (`/sc:explain`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--level` | Complexity level | `basic`, `intermediate`, `advanced` |
| `--format` | Explanation style | `text`, `examples`, `interactive` |
| `--context` | Domain context | Any domain (e.g., `react`, `security`) |
### Improve Command Flags (`/sc:improve`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Improvement focus | `quality`, `performance`, `maintainability`, `style`, `security` |
| `--safe` | Conservative approach | Boolean |
| `--interactive` | User guidance | Boolean |
| `--preview` | Show without executing | Boolean |
### Task Command Flags (`/sc:task`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Task approach | `systematic`, `agile`, `enterprise` |
| `--parallel` | Parallel execution | Boolean |
| `--delegate` | Sub-agent coordination | Boolean |
### Workflow Command Flags (`/sc:workflow`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Workflow approach | `systematic`, `agile`, `enterprise` |
| `--depth` | Analysis depth | `shallow`, `normal`, `deep` |
| `--parallel` | Parallel coordination | Boolean |
### Troubleshoot Command Flags (`/sc:troubleshoot`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Issue category | `bug`, `build`, `performance`, `deployment` |
| `--trace` | Include trace analysis | Boolean |
| `--fix` | Apply fixes | Boolean |
### Cleanup Command Flags (`/sc:cleanup`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Cleanup target | `code`, `imports`, `files`, `all` |
| `--safe` / `--aggressive` | Cleanup intensity | Boolean |
| `--interactive` | User guidance | Boolean |
| `--preview` | Show without executing | Boolean |
### Estimate Command Flags (`/sc:estimate`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Estimate focus | `time`, `effort`, `complexity` |
| `--unit` | Time unit | `hours`, `days`, `weeks` |
| `--breakdown` | Detailed breakdown | Boolean |
### Index Command Flags (`/sc:index`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Index target | `docs`, `api`, `structure`, `readme` |
| `--format` | Output format | `md`, `json`, `yaml` |
### Reflect Command Flags (`/sc:reflect`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Reflection scope | `task`, `session`, `completion` |
| `--analyze` | Include analysis | Boolean |
| `--validate` | Validate completeness | Boolean |
### Spawn Command Flags (`/sc:spawn`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Coordination approach | `sequential`, `parallel`, `adaptive` |
| `--depth` | Analysis depth | `normal`, `deep` |
### Git Command Flags (`/sc:git`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--smart-commit` | Generate commit message | Boolean |
| `--interactive` | Guided operations | Boolean |
### Select-Tool Command Flags (`/sc:select-tool`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--analyze` | Tool analysis | Boolean |
| `--explain` | Explain selection | Boolean |
### Test Command Flags (`/sc:test`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--coverage` | Include coverage | Boolean |
| `--type` | Test type | `unit`, `integration`, `e2e` |
| `--watch` | Watch mode | Boolean |
## Advanced Control Flags
### Scope and Focus
| Flag | Purpose | Values |
|------|---------|--------|
| `--scope` | Analysis boundary | `file`, `module`, `project`, `system` |
| `--focus` | Domain targeting | `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing` |
### Execution Control
| Flag | Purpose | Values |
|------|---------|--------|
| `--concurrency [n]` | Control parallel ops | 1-15 |
| `--iterations [n]` | Improvement cycles | 1-10 |
| `--all-mcp` | Enable all MCP servers | Boolean |
| `--no-mcp` | Native tools only | Boolean |
| `--frontend-verify` | UI testing, frontend debugging, layout validation | Enable Playwright + Chrome DevTools + Serena |
### System Flags (SuperClaude Installation)
| Flag | Purpose | Values |
|------|---------|--------|
| `--verbose` / `-v` | Verbose logging | Boolean |
| `--quiet` / `-q` | Suppress output | Boolean |
| `--dry-run` | Simulate operation | Boolean |
| `--force` | Skip checks | Boolean |
| `--yes` / `-y` | Auto-confirm | Boolean |
| `--install-dir` | Target directory | Path |
| `--legacy` | Use legacy script | Boolean |
| `--version` | Show version | Boolean |
| `--help` | Show help | Boolean |
## Common Usage Patterns
### Frontend Development
```bash
/sc:implement "responsive dashboard" --magic --c7
/sc:design component-library --type component --format code
/sc:test ui-components/ --magic --play
/sc:improve legacy-ui/ --magic --morph --validate
```
### Backend Development
```bash
/sc:analyze api/ --focus performance --seq --think
/sc:design payment-api --type api --format spec
/sc:troubleshoot "API timeout" --type performance --trace
/sc:improve auth-service --type security --validate
```
### Large Projects
```bash
/sc:analyze . --ultrathink --all-mcp --safe-mode
/sc:workflow enterprise-system --strategy enterprise --depth deep
/sc:cleanup . --type all --safe --interactive
/sc:estimate "migrate to microservices" --type complexity --breakdown
```
### Quality & Maintenance
```bash
/sc:improve src/ --type quality --safe --interactive
/sc:cleanup imports --type imports --preview
/sc:reflect --type completion --validate
/sc:git commit --smart-commit
```
## Flag Interactions
### Compatible Combinations
- `--think` + `--c7`: Analysis with documentation
- `--magic` + `--play`: UI generation with testing
- `--serena` + `--morph`: Project memory with transformations
- `--safe-mode` + `--validate`: Maximum safety
- `--loop` + `--validate`: Iterative improvement with validation
### Conflicting Flags
- `--all-mcp` vs individual MCP flags (use one or the other)
- `--no-mcp` vs any MCP flags (--no-mcp wins)
- `--safe` vs `--aggressive` (cleanup intensity)
- `--quiet` vs `--verbose` (output level)
### Auto-Enabling Relationships
- `--safe-mode` auto-enables `--uc` and `--validate`
- `--ultrathink` auto-enables all MCP servers
- `--think-hard` auto-enables `--seq` + `--c7`
- `--magic` triggers UI-focused agents
## Troubleshooting Flags
### Common Issues
- **Too many tools**: Use `--no-mcp` to test with native tools only
- **Operation too slow**: Add `--uc` to compress output
- **Validation blocking**: Use `--validate` instead of `--safe-mode` in development
- **Context pressure**: Auto-activates `--token-efficient` at >75% usage
### Debug Flags
```bash
/sc:analyze . --verbose # Shows decision logic and flag activation
/sc:select-tool "operation" --explain # Explains tool selection process
/sc:reflect --type session --analyze # Reviews current session decisions
```
### Quick Fixes
```bash
/sc:analyze . --help # Shows available flags for command
/sc:analyze . --no-mcp # Native execution only
/sc:cleanup . --preview # Shows what would be cleaned
```
## Flag Priority Rules
1. **Safety First**: `--safe-mode` > `--validate` > optimization flags
2. **Explicit Override**: User flags > auto-detection
3. **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think`
4. **MCP Control**: `--no-mcp` overrides all individual MCP flags
5. **Scope Precedence**: system > project > module > file
## Related Resources
- [Commands Guide](commands.md) - Commands that use these flags
- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation
- [Session Management](session-management.md) - Using flags with persistent sessions

339
docs/user-guide/mcp-servers.md Normal file
View File

@@ -0,0 +1,339 @@
# SuperClaude MCP Servers Guide 🔌
## Overview
MCP (Model Context Protocol) servers extend Claude Code's capabilities through specialized tools. SuperClaude integrates 8 MCP servers and provides Claude with instructions on when to activate them based on your tasks.
### 🔍 Reality Check
- **What MCP servers are**: External Node.js processes that provide additional tools
- **What they aren't**: Built-in SuperClaude functionality
- **How activation works**: Claude reads instructions to use appropriate servers based on context
- **What they provide**: Real tools that extend Claude Code's native capabilities
**Core Servers:**
- **context7**: Official library documentation and patterns
- **sequential-thinking**: Multi-step reasoning and analysis
- **magic**: Modern UI component generation
- **playwright**: Browser automation and E2E testing
- **morphllm-fast-apply**: Pattern-based code transformations
- **serena**: Semantic code understanding and project memory
- **tavily**: Web search and real-time information retrieval
- **chrome-devtools**: Performance analysis and debugging
## Quick Start
**Setup Verification**: MCP servers activate automatically. For installation and troubleshooting, see [Installation Guide](../getting-started/installation.md) and [Troubleshooting](../reference/troubleshooting.md).
**Auto-Activation Logic:**
| Request Contains | Servers Activated |
|-----------------|------------------|
| Library imports, API names | **context7** |
| `--think`, debugging | **sequential-thinking** |
| `component`, `UI`, frontend | **magic** |
| `test`, `e2e`, `browser` | **playwright** |
| Multi-file edits, refactoring | **morphllm-fast-apply** |
| Large projects, sessions | **serena** |
| `/sc:research`, `latest`, `current` | **tavily** |
| `performance`, `debug`, `LCP` | **chrome-devtools** |
## Server Details
### context7 📚
**Purpose**: Official library documentation access
**Triggers**: Import statements, framework keywords, documentation requests
**Requirements**: Node.js 16+, no API key
```bash
# Automatic activation
/sc:implement "React authentication system"
# → Provides official React patterns
# Manual activation
/sc:analyze auth-system/ --c7
```
### sequential-thinking 🧠
**Purpose**: Structured multi-step reasoning and systematic analysis
**Triggers**: Complex debugging, `--think` flags, architectural analysis
**Requirements**: Node.js 16+, no API key
```bash
# Automatic activation
/sc:troubleshoot "API performance issues"
# → Enables systematic root cause analysis
# Manual activation
/sc:analyze --think-hard architecture/
```
### magic ✨
**Purpose**: Modern UI component generation from 21st.dev patterns
**Triggers**: UI requests, `/ui` commands, component development
**Requirements**: Node.js 16+, TWENTYFIRST_API_KEY ()
```bash
# Automatic activation
/sc:implement "responsive dashboard component"
# → Generates accessible UI with modern patterns
# API key setup
export TWENTYFIRST_API_KEY="your_key_here"
```
### playwright 🎭
**Purpose**: Real browser automation and E2E testing
**Triggers**: Browser testing, E2E scenarios, visual validation
**Requirements**: Node.js 16+, no API key
```bash
# Automatic activation
/sc:test --type e2e "user login flow"
# → Enables browser automation testing
# Manual activation
/sc:validate "accessibility compliance" --play
```
### morphllm-fast-apply 🔄
**Purpose**: Efficient pattern-based code transformations
**Triggers**: Multi-file edits, refactoring, framework migrations
**Requirements**: Node.js 16+, MORPH_API_KEY
```bash
# Automatic activation
/sc:improve legacy-codebase/ --focus maintainability
# → Applies consistent patterns across files
# API key setup
export MORPH_API_KEY="your_key_here"
```
### serena 🧭
**Purpose**: Semantic code understanding with project memory
**Triggers**: Symbol operations, large codebases, session management
**Requirements**: Python 3.9+, uv package manager, no API key
```bash
# Automatic activation
/sc:load existing-project/
# → Builds project understanding and memory
# Manual activation
/sc:refactor "extract UserService" --serena
```
### tavily 🔍
**Purpose**: Web search and real-time information retrieval for research
**Triggers**: `/sc:research` commands, "latest" information requests, current events, fact-checking
**Requirements**: Node.js 16+, TAVILY_API_KEY (free tier available at https://app.tavily.com)
```bash
# Automatic activation
/sc:research "latest AI developments 2024"
# → Performs intelligent web research
# Manual activation
/sc:analyze "market trends" --tavily
# API key setup (get free key at https://app.tavily.com)
export TAVILY_API_KEY="tvly-your_api_key_here"
```
### chrome-devtools 📊
**Purpose**: Performance analysis, debugging, and real-time browser inspection
**Triggers**: Performance auditing, debugging layout issues (e.g., CLS), slow loading times (LCP), console errors, network requests
**Requirements**: Node.js 16+, no API key
```bash
# Automatic activation
/sc:debug "page is loading slowly"
# → Enables performance analysis with Chrome DevTools
# Manual activation
/sc:analyze --performance "homepage"
```
**Capabilities:**
- **Web Search**: Comprehensive searches with ranking and filtering
- **News Search**: Time-filtered current events and updates
- **Content Extraction**: Full-text extraction from search results
- **Domain Filtering**: Include/exclude specific domains
- **Multi-Hop Research**: Iterative searches based on findings (up to 5 hops)
**Research Depth Control:**
- `--depth quick`: 5-10 sources, basic synthesis
- `--depth standard`: 10-20 sources, structured report (default)
- `--depth deep`: 20-40 sources, comprehensive analysis
- `--depth exhaustive`: 40+ sources, academic-level research
## Configuration
**MCP Configuration File (`~/.claude.json`):**
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
},
"magic": {
"command": "npx",
"args": ["@21st-dev/magic"],
"env": {"TWENTYFIRST_API_KEY": "${TWENTYFIRST_API_KEY}"}
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"morphllm-fast-apply": {
"command": "npx",
"args": ["@morph-llm/morph-fast-apply"],
"env": {"MORPH_API_KEY": "${MORPH_API_KEY}"}
},
"serena": {
"command": "uvx",
"args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
},
"tavily": {
"command": "npx",
"args": ["-y", "tavily-mcp@latest"],
"env": {"TAVILY_API_KEY": "${TAVILY_API_KEY}"}
},
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
```
## Usage Patterns
**Server Control:**
```bash
# Enable specific servers
/sc:analyze codebase/ --c7 --seq
# Disable all MCP servers
/sc:implement "simple function" --no-mcp
# Enable all servers
/sc:design "complex architecture" --all-mcp
```
**Multi-Server Coordination:**
```bash
# Full-stack development
/sc:implement "e-commerce checkout"
# → Sequential: workflow analysis
# → Context7: payment patterns
# → Magic: UI components
# → Serena: code organization
# → Playwright: E2E testing
```
## Troubleshooting
**Common Issues:**
- **No servers connected**: Check Node.js: `node --version` (need v16+)
- **Context7 fails**: Clear cache: `npm cache clean --force`
- **Magic/Morphllm errors**: Expected without API keys (paid services)
- **Server timeouts**: Restart Claude Code session
**Quick Fixes:**
```bash
# Reset connections
# Restart Claude Code session
# Check dependencies
node --version # Should show v16+
# Test without MCP
/sc:command --no-mcp
# Check configuration
ls ~/.claude.json
```
**API Key Configuration:**
```bash
# For Magic server (required for UI generation)
export TWENTYFIRST_API_KEY="your_key_here"
# For Morphllm server (required for bulk transformations)
export MORPH_API_KEY="your_key_here"
# For Tavily server (required for web search - free tier available)
export TAVILY_API_KEY="tvly-your_key_here"
# Add to shell profile for persistence
echo 'export TWENTYFIRST_API_KEY="your_key"' >> ~/.bashrc
echo 'export MORPH_API_KEY="your_key"' >> ~/.bashrc
echo 'export TAVILY_API_KEY="your_key"' >> ~/.bashrc
```
**Environment Variable Usage:**
- ✅ `TWENTYFIRST_API_KEY` - Required for Magic MCP server functionality
- ✅ `MORPH_API_KEY` - Required for Morphllm MCP server functionality
- ✅ `TAVILY_API_KEY` - Required for Tavily MCP server functionality (free tier available)
- ❌ Other env vars in docs - Examples only, not used by framework
- 📝 Magic and Morphllm are paid services, Tavily has free tier, framework works without them
## Server Combinations
**No API Keys (Free)**:
- context7 + sequential-thinking + playwright + serena
**1 API Key**:
- Add magic for professional UI development
**2 API Keys**:
- Add morphllm-fast-apply for large-scale refactoring
**Common Workflows:**
- **Learning**: context7 + sequential-thinking
- **Web Development**: magic + context7 + playwright
- **Enterprise Refactoring**: serena + morphllm + sequential-thinking
- **Complex Analysis**: sequential-thinking + context7 + serena
- **Deep Research**: tavily + sequential-thinking + serena + playwright
- **Current Events**: tavily + context7 + sequential-thinking
- **Performance Tuning**: chrome-devtools + sequential-thinking + playwright
## Integration
**With SuperClaude Commands:**
- Analysis commands automatically use Sequential + Serena
- Implementation commands use Magic + Context7
- Testing commands use Playwright + Sequential
- Research commands use Tavily + Sequential + Playwright
**With Behavioral Modes:**
- Brainstorming Mode: Sequential for discovery
- Task Management: Serena for persistence
- Orchestration Mode: Optimal server selection
- Deep Research Mode: Tavily + Sequential + Playwright coordination
**Performance Control:**
- Automatic resource management based on system load
- Concurrency control: `--concurrency N` (1-15)
- Priority-based server selection under constraints
## Related Resources
**Essential Reading:**
- [Commands Guide](commands.md) - Commands that activate MCP servers
- [Quick Start Guide](../getting-started/quick-start.md) - MCP setup guide
**Advanced Usage:**
- [Behavioral Modes](modes.md) - Mode-MCP coordination
- [Agents Guide](agents.md) - Agent-MCP integration
- [Session Management](session-management.md) - Serena workflows
**Technical References:**
- [Examples Cookbook](../reference/examples-cookbook.md) - MCP workflow patterns
- [Technical Architecture](../developer-guide/technical-architecture.md) - Integration details

659
docs/user-guide/modes.md Normal file
View File

@@ -0,0 +1,659 @@
# SuperClaude Behavioral Modes Guide 🧠
## ✅ Quick Verification
Test modes by using `/sc:` commands - they activate automatically based on task complexity. For full command reference, see [Commands Guide](commands.md).
## Quick Reference Table
| Mode | Purpose | Auto-Triggers | Key Behaviors | Best Used For |
|------|---------|---------------|---------------|---------------|
| **🧠 Brainstorming** | Interactive discovery | "brainstorm", "maybe", vague requests | Socratic questions, requirement elicitation | New project planning, unclear requirements |
| **🔍 Introspection** | Meta-cognitive analysis | Error recovery, "analyze reasoning" | Transparent thinking markers (🤔, 🎯, 💡) | Debugging, learning, optimization |
| **🔬 Deep Research** | Systematic investigation mindset | `/sc:research`, investigation keywords | 6-phase workflow, evidence-based reasoning | Technical research, current events, market analysis |
| **📋 Task Management** | Complex coordination | >3 steps, >2 directories | Phase breakdown, memory persistence | Multi-step operations, project management |
| **🎯 Orchestration** | Intelligent tool selection | Multi-tool ops, high resource usage | Optimal tool routing, parallel execution | Complex analysis, performance optimization |
| **⚡ Token Efficiency** | Compressed communication | High context usage, `--uc` flag | Symbol systems, estimated 30-50% token reduction | Resource constraints, large operations |
---
## Getting Started (2-Minute Overview)
**Modes activate through behavioral instructions** - Claude Code reads context files to determine which mode behaviors to adopt based on your task patterns and complexity.
**Quick Examples:**
```bash
# Automatic activation examples
/sc:brainstorm "mobile app" # → Socratic discovery questions
/sc:implement "auth system" # → Multi-phase coordination
"--uc analyze large-codebase/" # → Compressed symbol output
```
**When to use manual flags:**
- Need specific behavior: `--brainstorm`, `--introspect`, `--uc`
- Override automatic detection for learning/debugging
- Optimize for specific constraints (memory, time, clarity)
---
## Mode Details
### 🧠 Brainstorming Mode - Interactive Discovery
**Purpose**: Transform vague ideas into structured requirements through collaborative discovery.
**Auto-Activation Triggers:**
- Vague project requests: "I want to build...", "Thinking about creating..."
- Exploration keywords: brainstorm, explore, discuss, figure out, not sure
- Uncertainty indicators: "maybe", "possibly", "could we"
- Manual flags: `--brainstorm`, `--bs`
**Behavioral Changes:**
- **Socratic Questioning**: Asks probing questions to uncover hidden requirements
- **Non-Presumptive Approach**: Avoids assumptions, lets you guide discovery direction
- **Collaborative Partnership**: Works with you in exploration rather than directive consultation
- **Requirement Synthesis**: Converts insights into structured technical briefs
- **Cross-Session Memory**: Maintains discovery context for follow-up discussions
**Example Experience:**
```
Standard Approach: "I'll build a user authentication system with JWT tokens..."
Brainstorming Approach:
"🤔 Let's explore this together:
- What specific user problems does auth solve for your app?
- Who are your users and what's their technical comfort level?
- Any existing systems or social logins to integrate with?
- What security/compliance requirements do you have?
📝 Outcome: Detailed auth requirements brief ready for implementation"
```
#### Success Criteria
- [ ] Responds with questions instead of immediate solutions
- [ ] Questions explore user needs, technical constraints, and business goals
- [ ] Maintains collaborative tone throughout discovery process
- [ ] Produces structured requirements or technical brief as outcome
**Verify:** `/sc:brainstorm "web app"` should ask about users, features, technology
**Test:** Vague requests should trigger discovery questions, not assumptions
**Check:** Mode should persist across follow-up questions in same conversation
**Works Best With:**
- **→ Task Management**: Requirements discovery → systematic implementation planning
- **→ Orchestration**: Requirements clarity → optimal tool selection for implementation
- **Manual Override**: Use `--brainstorm` to force discovery even for "clear" requirements
---
### 🔍 Introspection Mode - Meta-Cognitive Analysis
**Purpose**: Expose reasoning process for learning optimization and transparent decision-making.
**Auto-Activation Triggers:**
- Self-analysis requests: "analyze my reasoning", "reflect on decision"
- Error recovery scenarios and unexpected results requiring investigation
- Complex problem solving with multiple viable approaches
- Pattern recognition needs for optimization opportunities
- Manual flag: `--introspect`
**Behavioral Changes:**
- **Reasoning Transparency**: Exposes thinking process with clear markers (🤔, 🎯, ⚡, 📊, 💡)
- **Decision Analysis**: Evaluates choice logic and considers alternative approaches
- **Pattern Recognition**: Identifies recurring behaviors and improvement opportunities
- **Meta-Learning**: Extracts insights for continuous framework improvement
- **Framework Compliance**: Validates actions against SuperClaude principles and quality gates
**Example Experience:**
```
Standard Approach: "I'll analyze this code structure and suggest improvements..."
Introspective Approach:
"🧠 Meta-Analysis: Why did I choose structural analysis over functional flow?
🎯 Decision Logic: Saw class hierarchy → assumed OOP pattern dominance
🔄 Alternative Considered: Data flow analysis might reveal hidden dependencies
📊 Evidence Check: File imports suggest functional composition, not OOP
💡 Learning: Need to analyze imports before choosing analysis strategy
⚡ Correction: Switching to functional flow analysis approach"
```
**Works Best With:**
- **→ Task Management**: Provides transparent reasoning for complex phase decisions
- **Any Mode**: Adds reasoning transparency layer to any other mode's operation
- **Manual Override**: Use `--introspect` for learning sessions and debugging workflows
---
### 🔬 Deep Research Mode - Systematic Investigation Mindset
**Purpose**: Research mindset for systematic investigation and evidence-based reasoning.
**Auto-Activation Triggers:**
- `/sc:research` command invocation
- Research-related keywords: investigate, explore, discover, analyze
- Questions requiring current information beyond knowledge cutoff
- Complex research requirements
- Manual flag: `--research`
**Behavioral Modifications:**
- **Thinking Style**: Systematic over casual, evidence over assumption, progressive depth exploration
- **Communication**: Lead with confidence levels, provide inline citations, acknowledge uncertainties
- **Priority Shifts**: Completeness over speed, accuracy over speculation, verification over assumption
- **Process Adaptations**: Always create investigation plans, default to parallel operations, maintain evidence chains
**6-Phase Research Workflow:**
- 📋 **Understand** (5-10%): Assess query complexity and requirements
- 📝 **Plan** (10-15%): Select strategy (planning/intent/unified) and identify parallelization
- ✅ **TodoWrite** (5%): Create adaptive task hierarchy (3-15 tasks based on complexity)
- 🔄 **Execute** (50-60%): Parallel-first searches and smart extraction routing
- 📊 **Track** (Continuous): Monitor progress and update confidence scores
- ✓ **Validate** (10-15%): Verify evidence chains and ensure completeness
**Example Experience:**
```
Standard Mode: "Here are some search results about quantum computing..."
Deep Research Mode:
"📊 Research Plan: Quantum computing breakthroughs
✓ TodoWrite: Created 8 research tasks
🔄 Executing parallel searches across domains
📈 Confidence: 0.82 across 15 verified sources
📝 Report saved: claudedocs/research_quantum_[timestamp].md"
```
#### Quality Standards
- [ ] Minimum 2 sources per claim with inline citations
- [ ] Confidence scoring (0.0-1.0) for all findings
- [ ] Parallel execution by default for independent operations
- [ ] Reports saved to claudedocs/ with proper structure
- [ ] Clear methodology and evidence presentation
**Verify:** `/sc:research "test topic"` should create TodoWrite and execute systematically
**Test:** All research should include confidence scores and citations
**Check:** Reports should be saved to claudedocs/ automatically
**Works Best With:**
- **→ Task Management**: Research planning with TodoWrite integration
- **→ Orchestration**: Parallel Tavily/Playwright coordination
- **Manual Override**: Use `--depth` and `--strategy` for fine control
---
### 📋 Task Management Mode - Complex Coordination
**Purpose**: Hierarchical task organization with session persistence for multi-step operations.
**Auto-Activation Triggers:**
- Operations requiring >3 coordinated steps
- Multiple file/directory scope (>2 directories OR >3 files)
- Complex dependencies requiring phases and checkpoints
- Quality improvement requests: polish, refine, enhance
- Manual flags: `--task-manage`, `--delegate`
**Behavioral Changes:**
- **Hierarchical Planning**: Breaks complex work into Plan → Phase → Task → Todo structure
- **Session Persistence**: Maintains project context and progress across interruptions
- **Memory Integration**: Uses write_memory/read_memory for state preservation
- **Progress Orchestration**: Coordinates TodoWrite with memory updates for tracking
- **Quality Gates**: Implements systematic validation checkpoints between phases
**Example Experience:**
```
Standard Approach: "I'll implement user authentication..." → Direct implementation
Task Management Approach:
"📋 Multi-Phase Implementation Plan:
🎯 Phase 1: Security Requirements Analysis (Session 1)
🎯 Phase 2: API Design & Documentation (Session 2)
🎯 Phase 3: Implementation & Testing (Session 3-4)
🎯 Phase 4: Integration & Validation (Session 5)
💾 Session persistence: Resume context automatically
✓ Quality gates: Validation before each phase transition"
```
**Works Best With:**
- **Brainstorming →**: Requirements discovery then systematic implementation
- **+ Orchestration**: Task coordination with optimal tool selection
- **+ Introspection**: Transparent reasoning for complex phase decisions
---
### 🎯 Orchestration Mode - Intelligent Tool Selection
**Purpose**: Optimize task execution through intelligent tool routing and parallel coordination.
**Auto-Activation Triggers:**
- Multi-tool operations requiring sophisticated coordination
- Performance constraints (high resource usage)
- Parallel execution opportunities (>3 independent files/operations)
- Complex routing decisions with multiple valid tool approaches
**Behavioral Changes:**
- **Intelligent Tool Routing**: Selects optimal MCP servers and native tools for each task type
- **Resource Awareness**: Adapts approach based on system constraints and availability
- **Parallel Optimization**: Identifies independent operations for concurrent execution
- **Coordination Focus**: Optimizes tool selection and usage through coordinated execution
- **Adaptive Fallback**: Switches tools gracefully when preferred options are unavailable
**Example Experience:**
```
Standard Approach: Sequential file-by-file analysis and editing
Orchestration Approach:
"🎯 Multi-Tool Coordination Strategy:
🔍 Phase 1: Serena (semantic analysis) + Sequential (architecture review)
⚡ Phase 2: Morphllm (pattern edits) + Magic (UI components)
🧪 Phase 3: Playwright (testing) + Context7 (documentation patterns)
🔄 Parallel execution: 3 tools working simultaneously
\"
```
**Works Best With:**
- **Task Management →**: Provides tool coordination for complex multi-phase plans
- **+ Token Efficiency**: Optimal tool selection with compressed communication
- **Any Complex Task**: Adds intelligent tool routing to enhance execution
---
### ⚡ Token Efficiency Mode - Compressed Communication
**Purpose**: Achieve estimated 30-50% token reduction through symbol systems while preserving information quality.
**Auto-Activation Triggers:**
- High context usage approaching limits
- Large-scale operations requiring resource efficiency
- User explicit flags: `--uc`, `--ultracompressed`
- Complex analysis workflows with multiple outputs
**Behavioral Changes:**
- **Symbol Communication**: Uses visual symbols for logic flows, status, and technical domains
- **Technical Abbreviation**: Context-aware compression for repeated technical terms
- **Structured Density**: Bullet points, tables, and concise formatting over verbose paragraphs
- **Information Preservation**: Maintains ≥95% information quality despite compression
- **Structured Format**: Organized for clarity and task completion
**Example Experience:**
```
Standard Approach: "The authentication system implementation shows a security vulnerability in the user validation function that needs immediate attention..."
Token Efficient Approach:
"🛡️ Security Alert:
auth.js:45 → user val() → critical vuln
📊 Impact: ❌ token bypass possible
⚡ Action: fix validation + audit ∵ high sev
🔧 Est: 2h impl + 1h test"
```
**Works Best With:**
- **Any Mode**: Adds compression layer while preserving mode-specific behaviors
- **Orchestration →**: Compressed tool coordination and status updates
- **Manual Override**: Use `--uc` when context pressure or efficiency is priority
---
### 🎨 Standard Mode - Balanced Default
**Purpose**: Provide clear, professional communication for straightforward development tasks.
**Auto-Activation Triggers:**
- Simple, well-defined tasks without complexity indicators
- Single-file operations with clear requirements
- Basic explanations and standard development workflows
- No other mode triggers detected (default fallback)
**Behavioral Changes:**
- **Professional Communication**: Clear, concise technical language without compression
- **Moderate Detail**: Balanced information depth suitable for most development tasks
- **Standard Tool Selection**: Uses native Claude capabilities and basic tools
- **Quality Focus**: Maintains code quality without complex orchestration overhead
- **Responsive Adaptation**: Ready to switch to specialized modes when complexity increases
**Example Experience:**
```
Standard Approach: Consistent, professional baseline for all tasks
"I'll implement the login function with proper error handling:
1. Validate user input (email format, password requirements)
2. Authenticate against database with secure hashing
3. Generate JWT token with appropriate expiration
4. Return success response with user data
The implementation will follow security best practices and include comprehensive error handling."
```
**Works Best With:**
- **→ Any Mode**: Serves as baseline that other modes enhance
- **Mode Switching**: Automatically escalates to specialized modes when needed
- **Clarity Priority**: When straightforward communication is more important than optimization
---
## Advanced Usage
### Mode Combinations
**Multi-Mode Workflows:**
```bash
# Discovery → Planning → Implementation
/sc:brainstorm "microservices architecture" --task-manage
# → Brainstorming: requirement discovery
# → Task Management: multi-phase coordination
# Analysis with transparency and efficiency
/sc:analyze legacy-system/ --introspect --uc
# → Introspection: transparent reasoning
# → Token Efficiency: compressed output
```
### Manual Mode Control
**Force Specific Behaviors:**
- `--brainstorm`: Force collaborative discovery for any task
- `--introspect`: Add reasoning transparency to any mode
- `--task-manage`: Enable hierarchical coordination
- `--orchestrate`: Optimize tool selection and parallel execution
- `--uc`: Compress communication for efficiency
**Override Examples:**
```bash
# Force brainstorming on "clear" requirements
/sc:implement "user login" --brainstorm
# Add reasoning transparency to debugging
# Debug authentication issue with transparent reasoning
# Enable task management for simple operations
# Update styles.css with systematic task management
```
### Mode Boundaries and Priority
**When Modes Activate:**
1. **Complexity Threshold**: >3 files → Task Management
2. **Resource Pressure**: High context usage → Token Efficiency
3. **Multi-Tool Need**: Complex analysis → Orchestration
4. **Uncertainty**: Vague requirements → Brainstorming
5. **Error Recovery**: Problems → Introspection
**Priority Rules:**
- **Safety First**: Quality and validation always override efficiency
- **User Intent**: Manual flags override automatic detection
- **Context Adaptation**: Modes stack based on complexity
- **Resource Management**: Efficiency modes activate under pressure
---
## Real-World Examples
### Complete Workflow Examples
**New Project Development:**
```bash
# Phase 1: Discovery (Brainstorming Mode auto-activates)
"I want to build a productivity app"
→ 🤔 Socratic questions about users, features, platform choice
→ 📝 Structured requirements brief
# Phase 2: Planning (Task Management Mode auto-activates)
/sc:implement "core productivity features"
→ 📋 Multi-phase breakdown with dependencies
→ 🎯 Phase coordination with quality gates
# Phase 3: Implementation (Orchestration Mode coordinates tools)
/sc:implement "frontend and backend systems"
→ 🎯 Magic (UI) + Context7 (patterns) + Sequential (architecture)
→ ⚡ Parallel execution optimization
```
**Debugging Complex Issues:**
```bash
# Problem analysis (Introspection Mode auto-activates)
"Users getting intermittent auth failures"
→ 🤔 Transparent reasoning about potential causes
→ 🎯 Hypothesis formation and evidence gathering
→ 💡 Pattern recognition across similar issues
# Systematic resolution (Task Management coordinates)
# Fix authentication system comprehensively
→ 📋 Phase 1: Root cause analysis
→ 📋 Phase 2: Solution implementation
→ 📋 Phase 3: Testing and validation
```
### Mode Combination Patterns
**High-Complexity Scenarios:**
```bash
# Large refactoring with multiple constraints
/sc:improve legacy-system/ --introspect --uc --orchestrate
→ 🔍 Transparent reasoning (Introspection)
→ ⚡ Compressed communication (Token Efficiency)
→ 🎯 Optimal tool coordination (Orchestration)
→ 📋 Systematic phases (Task Management auto-activates)
```
---
## Quick Reference
### Mode Activation Patterns
| Trigger Type | Example Input | Mode Activated | Key Behavior |
|--------------|---------------|----------------|--------------|
| **Vague Request** | "I want to build an app" | 🧠 Brainstorming | Socratic discovery questions |
| **Complex Scope** | >3 files or >2 directories | 📋 Task Management | Phase coordination |
| **Multi-Tool Need** | Analysis + Implementation | 🎯 Orchestration | Tool optimization |
| **Error Recovery** | "This isn't working as expected" | 🔍 Introspection | Transparent reasoning |
| **Resource Pressure** | High context usage | ⚡ Token Efficiency | Symbol compression |
| **Simple Task** | "Fix this function" | 🎨 Standard | Clear, direct approach |
### Manual Override Commands
```bash
# Force specific mode behaviors
/sc:command --brainstorm # Collaborative discovery
/sc:command --introspect # Reasoning transparency
/sc:command --task-manage # Hierarchical coordination
/sc:command --orchestrate # Tool optimization
/sc:command --uc # Token compression
# Combine multiple modes
/sc:command --introspect --uc # Transparent + efficient
/sc:command --task-manage --orchestrate # Coordinated + optimized
```
---
## Troubleshooting
For troubleshooting help, see:
- [Common Issues](../reference/common-issues.md) - Quick fixes for frequent problems
- [Troubleshooting Guide](../reference/troubleshooting.md) - Comprehensive problem resolution
### Common Issues
- **Mode not activating**: Use manual flags: `--brainstorm`, `--introspect`, `--uc`
- **Wrong mode active**: Check complexity triggers and keywords in request
- **Mode switching unexpectedly**: Normal behavior based on task evolution
- **Execution impact**: Modes optimize tool usage, shouldn't affect execution
- **Mode conflicts**: Check flag priority rules in [Flags Guide](flags.md)
### Immediate Fixes
- **Force specific mode**: Use explicit flags like `--brainstorm` or `--task-manage`
- **Reset mode behavior**: Restart Claude Code session to reset mode state
- **Check mode indicators**: Look for 🤔, 🎯, 📋 symbols in responses
- **Verify complexity**: Simple tasks use Standard mode, complex tasks auto-switch
### Mode-Specific Troubleshooting
**Brainstorming Mode Issues:**
```bash
# Problem: Mode gives solutions instead of asking questions
# Quick Fix: Check request clarity and use explicit flag
/sc:brainstorm "web app" --brainstorm # Force discovery mode
"I have a vague idea about..." # Use uncertainty language
"Maybe we could build..." # Trigger exploration
```
**Task Management Mode Issues:**
```bash
# Problem: Simple tasks getting complex coordination
# Quick Fix: Reduce scope or use simpler commands
/sc:implement "function" --no-task-manage # Disable coordination
/sc:troubleshoot bug.js # Use basic commands
# Check if task really is complex (>3 files, >2 directories)
```
**Token Efficiency Mode Issues:**
```bash
# Problem: Output too compressed or unclear
# Quick Fix: Disable compression for clarity
/sc:command --no-uc # Disable compression
/sc:command --verbose # Force detailed output
# Use when clarity is more important than efficiency
```
**Introspection Mode Issues:**
```bash
# Problem: Too much meta-commentary, not enough action
# Quick Fix: Disable introspection for direct work
/sc:command --no-introspect # Direct execution
# Use introspection only for learning and debugging
```
**Orchestration Mode Issues:**
```bash
# Problem: Tool coordination causing confusion
# Quick Fix: Simplify tool usage
/sc:command --no-mcp # Native tools only
/sc:command --simple # Basic execution
# Check if task complexity justifies orchestration
```
### Error Code Reference
| Mode Error | Meaning | Quick Fix |
|------------|---------|-----------|
| **B001** | Brainstorming failed to activate | Use explicit `--brainstorm` flag |
| **T001** | Task management overhead | Use `--no-task-manage` for simple tasks |
| **U001** | Token efficiency too aggressive | Use `--verbose` or `--no-uc` |
| **I001** | Introspection mode stuck | Use `--no-introspect` for direct action |
| **O001** | Orchestration coordination failed | Use `--no-mcp` or `--simple` |
| **M001** | Mode conflict detected | Check flag priority rules |
| **M002** | Mode switching loop | Restart session to reset state |
| **M003** | Mode not recognized | Update SuperClaude or check spelling |
### Progressive Support Levels
**Level 1: Quick Fix (< 2 min)**
- Use manual flags to override automatic mode selection
- Check if task complexity matches expected mode behavior
- Try restarting Claude Code session
**Level 2: Detailed Help (5-15 min)**
```bash
# Mode-specific diagnostics
/sc:help modes # List all available modes
/sc:reflect --type mode-status # Check current mode state
# Review request complexity and triggers
```
- See [Common Issues Guide](../reference/common-issues.md) for mode installation problems
**Level 3: Expert Support (30+ min)**
```bash
# Deep mode analysis
SuperClaude install --diagnose
# Check mode activation patterns
# Review behavioral triggers and thresholds
```
- See [Diagnostic Reference Guide](../reference/diagnostic-reference.md) for behavioral mode analysis
**Level 4: Community Support**
- Report mode issues at [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
- Include examples of unexpected mode behavior
- Describe desired vs actual mode activation
### Success Validation
After applying mode fixes, test with:
- [ ] Simple requests use Standard mode (clear, direct responses)
- [ ] Complex requests auto-activate appropriate modes (coordination, reasoning)
- [ ] Manual flags override automatic detection correctly
- [ ] Mode indicators (🤔, 🎯, 📋) appear when expected
- [ ] Performance remains good across different modes
## Quick Troubleshooting (Legacy)
- **Mode not activating** → Use manual flags: `--brainstorm`, `--introspect`, `--uc`
- **Wrong mode active** → Check complexity triggers and keywords in request
- **Mode switching unexpectedly** → Normal behavior based on task evolution
- **Execution impact** → Modes optimize tool usage, shouldn't affect execution
- **Mode conflicts** → Check flag priority rules in [Flags Guide](flags.md)
## Frequently Asked Questions
**Q: How do I know which mode is active?**
A: Look for these indicators in communication patterns:
- 🤔 Discovery questions → Brainstorming
- 🎯 Reasoning transparency → Introspection
- Phase breakdowns → Task Management
- Tool coordination → Orchestration
- Symbol compression → Token Efficiency
**Q: Can I force specific modes?**
A: Yes, use manual flags to override automatic detection:
```bash
/sc:command --brainstorm # Force discovery
/sc:command --introspect # Add transparency
/sc:command --task-manage # Enable coordination
/sc:command --uc # Compress output
```
**Q: Do modes affect execution?**
A: Modes optimize tool usage through coordination:
- **Token Efficiency**: 30-50% context reduction
- **Orchestration**: Parallel processing
- **Task Management**: Prevents rework through systematic planning
**Q: Can modes work together?**
A: Yes, modes are designed to complement each other:
- **Task Management** coordinates other modes
- **Token Efficiency** compresses any mode's output
- **Introspection** adds transparency to any workflow
---
## Summary
SuperClaude's 5 behavioral modes create an **intelligent adaptation system** that matches your needs automatically:
- **🧠 Brainstorming**: Transforms vague ideas into clear requirements
- **🔍 Introspection**: Provides transparent reasoning for learning and debugging
- **📋 Task Management**: Coordinates complex multi-step operations
- **🎯 Orchestration**: Optimizes tool selection and parallel execution
- **⚡ Token Efficiency**: Compresses communication while preserving clarity
- **🎨 Standard**: Maintains professional baseline for straightforward tasks
**The key insight**: You don't need to think about modes - they work transparently to enhance your development experience. Simply describe what you want to accomplish, and SuperClaude automatically adapts its approach to match your needs.
---
## Related Guides
**Learning Progression:**
**🌱 Essential (Week 1)**
- [Quick Start Guide](../getting-started/quick-start.md) - Mode activation examples
- [Commands Reference](commands.md) - Commands automatically activate modes
- [Installation Guide](../getting-started/installation.md) - Set up behavioral modes
**🌿 Intermediate (Week 2-3)**
- [Agents Guide](agents.md) - How modes coordinate with specialists
- [Flags Guide](flags.md) - Manual mode control and optimization
- [Examples Cookbook](../reference/examples-cookbook.md) - Mode patterns in practice
**🌲 Advanced (Month 2+)**
- [MCP Servers](mcp-servers.md) - Mode integration with enhanced capabilities
- [Session Management](session-management.md) - Task Management mode workflows
- [Getting Started](../getting-started/quick-start.md) - Mode usage patterns
**🔧 Expert**
- [Technical Architecture](../developer-guide/technical-architecture.md) - Mode implementation details
- [Contributing Code](../developer-guide/contributing-code.md) - Extend mode capabilities
**Mode-Specific Guides:**
- **Brainstorming**: [Requirements Discovery Patterns](../reference/examples-cookbook.md#requirements)
- **Task Management**: [Session Management Guide](session-management.md)
- **Orchestration**: [MCP Servers Guide](mcp-servers.md)
- **Token Efficiency**: [Command Fundamentals](commands.md#token-efficiency)

310
docs/user-guide/session-management.md Normal file
View File

@@ -0,0 +1,310 @@
# Session Management Guide
SuperClaude provides persistent session management through the Serena MCP server, enabling true context preservation across Claude Code conversations and long-term project continuity.
## Core Session Commands with Persistent Memory
### `/sc:load` - Context Loading with Persistent Memory
**Purpose**: Initialize session with project context and persistent memory from previous sessions
**MCP Integration**: Triggers Serena MCP to read stored project memories
**Syntax**: `/sc:load [project_path]`
**What Happens**:
- Serena MCP reads persistent memory files from previous sessions
- Project context is restored from stored memories
- Previous decisions, patterns, and progress are loaded
- Session state is initialized with historical context
**Use Cases**:
```bash
# Load existing project context from persistent memory
/sc:load src/
# Resume specific project work with full history
/sc:load "authentication-system"
# Initialize with codebase analysis and previous insights
/sc:load . --analyze
```
### `/sc:save` - Session Persistence to Memory
**Purpose**: Save current session state and decisions to persistent memory
**MCP Integration**: Triggers Serena MCP to write memory files
**Syntax**: `/sc:save "session_description"`
**What Happens**:
- Current context and decisions are written to Serena memory
- Project state and progress are persisted across conversations
- Key insights and patterns are stored for future sessions
- Session summary is created with timestamp for retrieval
**Use Cases**:
```bash
# Save completed feature work for future reference
/sc:save "user authentication implemented with JWT"
# Checkpoint during complex work
/sc:save "API design phase complete, ready for implementation"
# Store architectural decisions permanently
/sc:save "microservices architecture decided, service boundaries defined"
```
### `/sc:reflect` - Progress Assessment with Memory Context
**Purpose**: Analyze current progress against stored memories and validate session completeness
**MCP Integration**: Uses Serena MCP to compare current state against stored memories
**Syntax**: `/sc:reflect [--scope project|session]`
**What Happens**:
- Serena MCP reads previous memories and current context
- Progress is assessed against stored goals and milestones
- Gaps and next steps are identified using historical context
- Session completeness is validated against project memory
**Use Cases**:
```bash
# Assess project progress against stored milestones
/sc:reflect --scope project
# Validate current session completeness
/sc:reflect
# Check if ready to move to next phase based on memory
/sc:reflect --scope session
```
## Persistent Memory Architecture
### How Serena MCP Enables True Persistence
**Memory Storage**:
- Session contexts stored as structured memory files
- Project decisions and architectural patterns preserved permanently
- Code analysis results and insights retained across conversations
- Progress tracking and milestone data maintained long-term
**Cross-Session Continuity**:
- Previous session context automatically available in new conversations
- Decisions and rationale preserved and accessible across conversations
- Learning from past patterns and solutions maintained
- Consistent project understanding maintained indefinitely
**Memory Types**:
- **Project Memories**: Long-term project context and architecture
- **Session Memories**: Specific conversation outcomes and decisions
- **Pattern Memories**: Reusable solutions and architectural patterns
- **Progress Memories**: Milestone tracking and completion status
## Session Lifecycle Patterns with Persistence
### New Project Initialization
```bash
# 1. Start fresh project
/sc:brainstorm "e-commerce platform requirements"
# 2. Save initial decisions to persistent memory
/sc:save "project scope and requirements defined"
# 3. Begin implementation planning
/sc:workflow "user authentication system"
# 4. Save architectural decisions permanently
/sc:save "auth architecture: JWT + refresh tokens + rate limiting"
```
### Resuming Existing Work (Cross-Conversation)
```bash
# 1. Load previous context from persistent memory
/sc:load "e-commerce-project"
# 2. Assess current state against stored progress
/sc:reflect --scope project
# 3. Continue with next phase using stored context
/sc:implement "payment processing integration"
# 4. Save progress checkpoint to memory
/sc:save "payment system integrated with Stripe API"
```
### Long-Term Project Management
```bash
# Weekly checkpoint pattern with persistence
/sc:load project-name
/sc:reflect --scope project
# ... work on features ...
/sc:save "week N progress: features X, Y, Z completed"
# Phase completion pattern with memory
/sc:reflect --scope project
/sc:save "Phase 1 complete: core authentication and user management"
/sc:workflow "Phase 2: payment and order processing"
```
## Cross-Conversation Continuity
### Starting New Conversations with Persistence
When starting a new Claude Code conversation, the persistent memory system allows:
1. **Automatic Context Restoration**
```bash
/sc:load project-name
# Automatically restores all previous context, decisions, and progress
```
2. **Progress Continuation**
- Previous session decisions are immediately available
- Architectural patterns and code insights are preserved
- Project history and rationale are maintained
3. **Intelligent Context Building**
- Serena MCP provides relevant memories based on current work
- Past solutions and patterns inform new implementations
- Project evolution is tracked and understood
### Memory Optimization
**Effective Memory Usage**:
- Use descriptive, searchable memory names
- Include project phase and timestamp context
- Reference specific features or architectural decisions
- Make future retrieval intuitive
**Memory Content Strategy**:
- Store decisions and rationale, not just outcomes
- Include alternative approaches considered
- Document integration patterns and dependencies
- Preserve learning and insights for future reference
**Memory Lifecycle Management**:
- Regular cleanup of outdated memories
- Consolidation of related session memories
- Archiving of completed project phases
- Pruning of obsolete architectural decisions
## Best Practices for Persistent Sessions
### Session Start Protocol
1. Always begin with `/sc:load` for existing projects
2. Use `/sc:reflect` to understand current state from memory
3. Plan work based on persistent context and stored patterns
4. Build on previous decisions and architectural choices
### Session End Protocol
1. Use `/sc:reflect` to assess completeness against stored goals
2. Save key decisions with `/sc:save` for future sessions
3. Document next steps and open questions in memory
4. Preserve context for seamless future continuation
### Memory Quality Maintenance
- Use clear, descriptive memory names for easy retrieval
- Include context about decisions and alternative approaches
- Reference specific code locations and patterns
- Maintain consistency in memory structure across sessions
## Integration with Other SuperClaude Features
### MCP Server Coordination
- **Serena MCP**: Provides the persistent memory infrastructure
- **Sequential MCP**: Uses stored memories for enhanced complex analysis
- **Context7 MCP**: References stored patterns and documentation approaches
- **Morphllm MCP**: Applies stored refactoring patterns consistently
### Agent Collaboration with Memory
- Agents access persistent memories for enhanced context
- Previous specialist decisions are preserved and referenced
- Cross-session agent coordination through shared memory
- Consistent specialist recommendations based on project history
### Command Integration with Persistence
- All `/sc:` commands can reference and build on persistent context
- Previous command outputs and decisions are available across sessions
- Workflow patterns are stored and reusable
- Implementation history guides future command decisions
## Troubleshooting Persistent Sessions
### Common Issues
**Memory Not Loading**:
- Verify Serena MCP is configured and running properly
- Check memory file permissions and accessibility
- Ensure consistent project naming conventions
- Validate memory file integrity and format
**Context Loss Between Sessions**:
- Always use `/sc:save` before ending sessions
- Use descriptive memory names for easy retrieval
- Regular `/sc:reflect` to validate memory completeness
- Backup important memory files periodically
**Memory Conflicts**:
- Use timestamped memory names for version control
- Regular cleanup of obsolete memories
- Clear separation between project and session memories
- Consistent memory naming conventions across sessions
### Quick Fixes
**Reset Session State**:
```bash
/sc:load --fresh # Start without previous context
/sc:reflect # Assess current state
```
**Memory Cleanup**:
```bash
/sc:reflect --cleanup # Remove obsolete memories
/sc:save --consolidate # Merge related memories
```
**Context Recovery**:
```bash
/sc:load --recent # Load most recent memories
/sc:reflect --repair # Identify and fix context gaps
```
## Advanced Persistent Session Patterns
### Multi-Phase Projects
- Use phase-specific memory naming for organization
- Maintain architectural decision continuity across phases
- Cross-phase dependency tracking through persistent memory
- Progressive complexity management with historical context
### Team Collaboration
- Shared memory conventions and naming standards
- Decision rationale preservation for team context
- Integration pattern documentation accessible to all team members
- Consistent code style and architecture enforcement through memory
### Long-Term Maintenance
- Memory archiving strategies for completed projects
- Pattern library development through accumulated memories
- Reusable solution documentation built over time
- Knowledge base building through persistent memory accumulation
## Key Benefits of Persistent Session Management
### Project Continuity
- Seamless work continuation across multiple conversations
- No context loss between Claude Code sessions
- Preserved architectural decisions and technical rationale
- Long-term project evolution tracking
### Enhanced Productivity
- Reduced need to re-explain project context
- Faster startup time for continued work
- Building on previous insights and patterns
- Cumulative project knowledge growth
### Quality Consistency
- Consistent architectural patterns across sessions
- Preserved code quality decisions and standards
- Reusable solutions and best practices
- Maintained technical debt awareness
---
**Key Takeaway**: Session management through Serena MCP transforms SuperClaude from single-conversation assistance to persistent project partnership, maintaining context, decisions, and learning across all development phases and Claude Code conversations.