diff --git a/Docs/agents-guide.md b/Docs/agents-guide.md deleted file mode 100644 index 118c1b6..0000000 --- a/Docs/agents-guide.md +++ /dev/null @@ -1,641 +0,0 @@ -# SuperClaude Agents Guide 🤖 - -## Overview - -SuperClaude V4 Beta features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents replace the previous persona system with more advanced, focused capabilities that provide expert-level assistance across all aspects of software development. - -**The simple truth**: You don't need to pick agents or memorize what they do. SuperClaude automatically brings in the right experts for each situation! - -**Here's what actually happens:** -- You type `/analyze auth.js` → Security auditor automatically jumps in 🛡️ -- You work on React components → Frontend specialist often takes over 🎨 -- You debug performance issues → Performance optimizer often helps ⚡ -- You write documentation → Technical writer usually helps out ✍️ - -**It's like having a smart team** that knows when to jump in and help, without you managing who does what. - -## 🚀 Just Try These (No Agent Knowledge Required) - -```bash -# These automatically activate the right experts: -/sc:analyze payment-system/ # → Security + backend experts auto-activate -/sc:build react-app/ # → Frontend specialist takes over -/sc:improve slow-queries.sql # → Performance optimizer jumps in -/sc:troubleshoot "auth failing" # → Root cause analyzer + security expert coordinate -/sc:brainstorm "task manager app" # → Brainstorm-PRD agent guides discovery -``` - -**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. - ---- - -## The SuperClaude Agent Team 👥 - -### Core Development Agents 🔧 - -#### 🐍 `python-ultimate-expert` - Master Python Architect -**What they do**: Production-ready Python development with SOLID principles, clean architecture, and comprehensive testing - -**Auto-activation triggers**: -- Python file detection (.py, requirements.txt, pyproject.toml) -- Keywords: "python", "django", "fastapi", "flask", "asyncio" -- Python-specific patterns and frameworks - -**Specialized capabilities**: -- **Production Standards**: SOLID principles, clean architecture, domain-driven design -- **Testing Excellence**: TDD with 95%+ coverage, pytest, property-based testing -- **Security First**: OWASP compliance, input validation, secrets management -- **Performance Optimization**: Profiling, async programming, memory management -- **Modern Tooling**: uv/poetry, black, ruff, mypy, pre-commit hooks - -**Example use cases**: -```bash -/sc:build python-api --focus security # → Production-ready FastAPI with security -/sc:improve legacy-python/ --focus quality # → Refactor to SOLID principles -/sc:test python-service/ --comprehensive # → Full test suite with coverage -``` - -**Integration with MCP servers**: -- **Context7**: Python framework documentation and best practices -- **Sequential**: Complex architecture analysis and system design -- **Magic**: Python web framework UI components - ---- - -#### ⚙️ `backend-engineer` - Reliable Systems Specialist -**What they do**: Server-side development, APIs, databases, and reliability engineering - -**Auto-activation triggers**: -- Keywords: "API", "database", "server", "microservices", "reliability" -- Backend file patterns (server.js, app.py, database schemas) -- Infrastructure and service-related tasks - -**Specialized capabilities**: -- **Reliability First**: 99.9% uptime targets, fault tolerance, graceful degradation -- **API Excellence**: RESTful design, GraphQL, comprehensive validation -- **Database Mastery**: Schema design, query optimization, ACID compliance -- **Security Implementation**: Authentication, authorization, zero trust architecture -- **Observable Systems**: Structured logging, monitoring, alerting - -**Quality standards**: -- Primary: 99.9% uptime with zero data loss tolerance -- Secondary: <200ms API response time, comprehensive error handling -- Success: Fault-tolerant systems meeting all reliability requirements - -**Example use cases**: -```bash -/sc:design user-management-api # → Reliable API with proper auth -/sc:optimize database-queries/ # → Performance tuning and indexing -/sc:implement payment-processing # → Secure, reliable payment system -``` - -**Integration with MCP servers**: -- **Context7**: Backend framework patterns and database documentation -- **Sequential**: System architecture analysis and reliability planning -- **Serena**: Cross-service dependency analysis and integration testing - ---- - -#### 🎨 `frontend-specialist` - Accessible UI Expert -**What they do**: User interface development with focus on accessibility, performance, and user experience - -**Auto-activation triggers**: -- Keywords: "component", "responsive", "accessibility", "UI", "UX", "react", "vue" -- Frontend file patterns (.jsx, .vue, .component.ts, CSS files) -- User interface and design-related tasks - -**Specialized capabilities**: -- **Accessibility by Default**: WCAG 2.1 AA compliance, screen reader support -- **Performance Budget**: Core Web Vitals optimization, bundle size management -- **Responsive Design**: Mobile-first approach, progressive enhancement -- **Modern Frameworks**: React, Vue, Angular with best practices -- **Design Systems**: Component libraries, design tokens, consistent patterns - -**Quality standards**: -- Primary: WCAG 2.1 AA compliance (100%) with Core Web Vitals in green zone -- Secondary: <3s load time on 3G networks, zero accessibility errors -- Success: Accessible, performant UI meeting all compliance standards - -**Example use cases**: -```bash -/sc:build dashboard-components/ # → Accessible React components -/sc:improve --focus accessibility ui/ # → WCAG compliance and optimization -/sc:optimize bundle-performance # → Core Web Vitals improvement -``` - -**Integration with MCP servers**: -- **Magic**: Advanced UI component generation and design system integration -- **Context7**: Frontend framework documentation and accessibility patterns -- **Playwright**: Cross-browser testing and visual regression detection - ---- - -#### 🚀 `devops-engineer` - Infrastructure Automation Expert -**What they do**: Infrastructure automation, deployment pipelines, monitoring, and reliability engineering - -**Auto-activation triggers**: -- Keywords: "deploy", "infrastructure", "CI/CD", "docker", "kubernetes", "monitoring" -- DevOps file patterns (Dockerfile, docker-compose.yml, .github/workflows) -- Infrastructure and deployment-related tasks - -**Specialized capabilities**: -- **Infrastructure as Code**: Terraform, CloudFormation, automated provisioning -- **CI/CD Excellence**: GitHub Actions, automated testing, deployment pipelines -- **Container Orchestration**: Docker, Kubernetes, microservices deployment -- **Monitoring & Observability**: Logging, metrics, alerting, performance tracking -- **Security Operations**: Security scanning, compliance, vulnerability management - -**Quality standards**: -- Primary: Zero-downtime deployments with automated rollback capability -- Secondary: Infrastructure as code, comprehensive monitoring coverage -- Success: Fully automated, observable, secure deployment infrastructure - -**Example use cases**: -```bash -/sc:deploy production-app # → Zero-downtime deployment pipeline -/sc:build monitoring-stack # → Comprehensive observability setup -/sc:secure infrastructure/ # → Security hardening and compliance -``` - -**Integration with MCP servers**: -- **Context7**: DevOps tools documentation and best practices -- **Sequential**: Infrastructure architecture analysis and optimization -- **Playwright**: Deployment validation and smoke testing - -### Analysis & Quality Agents 🔍 - -#### 🛡️ `security-auditor` - Threat Modeling Expert -**What they do**: Security vulnerability identification, threat modeling, and compliance verification - -**Auto-activation triggers**: -- Keywords: "security", "vulnerability", "auth", "compliance", "penetration", "audit" -- Security-sensitive code patterns (authentication, data handling, API endpoints) -- Security assessment and review requests - -**Specialized capabilities**: -- **Vulnerability Assessment**: OWASP Top 10, CWE compliance, penetration testing mindset -- **Threat Modeling**: Attack vector analysis, security risk assessment -- **Compliance Verification**: Industry standards, regulatory requirements -- **Security Architecture**: Zero trust principles, defense in depth -- **Remediation Guidance**: Specific fixes with security rationale - -**Quality standards**: -- Primary: Zero critical vulnerabilities in production with OWASP Top 10 compliance -- Secondary: All findings include remediation steps, clear severity classifications -- Success: Complete security assessment with actionable remediation plan - -**Example use cases**: -```bash -/sc:scan --focus security auth-system/ # → Comprehensive security audit -/sc:analyze payment-flow --security # → Threat modeling and risk assessment -/sc:improve --fix vulnerabilities api/ # → Security hardening and fixes -``` - -**Integration with MCP servers**: -- **Context7**: Security framework documentation and compliance standards -- **Sequential**: Complex threat modeling and vulnerability chain analysis -- **Playwright**: Security testing and penetration validation - ---- - -#### ⚡ `performance-optimizer` - Bottleneck Detection Expert -**What they do**: Performance analysis, optimization, and bottleneck identification across all system layers - -**Auto-activation triggers**: -- Keywords: "performance", "optimization", "slow", "bottleneck", "latency", "memory" -- Performance-related issues and optimization requests -- System profiling and benchmarking tasks - -**Specialized capabilities**: -- **Bottleneck Identification**: Systematic performance profiling and analysis -- **Optimization Strategy**: Database queries, application code, infrastructure tuning -- **Performance Monitoring**: Metrics collection, alerting, continuous optimization -- **Load Testing**: Capacity planning, stress testing, scalability analysis -- **Resource Management**: Memory optimization, CPU utilization, I/O efficiency - -**Quality standards**: -- Primary: Measurable performance improvements with baseline metrics -- Secondary: Comprehensive profiling, optimization rationale documentation -- Success: Performance targets met with sustainable optimization strategies - -**Example use cases**: -```bash -/sc:analyze --focus performance slow-api/ # → Bottleneck identification and fixes -/sc:optimize database-queries/ # → Query performance tuning -/sc:benchmark application-performance # → Load testing and capacity planning -``` - -**Integration with MCP servers**: -- **Sequential**: Complex performance analysis and systematic optimization -- **Context7**: Performance optimization patterns and best practices -- **Playwright**: Performance testing and real-world load simulation - ---- - -#### 🔍 `root-cause-analyzer` - Systematic Investigation Expert -**What they do**: Debugging, root cause analysis, and evidence-based problem solving - -**Auto-activation triggers**: -- Keywords: "debug", "investigate", "troubleshoot", "root cause", "analyze", "broken" -- Bug reports, system failures, and complex problem investigation -- Unknown system behavior and mysterious issues - -**Specialized capabilities**: -- **Systematic Investigation**: Evidence collection, hypothesis testing, pattern analysis -- **Debug Methodology**: Step-by-step problem isolation and reproduction -- **Root Cause Identification**: Deep analysis beyond surface symptoms -- **Solution Validation**: Testing fixes and preventing regression -- **Knowledge Transfer**: Documenting findings and prevention strategies - -**Quality standards**: -- Primary: Evidence-based conclusions with reproducible findings -- Secondary: Systematic investigation methodology, complete analysis -- Success: Root cause identified with validated solution and prevention - -**Example use cases**: -```bash -/sc:troubleshoot "payment processing fails randomly" # → Systematic investigation -/sc:analyze mysterious-bug/ # → Evidence-based debugging -/sc:investigate system-outage-logs/ # → Root cause analysis -``` - -**Integration with MCP servers**: -- **Sequential**: Complex problem decomposition and systematic analysis -- **Serena**: Code analysis and symbol-level investigation -- **Context7**: Debugging patterns and troubleshooting methodologies - ---- - -#### 🧪 `qa-specialist` - Quality Assurance Expert -**What they do**: Testing strategy, quality gates, edge case detection, and comprehensive validation - -**Auto-activation triggers**: -- Keywords: "test", "quality", "validation", "QA", "edge case", "coverage" -- Testing-related tasks and quality assurance requests -- Quality gate implementation and validation processes - -**Specialized capabilities**: -- **Testing Strategy**: Comprehensive test planning, risk-based testing -- **Quality Assurance**: Edge case identification, failure mode analysis -- **Test Automation**: Unit, integration, and end-to-end testing frameworks -- **Quality Gates**: Automated quality validation and compliance checking -- **Risk Assessment**: Quality risk analysis and mitigation strategies - -**Quality standards**: -- Primary: Comprehensive test coverage with edge case validation -- Secondary: Automated quality gates, risk-based testing priorities -- Success: Quality assurance processes preventing defects in production - -**Example use cases**: -```bash -/sc:test --comprehensive user-service/ # → Full testing strategy and implementation -/sc:validate --quality critical-features/ # → Quality gate implementation -/sc:analyze --focus testing legacy-code/ # → Testing strategy for existing code -``` - -**Integration with MCP servers**: -- **Playwright**: End-to-end testing and cross-browser validation -- **Sequential**: Complex testing strategy and quality analysis -- **Context7**: Testing framework documentation and QA best practices - -### Architecture & Code Quality Agents 🏗️ - -#### 🏗️ `system-architect` - Large-Scale Design Expert -**What they do**: System architecture, design patterns, and scalability planning - -**Auto-activation triggers**: -- Keywords: "architecture", "design", "scalability", "system", "patterns", "microservices" -- Large-scale system design and architectural decisions -- Cross-system integration and design pattern implementation - -**Specialized capabilities**: -- **System Architecture**: Large-scale system design, microservices architecture -- **Design Patterns**: Architectural patterns, design principle application -- **Scalability Planning**: Performance at scale, distributed system design -- **Integration Design**: Cross-system integration, API design, service mesh -- **Technology Strategy**: Technology selection, architectural decision records - -**Quality standards**: -- Primary: Scalable, maintainable architecture supporting business requirements -- Secondary: Design pattern adherence, comprehensive architectural documentation -- Success: Architecture enabling development team productivity and system reliability - -**Example use cases**: -```bash -/sc:design microservices-architecture # → System architecture and service design -/sc:analyze --focus architecture system/ # → Architectural review and improvement -/sc:plan scalability-improvements # → Scaling strategy and implementation -``` - -**Integration with MCP servers**: -- **Sequential**: Complex architectural analysis and design validation -- **Context7**: Architectural patterns and framework documentation -- **Serena**: Cross-system analysis and dependency management - ---- - -#### 🔄 `code-refactorer` - Clean Code Specialist -**What they do**: Code quality improvement, technical debt management, and clean code practices - -**Auto-activation triggers**: -- Keywords: "refactor", "cleanup", "quality", "technical debt", "maintainability" -- Code improvement and cleanup requests -- Legacy code modernization and quality enhancement - -**Specialized capabilities**: -- **Code Quality**: Clean code principles, SOLID design patterns -- **Refactoring Strategy**: Safe refactoring, incremental improvement -- **Technical Debt**: Debt identification, prioritization, systematic reduction -- **Design Patterns**: Pattern application, code structure improvement -- **Maintainability**: Code readability, documentation, consistency - -**Quality standards**: -- Primary: Improved code maintainability with reduced technical debt -- Secondary: Design pattern adherence, comprehensive test coverage -- Success: Clean, maintainable code supporting long-term development productivity - -**Example use cases**: -```bash -/sc:improve --focus quality legacy-module/ # → Comprehensive code quality improvement -/sc:refactor --safe complex-functions/ # → Safe refactoring with test coverage -/sc:cleanup --technical-debt codebase/ # → Systematic technical debt reduction -``` - -**Integration with MCP servers**: -- **Morphllm**: Pattern-based code transformations and intelligent refactoring -- **Serena**: Symbol-level analysis and large-scale refactoring coordination -- **Sequential**: Complex refactoring strategy and impact analysis - -### Communication & Knowledge Agents 📚 - -#### ✍️ `technical-writer` - Documentation Excellence Expert -**What they do**: Technical documentation, API references, user guides, and knowledge management - -**Auto-activation triggers**: -- Keywords: "document", "README", "guide", "documentation", "API docs", "tutorial" -- Documentation creation and improvement requests -- Knowledge transfer and educational content needs - -**Specialized capabilities**: -- **Technical Documentation**: API documentation, user guides, technical specifications -- **Audience Analysis**: Content tailored to different technical expertise levels -- **Information Architecture**: Structured, navigable documentation systems -- **Accessibility**: WCAG compliant documentation, inclusive design principles -- **Content Strategy**: Documentation planning, maintenance, and lifecycle management - -**Quality standards**: -- Primary: Flesch Reading Score 60-70 with zero ambiguity in instructions -- Secondary: WCAG 2.1 AA compliance, complete working code examples -- Success: Documentation enabling successful task completion without external assistance - -**Example use cases**: -```bash -/sc:document api-endpoints/ # → Comprehensive API documentation -/sc:write user-guide --audience beginner # → User-friendly tutorial and guides -/sc:improve --docs project-documentation/ # → Documentation quality enhancement -``` - -**Integration with MCP servers**: -- **Context7**: Documentation patterns and technical writing best practices -- **Serena**: Documentation persistence and cross-reference management -- **Sequential**: Complex documentation planning and content strategy - ---- - -#### 👨‍🏫 `code-educator` - Learning & Mentorship Expert -**What they do**: Code explanation, educational content, and knowledge transfer facilitation - -**Auto-activation triggers**: -- Keywords: "explain", "learn", "understand", "teach", "tutorial", "example" -- Educational content and learning-focused requests -- Code explanation and mentorship needs - -**Specialized capabilities**: -- **Educational Content**: Clear, progressive learning materials and tutorials -- **Code Explanation**: Complex concept breakdown with practical examples -- **Mentorship**: Guided learning experiences and skill development -- **Knowledge Transfer**: Best practices education and team learning facilitation -- **Interactive Learning**: Hands-on examples and practical exercises - -**Quality standards**: -- Primary: Clear, progressive learning experiences appropriate to audience level -- Secondary: Comprehensive examples, practical exercises, concept reinforcement -- Success: Learners successfully apply concepts and develop practical skills - -**Example use cases**: -```bash -/sc:explain complex-algorithm --educational # → Step-by-step learning guide -/sc:teach react-patterns --beginner # → Progressive React tutorial -/sc:mentor junior-developer --focus testing # → Personalized learning guidance -``` - -**Integration with MCP servers**: -- **Context7**: Educational resources and learning materials -- **Sequential**: Complex concept breakdown and progressive learning design -- **Magic**: Interactive examples and educational component creation - -### Special Purpose Agents 🎯 - -#### 🧠 `brainstorm-PRD` - Requirements Discovery Expert -**What they do**: Transform ambiguous project ideas into concrete specifications through structured brainstorming - -**Auto-activation triggers**: -- Ambiguous project requests ("I want to build something that...") -- Exploration keywords: brainstorm, explore, discuss, figure out, not sure -- PRD creation and requirements discovery needs -- `/sc:brainstorm` command usage - -**Specialized capabilities**: -- **Requirements Discovery**: Socratic questioning, stakeholder analysis -- **PRD Creation**: Comprehensive product requirement documentation -- **Brainstorming Facilitation**: Creative exploration with practical constraints -- **Specification Development**: Abstract concepts to concrete requirements -- **Risk Assessment**: Early constraint and dependency identification - -**Quality standards**: -- Primary: Requirements are complete and unambiguous before project handoff -- Secondary: All stakeholder perspectives integrated, feasibility validated -- Success: Comprehensive PRD enabling downstream agent execution - -**Integration workflow**: -```bash -/sc:brainstorm "task management app" # → Interactive discovery session -# → Automatic handoff to brainstorm-PRD agent -# → PRD generation with structured requirements -# → Ready for /sc:workflow implementation -``` - -**Integration with MCP servers**: -- **Sequential**: Complex requirements analysis and systematic discovery -- **Context7**: Industry patterns and requirement frameworks -- **Serena**: Session persistence and cross-project learning - ---- - -## Agent Coordination & Integration 🤝 - -### Automatic Agent Collaboration - -Agents often work together automatically. Here are common collaboration patterns: - -#### **Multi-Domain Projects** -```bash -/sc:build full-stack-app/ -# Auto-coordinates: backend-engineer + frontend-specialist + system-architect -``` - -#### **Security-Focused Development** -```bash -/sc:analyze --focus security payment-system/ -# Auto-coordinates: security-auditor + backend-engineer + performance-optimizer -``` - -#### **Quality Improvement** -```bash -/sc:improve --focus quality legacy-codebase/ -# Auto-coordinates: code-refactorer + qa-specialist + system-architect -``` - -### Integration with MCP Servers - -Each agent leverages specific MCP servers for enhanced capabilities: - -- **Context7**: Documentation patterns, framework best practices, compliance standards -- **Sequential**: Complex analysis, systematic problem solving, architectural planning -- **Magic**: UI component generation, design system integration, modern frameworks -- **Playwright**: Cross-browser testing, visual validation, performance testing -- **Morphllm**: Intelligent code transformations, pattern application, optimization -- **Serena**: Memory operations, cross-reference management, symbol-level analysis - -### Integration with Commands and Modes - -Agents seamlessly integrate with SuperClaude's command system: - -```bash -# Commands automatically select appropriate agents -/sc:analyze → root-cause-analyzer or system-architect (context-dependent) -/sc:build → frontend-specialist, backend-engineer, or python-ultimate-expert -/sc:test → qa-specialist with domain-specific coordination -/sc:brainstorm → brainstorm-PRD for requirements discovery -/sc:document → technical-writer with audience-appropriate formatting -``` - -**Mode Integration**: -- **Brainstorming Mode**: Activates brainstorm-PRD for discovery sessions -- **Task Management Mode**: Coordinates multiple agents across complex workflows -- **Token Efficiency Mode**: Optimizes agent communication for resource constraints - -## Quick Reference 📋 - -### Agent Selection Cheat Sheet - -| Agent | Best For | Auto-Activates On | Example Use | -|-------|----------|-------------------|-------------| -| 🐍 python-ultimate-expert | Python development | .py files, Python frameworks | Production Python APIs | -| ⚙️ backend-engineer | Server-side systems | APIs, databases, services | Reliable backend systems | -| 🎨 frontend-specialist | User interfaces | UI components, accessibility | Accessible web interfaces | -| 🚀 devops-engineer | Infrastructure | CI/CD, deployment, monitoring | Deployment automation | -| 🛡️ security-auditor | Security analysis | Security keywords, auth code | Vulnerability assessment | -| ⚡ performance-optimizer | Performance tuning | "slow", "bottleneck", profiling | System optimization | -| 🔍 root-cause-analyzer | Problem solving | "debug", "investigate", bugs | Complex bug investigation | -| 🧪 qa-specialist | Quality assurance | Testing, validation, QA | Comprehensive test strategy | -| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design | -| 🔄 code-refactorer | Code improvement | Refactoring, cleanup, quality | Clean code practices | -| ✍️ technical-writer | Documentation | Documentation requests | API documentation | -| 👨‍🏫 code-educator | Learning & teaching | "explain", "learn", tutorials | Educational content | -| 🧠 brainstorm-PRD | Requirements discovery | Ambiguous projects, brainstorming | Project specification | - -### Most Useful Agent Combinations - -**Full-Stack Development**: -```bash -# Automatically coordinates backend + frontend + architecture -/sc:build modern-web-app/ -``` - -**Security & Performance Review**: -```bash -# Coordinates security + performance + quality analysis -/sc:analyze --comprehensive production-system/ -``` - -**Learning & Development**: -```bash -# Coordinates educator + technical writer + domain expert -/sc:explain complex-system --educational -``` - -**Project Discovery to Implementation**: -```bash -# Brainstorm → PRD → Architecture → Implementation -/sc:brainstorm "e-commerce platform" -# → Automatic handoff through agent coordination -``` - -## Best Practices 💡 - -### Getting Started (The Simple Way) -1. **Just use normal commands** - Agents auto-activate based on your needs -2. **Trust the automation** - SuperClaude usually picks better experts than manual selection -3. **Focus on your work** - Not on managing which agent helps you -4. **Let coordination happen** - Multiple agents work together automatically - -### Advanced Usage (When You Want Control) -1. **Manual agent selection** - Use agent names in commands when you want specific expertise -2. **Cross-domain perspectives** - Ask security agents about frontend code for different viewpoints -3. **Learning mode** - Use code-educator for explanation-focused assistance -4. **Quality focus** - Combine qa-specialist with domain experts for comprehensive quality - -### Common Patterns - -**For New Projects**: -```bash -/sc:brainstorm "your project idea" # → Requirements discovery -# → Automatic PRD generation and handoff -# → Ready for implementation workflow -``` - -**For Existing Code**: -```bash -/sc:analyze existing-system/ # → Appropriate domain expert auto-selected -/sc:improve --focus quality code/ # → Quality-focused agent coordination -/sc:secure legacy-application/ # → Security-focused analysis and hardening -``` - -**For Learning**: -```bash -/sc:explain complex-concept --educational # → Code educator with domain expert -/sc:document api/ --audience beginner # → Technical writer with appropriate level -``` - ---- - -## Final Notes 📝 - -**The real truth about agents** 💯: -- **Auto-activation works remarkably well** - Usually better than trying to pick experts yourself -- **You can completely ignore agent details** and still get excellent expert assistance -- **Agents exist to help you** - Not to create complexity you need to manage -- **Learning happens naturally** through use, not through studying agent descriptions - -**Don't feel overwhelmed by the team** 🧘‍♂️: -- You don't need to know what each agent does -- SuperClaude handles expert selection intelligently -- The detailed descriptions above are for curiosity, not necessity -- Focus on your work - the right experts will show up when needed - -**When you might want to know about agents**: -- **Curiosity** - "What would a security expert think about this frontend code?" -- **Learning** - "How would different experts approach this problem?" -- **Specialization** - "I specifically need Python architecture expertise" -- **Quality focus** - "I want comprehensive quality analysis from multiple angles" - -**Keep it simple** 🎯: -- Use normal commands like `/analyze some-code/` and `/build my-app/` -- Let the right experts automatically show up -- Agent coordination is available when you want it, not because you need it -- Focus on building great software - we'll handle the expertise coordination - ---- - -*Behind this sophisticated team of 13 specialists, SuperClaude remains simple to use. Just start coding and the right experts show up when needed! 🚀* \ No newline at end of file diff --git a/Docs/installation-guide.md b/Docs/installation-guide.md deleted file mode 100644 index 4b06a77..0000000 --- a/Docs/installation-guide.md +++ /dev/null @@ -1,631 +0,0 @@ -# SuperClaude V4 Beta Installation Guide 📦 - -## 🎯 It's Easier Than It Looks! - -**The honest truth**: This guide looks long because we want to cover all the details, but installation is actually pretty simple. Most people are done in 2 minutes with one command! - -### Step 1: Install the Package - -**Option A: From PyPI (Recommended)** -```bash -uv add SuperClaude -``` - -**Option B: From Source** -```bash -git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git -cd SuperClaude_Framework -uv sync -``` -### 🔧 UV / UVX Setup Guide - -SuperClaude V4 Beta supports installation via [`uv`](https://github.com/astral-sh/uv) (a faster, modern Python package manager) or `uvx` for cross-platform usage. - -### 🌀 Install with `uv` - -Make sure `uv` is installed: - -```bash -curl -Ls https://astral.sh/uv/install.sh | sh -``` - -> Or follow instructions from: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv) - -Once `uv` is available, you can install SuperClaude like this: - -```bash -uv venv -source .venv/bin/activate -uv pip install SuperClaude -``` - -### ⚡ Install with `uvx` (Cross-platform CLI) - -If you’re using `uvx`, just run: - -```bash -uvx pip install SuperClaude -``` -## 🔧 UV / UVX Setup Guide - -SuperClaude V4 Beta supports installation via [`uv`](https://github.com/astral-sh/uv) (a faster, modern Python package manager) or `uvx` for cross-platform usage. - -### 🌀 Install with `uv` - -Make sure `uv` is installed: - -```bash -curl -Ls https://astral.sh/uv/install.sh | sh -``` - -> Or follow instructions from: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv) - -Once `uv` is available, you can install SuperClaude like this: - -```bash -uv venv -source .venv/bin/activate -uv pip install SuperClaude -``` - -### ⚡ Install with `uvx` (Cross-platform CLI) - -If you’re using `uvx`, just run: - -```bash -uvx pip install SuperClaude -``` - -### ✅ Finish Installation - -After installing, continue with the usual installer step: - -```bash -python3 -m SuperClaude install -``` - -Or using bash-style CLI: - -```bash -SuperClaude install -``` - -### 🧠 Note: - -* `uv` provides better caching and performance. -* Compatible with Python 3.8+ and works smoothly with SuperClaude. - ---- - -### ⚠️ Important Note -**After installing the SuperClaude.** -**You can use `SuperClaude commands` -, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`** - -**What just happened?** SuperClaude tried to set up everything you need. Usually no complex configuration, dependency hunting, or setup headaches! 🎉 - ---- - -A comprehensive guide to installing SuperClaude V4 Beta. But remember - most people never need to read past the quick start above! 😊 - -## Before You Start 🔍 - -### What You Need 💻 - -SuperClaude works on **Windows**, **macOS**, and **Linux**. Here's what you need: - -**Required:** -- **Python 3.8 or newer** - The framework is written in Python -- **Claude CLI** - SuperClaude enhances Claude Code, so you need it installed first - -**Optional (but recommended):** -- **Node.js 16+** - Only needed if you want MCP server integration -- **Git** - Helpful for development workflows - -### Quick Check 🔍 - -Before installing, let's make sure you have the basics: - -```bash -# Check Python version (should be 3.8+) -python3 --version - -# Check if Claude CLI is installed -claude --version - -# Check Node.js (optional, for MCP servers) -node --version -``` - -If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below. - -## Quick Start 🚀 - -**🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)** -**Option A: From PyPI (Recommended)** -```bash -pip install SuperClaude - -# Install with recommended settings -SuperClaude install --quick - -# That's it! 🎉 -``` -**Option B: From Source** -```bash -# Clone the repo -git clone -cd SuperClaude -pip install . - -# Install with recommended settings -SuperClaude install --quick - -# That's it! 🎉 -``` -**⚠️ Important Note** -**After installing the SuperClaude.** -**You can use `SuperClaude commands` -, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`** - -**What you just got:** -- ✅ All 16 smart commands that auto-activate experts -- ✅ 13 specialized domain expert agents that know when to help -- ✅ Advanced session management with brainstorming mode -- ✅ Python hooks system for intelligent framework coordination -- ✅ Intelligent routing that figures out complexity for you -- ✅ About 2 minutes of your time and ~50MB disk space - -**Seriously, you're done.** Open Claude Code, type `/help`, and watch SuperClaude work its magic. - -**Nervous about what it will do?** See first with: -```bash -SuperClaude install --dry-run -``` - -## Installation Options 🎯 - -### 🎛️ Interactive Two-Stage Installation (Default) -```bash -SuperClaude install -``` -- **Stage 1**: Select MCP servers (Context7, Sequential, Magic, Playwright, etc.) -- **Stage 2**: Choose framework components (Core, Commands, Agents, Modes) -- **Time**: ~3-5 minutes depending on selections -- **Space**: ~50-100MB depending on selections -- **Good for**: All users - gives you full control over what gets installed -- **Interactive**: Shows detailed descriptions and lets you pick exactly what you want - -### 🎯 Component-Specific Installation -```bash -SuperClaude install --components core commands modes -``` -- **What**: Install only specific components you need -- **Time**: Variable based on selection -- **Space**: Variable based on selection -- **Good for**: Users who know exactly what they want -- **Available components**: core, commands, agents, modes, mcp, mcp_docs - -## Step-by-Step Installation 📋 - -### Prerequisites Setup 🛠️ - -**Missing Python?** -```bash -# Linux (Ubuntu/Debian) -sudo apt update && sudo apt install python3 python3-pip - -# macOS -brew install python3 - -# Windows -# Download from https://python.org/downloads/ -#or open command prompt or powershell -winget install python -``` - -**Missing Claude CLI?** -- Visit https://claude.ai/code for installation instructions -- SuperClaude enhances Claude Code, so you need it first - -**Missing Node.js? (Optional)** -```bash -# Linux (Ubuntu/Debian) -sudo apt update && sudo apt install nodejs npm - -# macOS -brew install node - -# Windows -# Download from https://nodejs.org/ -#or open command prompt or powershell -winget install nodejs -``` - -### Getting SuperClaude 📥 - -**Option 1: From PyPI (Recommended)** -```bash -pip install SuperClaude -``` - -**Option 2: Download the latest release** -```bash -# Download and extract the latest release -# (Replace URL with actual release URL) -curl -L -o superclaude-v3.zip -unzip superclaude-v3.zip -cd superclaude-v3 -pip install . -``` - -**Option 3: Clone from Git** -```bash -git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git -cd SuperClaude_Framework -pip install . -``` - -### Running the Installer 🎬 - -The installer is pretty smart and will guide you through the process: - -```bash -# See all available options -SuperClaude install --help - -# Interactive installation (recommended) -SuperClaude install - -# Want to see what would happen first? -SuperClaude install --dry-run - -# Install everything -SuperClaude install --components core commands agents modes mcp mcp_docs - -# Quiet installation (minimal output) -SuperClaude install --quiet - -# Force installation (skip confirmations) -python3 SuperClaude.py install --quick --force -``` - -### During Installation 📱 - -Here's what happens when you install: - -1. **System Check** - Verifies you have required dependencies -2. **Directory Setup** - Creates `~/.claude/` directory structure -3. **Core Files** - Copies framework documentation files -4. **Commands** - Installs slash command definitions (if selected) -5. **MCP Servers** - Downloads and configures MCP servers (if selected) -6. **Configuration** - Sets up framework settings and CLAUDE.md imports -7. **Settings** - Sets up `settings.json` with your preferences -8. **Validation** - Tests that everything works - -The installer shows progress and will tell you if anything goes wrong. - -## After Installation ✅ - -### Quick Test 🧪 - -Let's make sure everything worked: - -```bash -# Check if files were installed -ls ~/.claude/ - -# Should show: CLAUDE.md, COMMANDS.md, settings.json, etc. -``` - -**Test with Claude Code:** -1. Open Claude Code -2. Try typing `/help` - you should see SuperClaude commands -3. Try `/analyze --help` - should show command options - -### What Got Installed 📂 - -SuperClaude V4 Beta installs to `~/.claude/` by default. Here's what you'll find: - -``` -~/.claude/ -├── CLAUDE.md # Main framework entry point -├── FLAGS.md # Command flags and options -├── PRINCIPLES.md # Development principles -├── RULES.md # Operational rules -├── ORCHESTRATOR.md # Intelligent routing -├── MCP_*.md # MCP server configurations -├── MODE_*.md # Operational modes -├── SESSION_LIFECYCLE.md # Session management -├── settings.json # Configuration file -└── commands/ # Individual command definitions - ├── analyze.md - ├── build.md - ├── improve.md - └── ... (13 more) -``` - -**For Developer Installation (+Hooks System)**: -``` -~/.claude/ -├── [above files] # Core framework files -└── backups/ # Installation backups - ├── framework_coordinator/ - ├── session_lifecycle/ - ├── performance_monitor/ - ├── quality_gates/ - └── install_hooks.py # Hook installation script -``` - -**What each file does:** -- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files -- **settings.json** - Configuration (MCP servers, hooks, etc.) -- **commands/** - Detailed definitions for each slash command -- **hooks/** - Python hooks for advanced framework coordination (developer only) - -### First Steps 🎯 - -Try these commands to get started: - -```bash -# In Claude Code, try these: -/sc:help # See available commands -/sc:analyze README.md # Analyze a file -/sc:build --help # See build options -/sc:improve --help # See improvement options -/sc:brainstorm "my app idea" # Try V4 Beta brainstorming mode -``` - -**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want. - -### Installing Hooks System (V4 Beta) 🔗 - -If you want to add the Python hooks system to an existing installation: - -```bash -# Install hooks to existing SuperClaude installation -cd SuperClaude_Framework -python3 SuperClaude/Hooks/scripts/install_hooks.py - -# Or upgrade existing installation with hooks -SuperClaude install --upgrade --hooks -``` - -**What the hooks system provides:** -- **Framework Coordinator**: Intelligent MCP server suggestions -- **Session Lifecycle**: Automatic checkpoint triggers -- **Performance Monitor**: Real-time performance tracking (<100ms targets) -- **Quality Gates**: 8-step validation system - -**Verification:** -```bash -# Test hooks installation -python3 SuperClaude/Hooks/scripts/test_hooks.py - -# Check hook status -SuperClaude hooks --status -``` - -## Managing Your Installation 🛠️ - -### Updates 📅 - -Keep SuperClaude up to date: - -```bash -# Check for updates -SuperClaude update - -# Force update (overwrite local changes) -SuperClaude update --force - -# Update specific components only -SuperClaude update --components core,commands - -# See what would be updated -SuperClaude update --dry-run -``` - -**When to update:** -- When new SuperClaude versions are released -- If you're having issues (updates often include fixes) -- When new MCP servers become available - -### Backups 💾 - -Create backups before major changes: - -```bash -# Create a backup -SuperClaude backup --create - -# List existing backups -SuperClaude backup --list - -# Restore from backup -SuperClaude backup --restore - -# Create backup with custom name -SuperClaude backup --create --name "before-update" -``` - -**When to backup:** -- Before updating SuperClaude -- Before experimenting with settings -- Before uninstalling -- Periodically if you've customized heavily - -### Uninstallation 🗑️ - -If you need to remove SuperClaude: - -```bash -# Remove SuperClaude (keeps backups) -SuperClaude uninstall - -# Complete removal (removes everything) -SuperClaude uninstall --complete - -# See what would be removed -SuperClaude uninstall --dry-run -``` - -**What gets removed:** -- All files in `~/.claude/` -- MCP server configurations -- SuperClaude settings from Claude Code - -**What stays:** -- Your backups (unless you use `--complete`) -- Claude Code itself (SuperClaude doesn't touch it) -- Your projects and other files - -## Troubleshooting 🔧 - -### Common Issues 🚨 - -**"Python not found"** -```bash -# Try python instead of python3 -python --version - -# Or check if it's installed but not in PATH -which python3 -``` - -**"Claude CLI not found"** -- Make sure Claude Code is installed first -- Try `claude --version` to verify -- Visit https://claude.ai/code for installation help - -**"Permission denied"** -```bash -# Try with explicit Python path -/usr/bin/python3 SuperClaude.py install --quick - -# Or check if you need different permissions -ls -la ~/.claude/ -``` - -**"MCP servers won't install"** -- Check that Node.js is installed: `node --version` -- Check that npm is available: `npm --version` -- Try installing without MCP first: `--minimal` or `--quick` - -**"Installation fails partway through"** -```bash -# Try with verbose output to see what's happening -SuperClaude install --quick --verbose - -# Or try a dry run first -SuperClaude install --quick --dry-run -``` - -### Platform-Specific Issues 🖥️ - -**Windows:** -- Use `python` instead of `python3` if you get "command not found" -- Run Command Prompt as Administrator if you get permission errors -- Make sure Python is in your PATH - -**macOS:** -- You might need to approve SuperClaude in Security & Privacy settings -- Use `brew install python3` if you don't have Python 3.8+ -- Try using `python3` explicitly instead of `python` - -**Linux:** -- Make sure you have `python3-pip` installed -- You might need `sudo` for some package installations -- Check that `~/.local/bin` is in your PATH - -### Still Having Issues? 🤔 - -**Check our troubleshooting resources:** -- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues -- Look for existing issues similar to yours -- Create a new issue if you can't find a solution - -**When reporting bugs, please include:** -- Your operating system and version -- Python version (`python3 --version`) -- Claude CLI version (`claude --version`) -- The exact command you ran -- The complete error message -- What you expected to happen - -**Getting Help:** -- GitHub Discussions for general questions -- Check the README.md for latest updates -- Look at the ROADMAP.md to see if your issue is known - -## Advanced Options ⚙️ - -### Custom Installation Directory - -```bash -# Install to custom location -SuperClaude install --quick --install-dir /custom/path - -# Use environment variable -export SUPERCLAUDE_DIR=/custom/path -SuperClaude install --quick -``` - -### Component Selection - -```bash -# See available components -SuperClaude install --list-components - -# Install specific components only -SuperClaude install --components core,commands - -# Skip certain components -SuperClaude install --quick --skip mcp -``` - -### Development Setup - -If you're planning to contribute or modify SuperClaude: - -```bash -# Developer installation with all components -SuperClaude install --components core commands agents modes mcp mcp_docs - -# Install in development mode -SuperClaude install --dev-mode -``` - -## What's Next? 🚀 - -**Now that SuperClaude is installed (that was easy, right?):** - -1. **Just start using it** - Try `/analyze some-file.js` or `/build` and see what happens ✨ -2. **Don't stress about learning** - SuperClaude usually figures out what you need -3. **Experiment freely** - Commands like `/improve` and `/troubleshoot` are pretty forgiving -4. **Read guides if curious** - Check `Docs/` when you want to understand what just happened -5. **Give feedback** - Let us know what works and what doesn't - -**The real secret**: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯 - -**Still feeling uncertain?** Start with just `/help` and `/analyze README.md` - you'll see how non-intimidating it actually is. - ---- - -## Final Notes 📝 - -- **Installation takes 1-5 minutes** depending on what you choose -- **Disk space needed: 20-100MB** (not much!) -- **Works alongside existing tools** - doesn't interfere with your setup -- **Easy to uninstall** if you change your mind -- **Community supported** - we actually read and respond to issues -- ### ⚠️ Important Note -**After installing the SuperClaude.** -**You can use `SuperClaude commands` -, `python3 -m SuperClaude commands` or also `python3 SuperClaude commands`** - -Thanks for trying SuperClaude! We hope it makes your development workflow a bit smoother. 🙂 - ---- - -*Last updated: January 2025 (V4 Beta) - Let us know if anything in this guide is wrong or confusing!* diff --git a/Docs/personas-guide-v3-legacy.md b/Docs/personas-guide-v3-legacy.md deleted file mode 100644 index 737b4ee..0000000 --- a/Docs/personas-guide-v3-legacy.md +++ /dev/null @@ -1,871 +0,0 @@ -# SuperClaude Personas User Guide 🎭 - -## 🎭 Personas Auto-Activate - No Need to Choose! - -**The simple truth**: You don't need to pick personas or memorize what they do. SuperClaude usually tries to bring in helpful experts for each situation! - -**Here's what actually happens:** -- You type `/analyze auth.js` → Security expert usually jumps in 🛡️ -- You work on React components → Frontend specialist often takes over 🎨 -- You debug performance issues → Performance optimizer often helps ⚡ -- You write documentation → Professional writer usually helps out ✍️ - -**It's like having a smart team** that knows when to jump in and help, without you managing who does what. - -**Manual control available** when you want it (like asking specifically for a security review of frontend code), but most of the time you can just... let it work. 🪄 - ---- - -## 🚀 Just Try These (No Persona Knowledge Required) - -```bash -# These automatically activate the right experts: -/sc:analyze payment-system/ # → Security + backend experts auto-activate -/sc:build react-app/ # → Frontend specialist takes over -/sc:improve slow-queries.sql # → Performance optimizer jumps in -/sc:troubleshoot "auth failing" # → Debug specialist + security expert coordinate -``` - -**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. Everything below is for when you get curious about who's on the team. - ---- - -Think of SuperClaude personas as having a team of specialists on demand. Each persona brings different expertise, priorities, and perspectives to help you with specific types of work. - -## What Are Personas? 🤔 - -**Personas are AI specialists** that try to adapt SuperClaude's behavior for different types of work. Instead of generic responses, you often get expert-level help from relevant specialists. - -**How they actually work in practice:** -- **Auto-activation** - SuperClaude usually tries to pick helpful experts (most of the time this works pretty well!) -- **Smart detection** - Recognizes security work, frontend tasks, performance issues, etc. -- **Seamless switching** - Different experts jump in as needed within the same conversation -- **Team coordination** - Multiple experts often coordinate on complex tasks -- **Manual override available** - You can explicitly choose with `--persona-name` flags when you want a different perspective - -**Why this matters:** -- Often get expert-level advice without knowing which expert to ask -- Usually get better decision-making aligned with what you're actually working on -- More focused and relevant responses based on the task -- Access to specialized workflows that activate when useful - -**The neat part**: You just work on your stuff, and helpful experts usually show up when needed. 🎯 - -## The SuperClaude Team 👥 - -### Technical Specialists 🔧 - -#### 🏗️ `architect` - Systems Design Specialist -**What they do**: Long-term architecture planning, system design, scalability decisions - -**Priority**: Long-term maintainability > scalability > performance > quick fixes - -**When they auto-activate**: -- Keywords: "architecture", "design", "scalability", "system structure" -- Complex system modifications involving multiple modules -- Planning large features or system changes - -**Great for**: -- Planning new systems or major features -- Architectural reviews and improvements -- Technical debt assessment -- Design pattern recommendations -- Scalability planning - -**Example workflows**: -```bash -/sc:design microservices-migration --persona-architect -/sc:analyze --focus architecture large-system/ -/sc:estimate "redesign auth system" --persona-architect -``` - -**What they prioritize**: -- Maintainable, understandable code -- Loose coupling, high cohesion -- Future-proof design decisions -- Clear separation of concerns - ---- - -#### 🎨 `frontend` - UI/UX & Accessibility Expert -**What they do**: User experience, accessibility, frontend performance, design systems - -**Priority**: User needs > accessibility > performance > technical elegance - -**When they auto-activate**: -- Keywords: "component", "responsive", "accessibility", "UI", "UX" -- Frontend development work -- User interface related tasks - -**Great for**: -- Building UI components -- Accessibility compliance (WCAG 2.1 AA) -- Frontend performance optimization -- Design system work -- User experience improvements - -**Performance budgets they enforce**: -- Load time: <3s on 3G, <1s on WiFi -- Bundle size: <500KB initial, <2MB total -- Accessibility: WCAG compliance target - -**Example workflows**: -```bash -/sc:build dashboard --persona-frontend -/sc:improve --focus accessibility components/ -/sc:analyze --persona-frontend --focus performance -``` - -**What they prioritize**: -- Intuitive, user-friendly interfaces -- Accessibility for all users -- Real-world performance on mobile/3G -- Clean, maintainable CSS/JS - ---- - -#### ⚙️ `backend` - API & Infrastructure Specialist -**What they do**: Server-side development, APIs, databases, reliability engineering - -**Priority**: Reliability > security > performance > features > convenience - -**When they auto-activate**: -- Keywords: "API", "database", "service", "server", "reliability" -- Backend development work -- Infrastructure or data-related tasks - -**Great for**: -- API design and implementation -- Database schema and optimization -- Security implementation -- Reliability and error handling -- Backend performance tuning - -**Reliability budgets they enforce**: -- Uptime: 99.9% (8.7h/year downtime) -- Error rate: <0.1% for critical operations -- API response time: <200ms -- Recovery time: <5 minutes for critical services - -**Example workflows**: -```bash -/sc:design user-api --persona-backend -/sc:analyze --focus security api/ -/sc:improve --persona-backend database-layer/ -``` - -**What they prioritize**: -- Rock-solid reliability and uptime -- Security by default (zero trust) -- Data integrity and consistency -- Graceful error handling - ---- - -#### 🛡️ `security` - Threat Modeling & Vulnerability Expert -**What they do**: Security analysis, threat modeling, vulnerability assessment, compliance - -**Priority**: Security > compliance > reliability > performance > convenience - -**When they auto-activate**: -- Keywords: "security", "vulnerability", "auth", "compliance" -- Security scanning or assessment work -- Authentication/authorization tasks - -**Great for**: -- Security audits and vulnerability scanning -- Threat modeling and risk assessment -- Secure coding practices -- Compliance requirements (OWASP, etc.) -- Authentication and authorization systems - -**Threat assessment levels**: -- Critical: Immediate action required -- High: Fix within 24 hours -- Medium: Fix within 7 days -- Low: Fix within 30 days - -**Example workflows**: -```bash -/sc:scan --persona-security --focus security -/sc:analyze auth-system/ --persona-security -/sc:improve --focus security --persona-security -``` - -**What they prioritize**: -- Security by default, fail-safe mechanisms -- Zero trust architecture principles -- Defense in depth strategies -- Clear security documentation - ---- - -#### ⚡ `performance` - Optimization & Bottleneck Specialist -**What they do**: Performance optimization, bottleneck identification, metrics analysis - -**Priority**: Measure first > optimize critical path > user experience > avoid premature optimization - -**When they auto-activate**: -- Keywords: "performance", "optimization", "speed", "bottleneck" -- Performance analysis or optimization work -- When speed/efficiency is mentioned - -**Great for**: -- Performance bottleneck identification -- Code optimization with metrics validation -- Database query optimization -- Frontend performance tuning -- Load testing and capacity planning - -**Performance budgets they track**: -- API responses: <500ms -- Database queries: <100ms -- Bundle size: <500KB initial -- Memory usage: <100MB mobile, <500MB desktop - -**Example workflows**: -```bash -/sc:analyze --focus performance --persona-performance -/sc:improve --type performance slow-endpoints/ -/sc:test --benchmark --persona-performance -``` - -**What they prioritize**: -- Measurement-driven optimization -- Real user experience improvements -- Critical path performance -- Systematic optimization methodology - -### Process & Quality Experts ✨ - -#### 🔍 `analyzer` - Root Cause Investigation Specialist -**What they do**: Systematic debugging, root cause analysis, evidence-based investigation - -**Priority**: Evidence > systematic approach > thoroughness > speed - -**When they auto-activate**: -- Keywords: "analyze", "investigate", "debug", "root cause" -- Debugging or troubleshooting sessions -- Complex problem investigation - -**Great for**: -- Debugging complex issues -- Root cause analysis -- System investigation -- Evidence-based problem solving -- Understanding unknown codebases - -**Investigation methodology**: -1. Evidence collection before conclusions -2. Pattern recognition in data -3. Hypothesis testing and validation -4. Root cause confirmation through tests - -**Example workflows**: -```bash -/sc:troubleshoot "auth randomly fails" --persona-analyzer -/sc:analyze --persona-analyzer mysterious-bug/ -/sc:explain --detailed "why is this slow" --persona-analyzer -``` - -**What they prioritize**: -- Evidence-based conclusions -- Systematic investigation methods -- Complete analysis before solutions -- Reproducible findings - ---- - -#### 🧪 `qa` - Quality Assurance & Testing Expert -**What they do**: Testing strategy, quality gates, edge case detection, risk assessment - -**Priority**: Prevention > detection > correction > comprehensive coverage - -**When they auto-activate**: -- Keywords: "test", "quality", "validation", "coverage" -- Testing or quality assurance work -- Quality gates or edge cases mentioned - -**Great for**: -- Test strategy and planning -- Quality assurance processes -- Edge case identification -- Risk-based testing -- Test automation - -**Quality risk assessment**: -- Critical path analysis for user journeys -- Failure impact evaluation -- Defect probability assessment -- Recovery difficulty estimation - -**Example workflows**: -```bash -/sc:test --persona-qa comprehensive-suite -/sc:analyze --focus quality --persona-qa -/sc:review --persona-qa critical-features/ -``` - -**What they prioritize**: -- Preventing defects over finding them -- Comprehensive test coverage -- Risk-based testing priorities -- Quality built into the process - ---- - -#### 🔄 `refactorer` - Code Quality & Cleanup Specialist -**What they do**: Code quality improvement, technical debt management, clean code practices - -**Priority**: Simplicity > maintainability > readability > performance > cleverness - -**When they auto-activate**: -- Keywords: "refactor", "cleanup", "quality", "technical debt" -- Code improvement or cleanup work -- Maintainability concerns - -**Great for**: -- Code refactoring and cleanup -- Technical debt reduction -- Code quality improvements -- Design pattern application -- Legacy code modernization - -**Code quality metrics they track**: -- Cyclomatic complexity -- Code readability scores -- Technical debt ratio -- Test coverage - -**Example workflows**: -```bash -/sc:improve --type quality --persona-refactorer -/sc:cleanup legacy-module/ --persona-refactorer -/sc:analyze --focus maintainability --persona-refactorer -``` - -**What they prioritize**: -- Simple, readable solutions -- Consistent patterns and conventions -- Maintainable code structure -- Technical debt management - ---- - -#### 🚀 `devops` - Infrastructure & Deployment Expert -**What they do**: Infrastructure automation, deployment, monitoring, reliability engineering - -**Priority**: Automation > observability > reliability > scalability > manual processes - -**When they auto-activate**: -- Keywords: "deploy", "infrastructure", "CI/CD", "monitoring" -- Deployment or infrastructure work -- DevOps or automation tasks - -**Great for**: -- Deployment automation and CI/CD -- Infrastructure as code -- Monitoring and alerting setup -- Performance monitoring -- Container and cloud infrastructure - -**Infrastructure automation priorities**: -- Zero-downtime deployments -- Automated rollback capabilities -- Infrastructure as code -- Comprehensive monitoring - -**Example workflows**: -```bash -/sc:deploy production --persona-devops -/sc:analyze infrastructure/ --persona-devops -/sc:improve deployment-pipeline --persona-devops -``` - -**What they prioritize**: -- Automated over manual processes -- Comprehensive observability -- Reliable, repeatable deployments -- Infrastructure as code practices - -### Knowledge & Communication 📚 - -#### 👨‍🏫 `mentor` - Educational Guidance Specialist -**What they do**: Teaching, knowledge transfer, educational explanations, learning facilitation - -**Priority**: Understanding > knowledge transfer > teaching > task completion - -**When they auto-activate**: -- Keywords: "explain", "learn", "understand", "teach" -- Educational or knowledge transfer tasks -- Step-by-step guidance requests - -**Great for**: -- Learning new technologies -- Understanding complex concepts -- Code explanations and walkthroughs -- Best practices education -- Team knowledge sharing - -**Learning optimization approach**: -- Skill level assessment -- Progressive complexity building -- Learning style adaptation -- Knowledge retention reinforcement - -**Example workflows**: -```bash -/sc:explain React hooks --persona-mentor -/sc:document --type guide --persona-mentor -/sc:analyze complex-algorithm.js --persona-mentor -``` - -**What they prioritize**: -- Clear, accessible explanations -- Complete conceptual understanding -- Engaging learning experiences -- Practical skill development - ---- - -#### ✍️ `scribe` - Professional Documentation Expert -**What they do**: Professional writing, documentation, localization, cultural communication - -**Priority**: Clarity > audience needs > cultural sensitivity > completeness > brevity - -**When they auto-activate**: -- Keywords: "document", "write", "guide", "README" -- Documentation or writing tasks -- Professional communication needs - -**Great for**: -- Technical documentation -- User guides and tutorials -- README files and wikis -- API documentation -- Professional communications - -**Language support**: English (default), Spanish, French, German, Japanese, Chinese, Portuguese, Italian, Russian, Korean - -**Content types**: Technical docs, user guides, API docs, commit messages, PR descriptions - -**Example workflows**: -```bash -/sc:document api/ --persona-scribe -/sc:git commit --persona-scribe -/sc:explain --persona-scribe=es complex-feature -``` - -**What they prioritize**: -- Clear, professional communication -- Audience-appropriate language -- Cultural sensitivity and adaptation -- High writing standards - -## When Each Persona Shines ⭐ - -### Development Phase Mapping - -**Planning & Design Phase**: -- 🏗️ `architect` - System design and architecture planning -- 🎨 `frontend` - UI/UX design and user experience -- ✍️ `scribe` - Requirements documentation and specifications - -**Implementation Phase**: -- 🎨 `frontend` - UI component development -- ⚙️ `backend` - API and service implementation -- 🛡️ `security` - Security implementation and hardening - -**Testing & Quality Phase**: -- 🧪 `qa` - Test strategy and quality assurance -- ⚡ `performance` - Performance testing and optimization -- 🔍 `analyzer` - Bug investigation and root cause analysis - -**Maintenance & Improvement Phase**: -- 🔄 `refactorer` - Code cleanup and refactoring -- ⚡ `performance` - Performance optimization -- 👨‍🏫 `mentor` - Knowledge transfer and documentation - -**Deployment & Operations Phase**: -- 🚀 `devops` - Deployment automation and infrastructure -- 🛡️ `security` - Security monitoring and compliance -- ✍️ `scribe` - Operations documentation and runbooks - -### Problem Type Mapping - -**"My code is slow"** → ⚡ `performance` -**"Something's broken and I don't know why"** → 🔍 `analyzer` -**"Need to design a new system"** → 🏗️ `architect` -**"UI looks terrible"** → 🎨 `frontend` -**"Is this secure?"** → 🛡️ `security` -**"Code is messy"** → 🔄 `refactorer` -**"Need better tests"** → 🧪 `qa` -**"Deployment keeps failing"** → 🚀 `devops` -**"I don't understand this"** → 👨‍🏫 `mentor` -**"Need documentation"** → ✍️ `scribe` - -## Persona Combinations 🤝 - -Personas often work together automatically. Here are common collaboration patterns: - -### Design & Implementation -```bash -/sc:design user-dashboard -# Auto-activates: 🏗️ architect (system design) + 🎨 frontend (UI design) -``` - -### Security Review -```bash -/sc:analyze --focus security api/ -# Auto-activates: 🛡️ security (primary) + ⚙️ backend (API expertise) -``` - -### Performance Optimization -```bash -/sc:improve --focus performance slow-app/ -# Auto-activates: ⚡ performance (primary) + 🎨 frontend (if UI) or ⚙️ backend (if API) -``` - -### Quality Improvement -```bash -/sc:improve --focus quality legacy-code/ -# Auto-activates: 🔄 refactorer (primary) + 🧪 qa (testing) + 🏗️ architect (design) -``` - -### Documentation & Learning -```bash -/sc:document complex-feature --type guide -# Auto-activates: ✍️ scribe (writing) + 👨‍🏫 mentor (educational approach) -``` - -## Practical Examples 💡 - -### Before/After: Generic vs Persona-Specific - -**Before** (generic): -```bash -/sc:analyze auth.js -# → Basic analysis, generic advice -``` - -**After** (security persona): -```bash -/sc:analyze auth.js --persona-security -# → Security-focused analysis -# → Threat modeling perspective -# → OWASP compliance checking -# → Vulnerability pattern detection -``` - -### Auto-Activation in Action - -**Frontend work detection**: -```bash -/sc:build react-components/ -# Auto-activates: 🎨 frontend -# → UI-focused build optimization -# → Accessibility checking -# → Performance budgets -# → Bundle size analysis -``` - -**Complex debugging**: -```bash -/sc:troubleshoot "payment processing randomly fails" -# Auto-activates: 🔍 analyzer -# → Systematic investigation approach -# → Evidence collection methodology -# → Pattern analysis -# → Root cause identification -``` - -### Manual Override Examples - -**Force security perspective**: -```bash -/sc:analyze react-app/ --persona-security -# Even though it's frontend code, analyze from security perspective -# → XSS vulnerability checking -# → Authentication flow analysis -# → Data exposure risks -``` - -**Get architectural advice on small changes**: -```bash -/sc:improve small-utility.js --persona-architect -# Apply architectural thinking to small code -# → Design pattern opportunities -# → Future extensibility -# → Coupling analysis -``` - -## Advanced Usage 🚀 - -### Manual Persona Control - -**When to override auto-activation**: -- You want a different perspective on the same problem -- Auto-activation chose wrong persona for your specific needs -- You're learning and want to see how different experts approach problems - -**How to override**: -```bash -# Explicit persona selection -/sc:analyze frontend-code/ --persona-security # Security view of frontend -/sc:improve backend-api/ --persona-performance # Performance view of backend - -# Multiple persona flags (last one wins) -/sc:analyze --persona-frontend --persona-security # Uses security persona -``` - -### Persona-Specific Flags and Settings - -**Security persona + validation**: -```bash -/sc:analyze --persona-security --focus security --validate -# → Maximum security focus with validation -``` - -**Performance persona + benchmarking**: -```bash -/sc:test --persona-performance --benchmark --focus performance -# → Performance-focused testing with metrics -``` - -**Mentor persona + detailed explanations**: -```bash -/sc:explain complex-concept --persona-mentor --verbose -# → Educational explanation with full detail -``` - -### Cross-Domain Expertise - -**When you need multiple perspectives**: -```bash -# Sequential analysis with different personas -/sc:analyze --persona-security api/auth.js -/sc:analyze --persona-performance api/auth.js -/sc:analyze --persona-refactorer api/auth.js - -# Or let SuperClaude coordinate automatically -/sc:analyze --focus quality api/auth.js -# Auto-coordinates: security + performance + refactorer insights -``` - -## Common Workflows by Persona 💼 - -### 🏗️ Architect Workflows -```bash -# System design -/sc:design microservices-architecture --persona-architect -/sc:estimate "migrate monolith to microservices" --persona-architect - -# Architecture review -/sc:analyze --focus architecture --persona-architect large-system/ -/sc:review --persona-architect critical-components/ -``` - -### 🎨 Frontend Workflows -```bash -# Component development -/sc:build dashboard-components/ --persona-frontend -/sc:improve --focus accessibility --persona-frontend ui/ - -# Performance optimization -/sc:analyze --focus performance --persona-frontend bundle/ -/sc:test --persona-frontend --focus performance -``` - -### ⚙️ Backend Workflows -```bash -# API development -/sc:design rest-api --persona-backend -/sc:build api-endpoints/ --persona-backend - -# Reliability improvements -/sc:improve --focus reliability --persona-backend services/ -/sc:analyze --persona-backend --focus security api/ -``` - -### 🛡️ Security Workflows -```bash -# Security assessment -/sc:scan --persona-security --focus security entire-app/ -/sc:analyze --persona-security auth-flow/ - -# Vulnerability fixing -/sc:improve --focus security --persona-security vulnerable-code/ -/sc:review --persona-security --focus security critical-paths/ -``` - -### 🔍 Analyzer Workflows -```bash -# Bug investigation -/sc:troubleshoot "intermittent failures" --persona-analyzer -/sc:analyze --persona-analyzer --focus debugging problem-area/ - -# System understanding -/sc:explain --persona-analyzer complex-system/ -/sc:load --persona-analyzer unfamiliar-codebase/ -``` - -## Quick Reference 📋 - -### Persona Cheat Sheet - -| Persona | Best For | Auto-Activates On | Manual Flag | -|---------|----------|-------------------|-------------| -| 🏗️ architect | System design, architecture | "architecture", "design", "scalability" | `--persona-architect` | -| 🎨 frontend | UI/UX, accessibility | "component", "responsive", "UI" | `--persona-frontend` | -| ⚙️ backend | APIs, databases, reliability | "API", "database", "service" | `--persona-backend` | -| 🛡️ security | Security, compliance | "security", "vulnerability", "auth" | `--persona-security` | -| ⚡ performance | Optimization, speed | "performance", "optimization", "slow" | `--persona-performance` | -| 🔍 analyzer | Debugging, investigation | "analyze", "debug", "investigate" | `--persona-analyzer` | -| 🧪 qa | Testing, quality | "test", "quality", "validation" | `--persona-qa` | -| 🔄 refactorer | Code cleanup, refactoring | "refactor", "cleanup", "quality" | `--persona-refactorer` | -| 🚀 devops | Deployment, infrastructure | "deploy", "infrastructure", "CI/CD" | `--persona-devops` | -| 👨‍🏫 mentor | Learning, explanation | "explain", "learn", "understand" | `--persona-mentor` | -| ✍️ scribe | Documentation, writing | "document", "write", "guide" | `--persona-scribe` | - -### Most Useful Combinations - -**Security-focused development**: -```bash ---persona-security --focus security --validate -``` - -**Performance optimization**: -```bash ---persona-performance --focus performance --benchmark -``` - -**Learning and understanding**: -```bash ---persona-mentor --verbose --explain -``` - -**Quality improvement**: -```bash ---persona-refactorer --focus quality --safe-mode -``` - -**Professional documentation**: -```bash ---persona-scribe --type guide --detailed -``` - -### Auto-Activation Triggers - -**Strong triggers** (usually work well): -- "security audit" → 🛡️ security -- "UI component" → 🎨 frontend -- "API design" → ⚙️ backend -- "system architecture" → 🏗️ architect -- "debug issue" → 🔍 analyzer - -**Moderate triggers** (often work): -- "improve performance" → ⚡ performance -- "write tests" → 🧪 qa -- "clean up code" → 🔄 refactorer -- "deployment issue" → 🚀 devops - -**Context-dependent triggers** (varies): -- "document this" → ✍️ scribe or 👨‍🏫 mentor (depends on audience) -- "analyze this" → 🔍 analyzer, 🏗️ architect, or domain specialist (depends on content) - -## Troubleshooting Persona Issues 🚨 - -### Common Problems - -**"Wrong persona activated"** -- Use explicit persona flags: `--persona-security` -- Check if your keywords triggered auto-activation -- Try more specific language in your request - -**"Persona doesn't seem to work"** -- Verify persona name spelling: `--persona-frontend` not `--persona-fronted` -- Some personas work better with specific commands -- Try combining with relevant flags: `--focus security --persona-security` - -**"Want multiple perspectives"** -- Run same command with different personas manually -- Use broader focus flags: `--focus quality` (activates multiple personas) -- Let SuperClaude coordinate automatically with complex requests - -**"Persona is too focused"** -- Try a different persona that's more general -- Use mentor persona for broader explanations -- Combine with `--verbose` for more context - -### When to Override Auto-Activation - -**Override when**: -- Auto-activation chose the wrong specialist -- You want to learn from a different perspective -- Working outside typical domain boundaries -- Need specific expertise for edge cases - -**How to override effectively**: -```bash -# Force specific perspective -/sc:analyze frontend-code/ --persona-security # Security view of frontend - -# Combine multiple perspectives -/sc:analyze api/ --persona-security -/sc:analyze api/ --persona-performance # Run separately for different views - -# Use general analysis -/sc:analyze --no-persona # Disable persona auto-activation -``` - -## Tips for Effective Persona Usage 💡 - -### Getting Started (The Honest Way) -1. **Just ignore personas completely at first** - Auto-activation handles everything -2. **Use basic commands normally** - `/analyze`, `/build`, `/improve` work great without persona knowledge -3. **Notice what happens** - You'll see different types of expertise emerge naturally -4. **Trust the automation** - SuperClaude usually picks better experts than manual selection - -### Getting Advanced (If You Want To) -1. **Experiment with manual override** - Try `--persona-security` on frontend code for different perspectives -2. **Learn the team members** - Read about individual personas when you get curious -3. **Watch persona combinations** - See how multiple experts collaborate on complex problems -4. **Use for learning** - Ask different personas the same question to see different approaches - -### Best Practices (Keep It Simple) -- **Let auto-activation work first** - Override only when you want different perspectives -- **Don't overthink it** - The right experts show up when needed -- **Use for experimentation** - Try different personas on the same problem for learning -- **Trust the intelligence** - Auto-activation learns from patterns and keeps getting better - ---- - -## Final Notes 📝 - -**The real truth about personas** 💯: -- **Auto-activation usually works pretty well** compared to trying to pick experts yourself -- **You can completely ignore this guide** and still often get helpful expert assistance -- **Personas exist to help you** - not to create complexity you need to manage -- **Learning happens naturally** through use, not through studying persona descriptions 😊 - -**Don't feel overwhelmed by the team** 🧘‍♂️: -- You don't need to know what each persona does -- SuperClaude usually handles expert selection reasonably well -- The detailed descriptions above are for curiosity, not necessity -- You're not missing anything by letting auto-activation work - -**When you might manually choose personas**: -- **Curiosity** - "What would a security expert think about this frontend code?" -- **Learning** - "How would different experts approach this problem?" -- **Experimentation** - "Let me see this through a performance lens" -- **Override** - "I want architectural advice on this small utility function" - -**Keep it simple** 🎯: -- Use normal commands like `/analyze some-code/` -- Let the right experts automatically show up -- Manual persona control is available when you want it, not because you need it -- Focus on your work, not on managing who helps you - ---- - -*Behind all this apparent complexity of having 11 specialists, SuperClaude tries to be simple to use. Just start coding and helpful experts usually show up when needed! 🚀* \ No newline at end of file diff --git a/Guides/agents-guide.md b/Guides/agents-guide.md new file mode 100644 index 0000000..ef65afd --- /dev/null +++ b/Guides/agents-guide.md @@ -0,0 +1,521 @@ +# SuperClaude Agents Guide 🤖 + +## Overview + +The SuperClaude Framework features 13 specialized domain expert agents that automatically activate based on your task context. These intelligent agents provide expert-level assistance across all aspects of software development, from architecture design to documentation writing. + +**The simple truth**: You don't need to pick agents or memorize what they do. SuperClaude automatically brings in the right experts for each situation! + +**Here's what actually happens:** +- You type `/analyze auth.js` → Security engineer automatically jumps in 🛡️ +- You work on React components → Frontend architect often takes over 🎨 +- You debug performance issues → Performance engineer often helps ⚡ +- You write documentation → Technical writer usually helps out ✍️ + +**It's like having a smart team** that knows when to jump in and help, without you managing who does what. + +## 🚀 Just Try These (No Agent Knowledge Required) + +```bash +# These automatically activate the right experts: +/analyze payment-system/ # → Security + backend experts auto-activate +/build react-app/ # → Frontend architect takes over +/improve slow-queries.sql # → Performance engineer jumps in +/troubleshoot "auth failing" # → Root cause analyst + security expert coordinate +/brainstorm "task manager app" # → Requirements analyst guides discovery +``` + +**See the pattern?** You focus on what you want to do, SuperClaude figures out who should help. + +--- + +## The SuperClaude Agent Team 👥 + +### Architecture & System Design Agents 🏗️ + +#### 🏗️ `system-architect` - Large-Scale Design Expert +**What they do**: Design scalable system architecture with focus on maintainability and long-term technical decisions + +**Auto-activation triggers**: +- Keywords: "architecture", "design", "scalability", "system", "patterns", "microservices" +- Large-scale system design and architectural decisions +- Cross-system integration and design pattern implementation + +**Specialized capabilities**: +- **System Design**: Component boundaries, interfaces, and interaction patterns +- **Scalability Architecture**: Horizontal scaling strategies, bottleneck identification +- **Dependency Management**: Coupling analysis, dependency mapping, risk assessment +- **Architectural Patterns**: Microservices, CQRS, event sourcing, domain-driven design +- **Technology Strategy**: Tool selection based on long-term impact and ecosystem fit + +**Example use cases**: +```bash +/design microservices-architecture # → System architecture and service design +/analyze --focus architecture system/ # → Architectural review and improvement +/plan scalability-improvements # → Scaling strategy and implementation +``` + +--- + +#### ⚙️ `backend-architect` - Reliable Backend Systems Expert +**What they do**: Design reliable backend systems with focus on data integrity, security, and fault tolerance + +**Auto-activation triggers**: +- Backend system design and API development requests +- Database design and optimization needs +- Security, reliability, and performance requirements +- Server-side architecture and scalability challenges + +**Specialized capabilities**: +- **API Design**: RESTful services, GraphQL, proper error handling, validation +- **Database Architecture**: Schema design, ACID compliance, query optimization +- **Security Implementation**: Authentication, authorization, encryption, audit trails +- **System Reliability**: Circuit breakers, graceful degradation, monitoring +- **Performance Optimization**: Caching strategies, connection pooling, scaling patterns + +**Example use cases**: +```bash +/design user-management-api # → Reliable API with proper auth +/optimize database-queries/ # → Performance tuning and indexing +/implement payment-processing # → Secure, reliable payment system +``` + +--- + +#### 🎨 `frontend-architect` - Accessible UI Systems Expert +**What they do**: Create accessible, performant user interfaces with focus on user experience and modern frameworks + +**Auto-activation triggers**: +- UI component development and design system requests +- Accessibility compliance and WCAG implementation needs +- Performance optimization and Core Web Vitals improvements +- Responsive design and mobile-first development requirements + +**Specialized capabilities**: +- **Accessibility**: WCAG 2.1 AA compliance, keyboard navigation, screen reader support +- **Performance**: Core Web Vitals, bundle optimization, loading strategies +- **Responsive Design**: Mobile-first approach, flexible layouts, device adaptation +- **Component Architecture**: Reusable systems, design tokens, maintainable patterns +- **Modern Frameworks**: React, Vue, Angular with best practices and optimization + +**Example use cases**: +```bash +/build dashboard-components/ # → Accessible React components +/improve --focus accessibility ui/ # → WCAG compliance and optimization +/optimize bundle-performance # → Core Web Vitals improvement +``` + +--- + +#### 🚀 `devops-architect` - Infrastructure Automation Expert +**What they do**: Automate infrastructure and deployment processes with focus on reliability and observability + +**Auto-activation triggers**: +- Infrastructure automation and CI/CD pipeline development needs +- Deployment strategy and zero-downtime release requirements +- Monitoring, observability, and reliability engineering requests +- Infrastructure as code and configuration management tasks + +**Specialized capabilities**: +- **CI/CD Pipelines**: Automated testing, deployment strategies, rollback capabilities +- **Infrastructure as Code**: Version-controlled, reproducible infrastructure management +- **Observability**: Comprehensive monitoring, logging, alerting, and metrics +- **Container Orchestration**: Kubernetes, Docker, microservices architecture +- **Cloud Automation**: Multi-cloud strategies, resource optimization, compliance + +**Example use cases**: +```bash +/deploy production-app # → Zero-downtime deployment pipeline +/build monitoring-stack # → Comprehensive observability setup +/secure infrastructure/ # → Security hardening and compliance +``` + +### Quality & Analysis Agents 🔍 + +#### 🛡️ `security-engineer` - Threat Modeling Expert +**What they do**: Identify security vulnerabilities and ensure compliance with security standards and best practices + +**Auto-activation triggers**: +- Security vulnerability assessment and code audit requests +- Compliance verification and security standards implementation needs +- Threat modeling and attack vector analysis requirements +- Authentication, authorization, and data protection implementation reviews + +**Specialized capabilities**: +- **Vulnerability Assessment**: OWASP Top 10, CWE patterns, code security analysis +- **Threat Modeling**: Attack vector identification, risk assessment, security controls +- **Compliance Verification**: Industry standards, regulatory requirements, security frameworks +- **Authentication & Authorization**: Identity management, access controls, privilege escalation +- **Data Protection**: Encryption implementation, secure data handling, privacy compliance + +**Example use cases**: +```bash +/scan --focus security auth-system/ # → Comprehensive security audit +/analyze payment-flow --security # → Threat modeling and risk assessment +/improve --fix vulnerabilities api/ # → Security hardening and fixes +``` + +--- + +#### ⚡ `performance-engineer` - Bottleneck Detection Expert +**What they do**: Optimize system performance through measurement-driven analysis and bottleneck elimination + +**Auto-activation triggers**: +- Performance optimization requests and bottleneck resolution needs +- Speed and efficiency improvement requirements +- Load time, response time, and resource usage optimization requests +- Core Web Vitals and user experience performance issues + +**Specialized capabilities**: +- **Frontend Performance**: Core Web Vitals, bundle optimization, asset delivery +- **Backend Performance**: API response times, query optimization, caching strategies +- **Resource Optimization**: Memory usage, CPU efficiency, network performance +- **Critical Path Analysis**: User journey bottlenecks, load time optimization +- **Benchmarking**: Before/after metrics validation, performance regression detection + +**Example use cases**: +```bash +/analyze --focus performance slow-api/ # → Bottleneck identification and fixes +/optimize database-queries/ # → Query performance tuning +/benchmark application-performance # → Load testing and capacity planning +``` + +--- + +#### 🔍 `root-cause-analyst` - Systematic Investigation Expert +**What they do**: Systematically investigate complex problems to identify underlying causes through evidence-based analysis and hypothesis testing + +**Auto-activation triggers**: +- Complex debugging scenarios requiring systematic investigation and evidence-based analysis +- Multi-component failure analysis and pattern recognition needs +- Problem investigation requiring hypothesis testing and verification +- Root cause identification for recurring issues and system failures + +**Specialized capabilities**: +- **Evidence Collection**: Log analysis, error pattern recognition, system behavior investigation +- **Hypothesis Formation**: Multiple theory development, assumption validation, systematic testing approach +- **Pattern Analysis**: Correlation identification, symptom mapping, system behavior tracking +- **Investigation Documentation**: Evidence preservation, timeline reconstruction, conclusion validation +- **Problem Resolution**: Clear remediation path definition, prevention strategy development + +**Example use cases**: +```bash +/troubleshoot "payment processing fails randomly" # → Systematic investigation +/analyze mysterious-bug/ # → Evidence-based debugging +/investigate system-outage-logs/ # → Root cause analysis +``` + +--- + +#### 🧪 `quality-engineer` - Quality Assurance Expert +**What they do**: Ensure software quality through comprehensive testing strategies and systematic edge case detection + +**Auto-activation triggers**: +- Testing strategy design and comprehensive test plan development requests +- Quality assurance process implementation and edge case identification needs +- Test coverage analysis and risk-based testing prioritization requirements +- Automated testing framework setup and integration testing strategy development + +**Specialized capabilities**: +- **Test Strategy Design**: Comprehensive test planning, risk assessment, coverage analysis +- **Edge Case Detection**: Boundary conditions, failure scenarios, negative testing +- **Test Automation**: Framework selection, CI/CD integration, automated test development +- **Quality Metrics**: Coverage analysis, defect tracking, quality risk assessment +- **Testing Methodologies**: Unit, integration, performance, security, and usability testing + +**Example use cases**: +```bash +/test --comprehensive user-service/ # → Full testing strategy and implementation +/validate --quality critical-features/ # → Quality gate implementation +/analyze --focus testing legacy-code/ # → Testing strategy for existing code +``` + +--- + +#### 🔄 `refactoring-expert` - Clean Code Specialist +**What they do**: Improve code quality and reduce technical debt through systematic refactoring and clean code principles + +**Auto-activation triggers**: +- Code complexity reduction and technical debt elimination requests +- SOLID principles implementation and design pattern application needs +- Code quality improvement and maintainability enhancement requirements +- Refactoring methodology and clean code principle application requests + +**Specialized capabilities**: +- **Code Simplification**: Complexity reduction, readability improvement, cognitive load minimization +- **Technical Debt Reduction**: Duplication elimination, anti-pattern removal, quality metric improvement +- **Pattern Application**: SOLID principles, design patterns, refactoring catalog techniques +- **Quality Metrics**: Cyclomatic complexity, maintainability index, code duplication measurement +- **Safe Transformation**: Behavior preservation, incremental changes, comprehensive testing validation + +**Example use cases**: +```bash +/improve --focus quality legacy-module/ # → Comprehensive code quality improvement +/refactor --safe complex-functions/ # → Safe refactoring with test coverage +/cleanup --technical-debt codebase/ # → Systematic technical debt reduction +``` + +### Specialized Development Agents 🎯 + +#### 🐍 `python-expert` - Master Python Specialist +**What they do**: Deliver production-ready, secure, high-performance Python code following SOLID principles and modern best practices + +**Auto-activation triggers**: +- Python development requests requiring production-quality code and architecture decisions +- Code review and optimization needs for performance and security enhancement +- Testing strategy implementation and comprehensive coverage requirements +- Modern Python tooling setup and best practices implementation + +**Specialized capabilities**: +- **Production Quality**: Security-first development, comprehensive testing, error handling, performance optimization +- **Modern Architecture**: SOLID principles, clean architecture, dependency injection, separation of concerns +- **Testing Excellence**: TDD approach, unit/integration/property-based testing, 95%+ coverage, mutation testing +- **Security Implementation**: Input validation, OWASP compliance, secure coding practices, vulnerability prevention +- **Performance Engineering**: Profiling-based optimization, async programming, efficient algorithms, memory management + +**Example use cases**: +```bash +/build python-api --focus security # → Production-ready FastAPI with security +/improve legacy-python/ --focus quality # → Refactor to SOLID principles +/test python-service/ --comprehensive # → Full test suite with coverage +``` + +--- + +#### 📋 `requirements-analyst` - Requirements Discovery Expert +**What they do**: Transform ambiguous project ideas into concrete specifications through systematic requirements discovery and structured analysis + +**Auto-activation triggers**: +- Ambiguous project requests requiring requirements clarification and specification development +- PRD creation and formal project documentation needs from conceptual ideas +- Stakeholder analysis and user story development requirements +- Project scope definition and success criteria establishment requests + +**Specialized capabilities**: +- **Requirements Discovery**: Systematic questioning, stakeholder analysis, user need identification +- **Specification Development**: PRD creation, user story writing, acceptance criteria definition +- **Scope Definition**: Boundary setting, constraint identification, feasibility validation +- **Success Metrics**: Measurable outcome definition, KPI establishment, acceptance condition setting +- **Stakeholder Alignment**: Perspective integration, conflict resolution, consensus building + +**Example use cases**: +```bash +/brainstorm "task management app" # → Interactive discovery session +# → Automatic handoff to requirements analyst +# → PRD generation with structured requirements +``` + +### Communication & Learning Agents 📚 + +#### ✍️ `technical-writer` - Documentation Excellence Expert +**What they do**: Create clear, comprehensive technical documentation tailored to specific audiences with focus on usability and accessibility + +**Auto-activation triggers**: +- API documentation and technical specification creation requests +- User guide and tutorial development needs for technical products +- Documentation improvement and accessibility enhancement requirements +- Technical content structuring and information architecture development + +**Specialized capabilities**: +- **Audience Analysis**: User skill level assessment, goal identification, context understanding +- **Content Structure**: Information architecture, navigation design, logical flow development +- **Clear Communication**: Plain language usage, technical precision, concept explanation +- **Practical Examples**: Working code samples, step-by-step procedures, real-world scenarios +- **Accessibility Design**: WCAG compliance, screen reader compatibility, inclusive language + +**Example use cases**: +```bash +/document api-endpoints/ # → Comprehensive API documentation +/write user-guide --audience beginner # → User-friendly tutorial and guides +/improve --docs project-documentation/ # → Documentation quality enhancement +``` + +--- + +#### 👨‍🏫 `learning-guide` - Learning & Mentorship Expert +**What they do**: Teach programming concepts and explain code with focus on understanding through progressive learning and practical examples + +**Auto-activation triggers**: +- Code explanation and programming concept education requests +- Tutorial creation and progressive learning path development needs +- Algorithm breakdown and step-by-step analysis requirements +- Educational content design and skill development guidance requests + +**Specialized capabilities**: +- **Concept Explanation**: Clear breakdowns, practical examples, real-world application demonstration +- **Progressive Learning**: Step-by-step skill building, prerequisite mapping, difficulty progression +- **Educational Examples**: Working code demonstrations, variation exercises, practical implementation +- **Understanding Verification**: Knowledge assessment, skill application, comprehension validation +- **Learning Path Design**: Structured progression, milestone identification, skill development tracking + +**Example use cases**: +```bash +/explain complex-algorithm --educational # → Step-by-step learning guide +/teach react-patterns --beginner # → Progressive React tutorial +/mentor junior-developer --focus testing # → Personalized learning guidance +``` + +--- + +## Agent Coordination & Integration 🤝 + +### Automatic Agent Collaboration + +Agents often work together automatically. Here are common collaboration patterns: + +#### **Multi-Domain Projects** +```bash +/build full-stack-app/ +# Auto-coordinates: backend-architect + frontend-architect + system-architect +``` + +#### **Security-Focused Development** +```bash +/analyze --focus security payment-system/ +# Auto-coordinates: security-engineer + backend-architect + performance-engineer +``` + +#### **Quality Improvement** +```bash +/improve --focus quality legacy-codebase/ +# Auto-coordinates: refactoring-expert + quality-engineer + system-architect +``` + +### Integration with MCP Servers + +Each agent leverages specific MCP servers for enhanced capabilities: + +- **Context7**: Documentation patterns, framework best practices, compliance standards +- **Sequential**: Complex analysis, systematic problem solving, architectural planning +- **Magic**: UI component generation, design system integration, modern frameworks +- **Playwright**: Cross-browser testing, visual validation, performance testing +- **Morphllm**: Intelligent code transformations, pattern application, optimization +- **Serena**: Memory operations, cross-reference management, symbol-level analysis + +### Integration with Commands + +Agents seamlessly integrate with SuperClaude's command system: + +```bash +# Commands automatically select appropriate agents +/analyze → root-cause-analyst or system-architect (context-dependent) +/build → frontend-architect, backend-architect, or python-expert +/test → quality-engineer with domain-specific coordination +/brainstorm → requirements-analyst for requirements discovery +/document → technical-writer with audience-appropriate formatting +``` + +## Quick Reference 📋 + +### Agent Selection Cheat Sheet + +| Agent | Best For | Auto-Activates On | Example Use | +|-------|----------|-------------------|-------------| +| 🏗️ system-architect | System design | Architecture, scalability | Large-scale system design | +| ⚙️ backend-architect | Backend systems | APIs, databases, services | Reliable backend systems | +| 🎨 frontend-architect | User interfaces | UI components, accessibility | Accessible web interfaces | +| 🚀 devops-architect | Infrastructure | CI/CD, deployment, monitoring | Deployment automation | +| 🛡️ security-engineer | Security analysis | Security keywords, auth code | Vulnerability assessment | +| ⚡ performance-engineer | Performance tuning | "slow", "bottleneck", profiling | System optimization | +| 🔍 root-cause-analyst | Problem solving | "debug", "investigate", bugs | Complex bug investigation | +| 🧪 quality-engineer | Quality assurance | Testing, validation, QA | Comprehensive test strategy | +| 🔄 refactoring-expert | Code improvement | Refactoring, cleanup, quality | Clean code practices | +| 🐍 python-expert | Python development | .py files, Python frameworks | Production Python APIs | +| 📋 requirements-analyst | Requirements discovery | Ambiguous projects, brainstorming | Project specification | +| ✍️ technical-writer | Documentation | Documentation requests | API documentation | +| 👨‍🏫 learning-guide | Learning & teaching | "explain", "learn", tutorials | Educational content | + +### Most Useful Agent Combinations + +**Full-Stack Development**: +```bash +# Automatically coordinates backend + frontend + architecture +/build modern-web-app/ +``` + +**Security & Performance Review**: +```bash +# Coordinates security + performance + quality analysis +/analyze --comprehensive production-system/ +``` + +**Learning & Development**: +```bash +# Coordinates learning guide + technical writer + domain expert +/explain complex-system --educational +``` + +**Project Discovery to Implementation**: +```bash +# Requirements → Architecture → Implementation +/brainstorm "e-commerce platform" +# → Automatic handoff through agent coordination +``` + +## Best Practices 💡 + +### Getting Started (The Simple Way) +1. **Just use normal commands** - Agents auto-activate based on your needs +2. **Trust the automation** - SuperClaude usually picks better experts than manual selection +3. **Focus on your work** - Not on managing which agent helps you +4. **Let coordination happen** - Multiple agents work together automatically + +### Advanced Usage (When You Want Control) +1. **Manual agent selection** - Use agent names in commands when you want specific expertise +2. **Cross-domain perspectives** - Ask security agents about frontend code for different viewpoints +3. **Learning mode** - Use learning-guide for explanation-focused assistance +4. **Quality focus** - Combine quality-engineer with domain experts for comprehensive quality + +### Common Patterns + +**For New Projects**: +```bash +/brainstorm "your project idea" # → Requirements discovery +# → Automatic PRD generation and handoff +# → Ready for implementation workflow +``` + +**For Existing Code**: +```bash +/analyze existing-system/ # → Appropriate domain expert auto-selected +/improve --focus quality code/ # → Quality-focused agent coordination +/secure legacy-application/ # → Security-focused analysis and hardening +``` + +**For Learning**: +```bash +/explain complex-concept --educational # → Learning guide with domain expert +/document api/ --audience beginner # → Technical writer with appropriate level +``` + +--- + +## Final Notes 📝 + +**The real truth about agents** 💯: +- **Auto-activation works remarkably well** - Usually better than trying to pick experts yourself +- **You can completely ignore agent details** and still get excellent expert assistance +- **Agents exist to help you** - Not to create complexity you need to manage +- **Learning happens naturally** through use, not through studying agent descriptions + +**Don't feel overwhelmed by the team** 🧘‍♂️: +- You don't need to know what each agent does +- SuperClaude handles expert selection intelligently +- The detailed descriptions above are for curiosity, not necessity +- Focus on your work - the right experts will show up when needed + +**When you might want to know about agents**: +- **Curiosity** - "What would a security expert think about this frontend code?" +- **Learning** - "How would different experts approach this problem?" +- **Specialization** - "I specifically need Python architecture expertise" +- **Quality focus** - "I want comprehensive quality analysis from multiple angles" + +**Keep it simple** 🎯: +- Use normal commands like `/analyze some-code/` and `/build my-app/` +- Let the right experts automatically show up +- Agent coordination is available when you want it, not because you need it +- Focus on building great software - we'll handle the expertise coordination + +--- + +*Behind this sophisticated team of 13 specialists, the SuperClaude Framework remains simple to use. Just start coding and the right experts show up when needed! 🚀* \ No newline at end of file diff --git a/Guides/behavioral-modes-guide.md b/Guides/behavioral-modes-guide.md new file mode 100644 index 0000000..cb15251 --- /dev/null +++ b/Guides/behavioral-modes-guide.md @@ -0,0 +1,695 @@ +# SuperClaude Behavioral Modes Guide 🧠 + +## 💡 The Simple Truth About Modes + +**You don't need to understand behavioral modes to use SuperClaude.** They work automatically in the background, adapting how Claude Code behaves based on what you're trying to do. + +**Here's what actually happens:** +- Type `/sc:brainstorm "app idea"` → Brainstorming mode kicks in with discovery questions 🤔 +- Work on complex debugging → Introspection mode helps with systematic analysis 🔍 +- Handle large refactoring → Task Management mode breaks it into coordinated steps 📋 +- Need multiple tools → Orchestration mode picks the best ones automatically 🎯 +- Context getting full → Token Efficiency mode compresses without losing meaning ⚡ + +**Think of it like this**: SuperClaude has different "personalities" that automatically show up when they'd be most helpful. You just work normally, and the right approach appears! ✨ + +--- + +**TL;DR**: Behavioral modes are SuperClaude's way of being smarter about how it helps you. They activate automatically. You don't manage them, they manage themselves. + +--- + +## 🚀 Just Try These (See Modes in Action) + +```bash +# Brainstorming Mode - Interactive discovery +/sc:brainstorm "task management app" # → Gets curious, asks discovery questions + +# Introspection Mode - Deep thinking +/sc:troubleshoot "weird auth behavior" # → Analyzes reasoning patterns systematically + +# Task Management Mode - Complex coordination +/sc:implement user-dashboard # → Breaks into phases, delegates subtasks + +# Orchestration Mode - Smart tool selection +/sc:analyze large-codebase/ # → Picks best tools, coordinates efficiently + +# Token Efficiency Mode - Compressed communication +/sc:improve --uc legacy-code/ # → Uses symbols, abbreviations, stays clear +``` + +**See the pattern?** You just say what you want to do. SuperClaude figures out the best way to help. The modes are the "how" - you focus on the "what". 🎯 + +--- + +## The Five Behavioral Modes 🌟 + +### 🧠 Brainstorming Mode - Interactive Discovery + +**What it does**: Turns SuperClaude into a collaborative discovery partner who helps you figure out what you actually want to build. + +#### Automatic Activation 🪄 +- **Vague requests**: "I want to build something...", "Maybe we could..." +- **Exploration words**: brainstorm, explore, discuss, figure out, not sure +- **Uncertainty**: "possibly", "thinking about", "could we" +- **Manual trigger**: `--brainstorm` or `--bs` + +#### How It Changes SuperClaude 🔄 +- **Socratic Dialogue**: Asks probing questions instead of jumping to solutions +- **Non-Presumptive**: Doesn't assume what you want, lets you guide discovery +- **Collaborative**: Partners with you rather than directing you +- **Brief Generation**: Turns conversations into structured requirement documents + +#### Real Examples 📝 + +**Standard response:** +``` +User: "I want to build a web app" +Claude: "I'll help you build a web application. What framework would you like to use?" +``` + +**Brainstorming mode:** +``` +User: "I want to build a web app" +Claude: "🤔 Let's explore this together! Discovery questions: + - What problem does this solve for your users? + - Who are your target users and what are their main workflows? + - What's your expected user volume and performance needs? + - Any existing systems it needs to integrate with? + - What's your timeline and technical constraints? + + 📝 Once we explore these, I'll generate a structured brief for implementation!" +``` + +#### Perfect For 💫 +- Early project planning and ideation +- Requirements discovery from vague ideas +- Turning "I need something that does..." into concrete specs +- Preventing scope creep through upfront exploration + +--- + +### 🔍 Introspection Mode - Meta-Cognitive Analysis + +**What it does**: Makes SuperClaude consciously analyze its own reasoning and decision-making process, especially when things go wrong or get complex. + +#### Automatic Activation 🪄 +- **Self-analysis requests**: "analyze my reasoning", "reflect on decision" +- **Error recovery**: When outcomes don't match expectations +- **Complex problems**: Multi-layered issues requiring conscious oversight +- **Pattern recognition**: Recurring behaviors or optimization needs +- **Manual trigger**: `--introspect` or `--introspection` + +#### How It Changes SuperClaude 🔄 +- **Self-Examination**: Consciously analyzes decision logic and reasoning chains +- **Transparency**: Exposes thinking with markers (🤔, 🎯, ⚡, 📊, 💡) +- **Pattern Detection**: Identifies recurring cognitive patterns and behaviors +- **Learning Focus**: Extracts insights for continuous improvement + +#### Real Examples 📝 + +**Standard response:** +``` +User: "The solution didn't work as expected" +Claude: "Let me look at the code and find the issue." +``` + +**Introspection mode:** +``` +User: "The solution didn't work as expected" +Claude: "🎯 Decision Analysis: Expected X → got Y + 🔍 Pattern Check: Similar logic errors in auth.js:15, config.js:22 + 📊 Framework Compliance: Missed validation step from quality gates + 🤔 Reasoning: Why did I choose async/await over promises here? + 💡 Insight: Need systematic validation before implementation + + Let me apply this learning to fix the current issue properly." +``` + +#### Perfect For 💫 +- Debugging complex problems that require meta-thinking +- Understanding why certain approaches were chosen +- Learning from mistakes and improving patterns +- Framework compliance checking and optimization + +--- + +### 📋 Task Management Mode - Orchestration & Delegation + +**What it does**: Transforms SuperClaude into a project coordinator that breaks complex work into systematic phases and coordinates multiple sub-tasks efficiently. + +#### Automatic Activation 🪄 +- **Multi-step operations**: 3+ steps (build, implement, create, fix, refactor) +- **Complex scope**: system-wide, feature-complete, comprehensive changes +- **File thresholds**: >2 directories OR >3 files OR complexity >0.4 +- **Quality improvements**: polish, refine, enhance keywords +- **Manual triggers**: `--delegate`, `--loop`, `--concurrency` + +#### How It Changes SuperClaude 🔄 +- **Orchestration Mindset**: Breaks complex work into coordinated layers +- **Delegation Strategy**: Parallel processing with intelligent sub-task routing +- **State Management**: Single focus protocol with real-time progress tracking +- **Quality Gates**: Evidence-based validation before task completion +- **Progressive Systems**: Systematic enhancement through compound intelligence + +#### Real Examples 📝 + +**Standard response:** +``` +User: "I need to refactor this authentication system" +Claude: "I'll refactor the authentication system for you." +``` + +**Task Management mode:** +``` +User: "I need to refactor this authentication system" +Claude: "📋 Detected: system-wide auth refactor → delegation mode activated + + 🔄 Phase 1: Security Analysis & Dependencies + - Analyze current auth.js, middleware.js, session.js + - Map security vulnerabilities and performance bottlenecks + - Document current API contracts and integrations + + 🔄 Phase 2: Core Implementation + - Refactor authentication logic with modern patterns + - Update middleware for improved security + - Enhance session management with proper cleanup + + 🔄 Phase 3: Integration & Validation + - Update all dependent components and routes + - Run comprehensive security and integration tests + - Performance benchmarking and optimization + + 📊 Progress tracking: Each phase validates before proceeding + ✅ Quality gates: Security, performance, compatibility checks" +``` + +#### Perfect For 💫 +- Large refactoring projects that span multiple files +- Feature implementation requiring coordination +- System-wide changes that need careful orchestration +- Complex builds that benefit from parallel processing + +--- + +### 🎯 Orchestration Mode - Intelligent Tool Selection + +**What it does**: Optimizes SuperClaude's tool selection and resource usage, automatically choosing the most powerful and efficient approach for each task. + +#### Automatic Activation 🪄 +- **Multi-tool operations**: Tasks requiring coordination between different tools +- **Performance constraints**: >75% resource usage detected +- **Parallel opportunities**: >3 files or independent operations possible +- **Complex routing**: Multiple valid approaches available +- **Manual trigger**: `--orchestrate` + +#### How It Changes SuperClaude 🔄 +- **Smart Tool Selection**: Always chooses the most powerful tool for each task type +- **Resource Awareness**: Adapts approach based on system constraints +- **Parallel Thinking**: Identifies independent operations for concurrent execution +- **Efficiency Focus**: Optimizes for speed and effectiveness over familiarity + +#### Tool Selection Matrix 🛠️ + +| Task Type | Best Tool | Alternative | Why Better | +|-----------|-----------|-------------|------------| +| UI components | Magic MCP | Manual coding | Modern patterns, accessibility | +| Deep analysis | Sequential MCP | Native reasoning | Structured multi-step thinking | +| Symbol operations | Serena MCP | Manual search | Semantic understanding | +| Pattern edits | Morphllm MCP | Individual edits | Bulk operations, consistency | +| Documentation | Context7 MCP | Web search | Official patterns, versioned | +| Browser testing | Playwright MCP | Unit tests | Real user interactions | +| Multi-file edits | MultiEdit | Sequential Edits | Atomic operations, rollback | + +#### Resource Management Zones 📊 + +**🟢 Green Zone (0-75%)** +- Full capabilities available +- Use all tools and features +- Normal verbosity and detail + +**🟡 Yellow Zone (75-85%)** +- Activate efficiency mode +- Reduce verbosity intelligently +- Defer non-critical operations + +**🔴 Red Zone (85%+)** +- Essential operations only +- Minimal output, maximum efficiency +- Fail fast on complex requests + +#### Real Examples 📝 + +**Standard response:** +``` +User: "/sc:analyze large-project/" +Claude: "I'll analyze your project files." +[Uses basic file reading and native analysis] +``` + +**Orchestration mode:** +``` +User: "/sc:analyze large-project/" +Claude: "🎯 Orchestration: large-project analysis + 📊 Resource Status: 45% → Green Zone + 🛠️ Tool Selection Matrix: + - File discovery: Glob (batch patterns) + - Code analysis: Sequential MCP (structured reasoning) + - Documentation: Context7 MCP (framework patterns) + - Parallel execution: 3 concurrent analysis threads + + ⚡ Executing optimized analysis workflow..." +``` + +#### Perfect For 💫 +- Large codebases requiring efficient analysis +- Performance-critical operations +- Tasks benefiting from parallel processing +- Resource-constrained environments + +--- + +### ⚡ Token Efficiency Mode - Compressed Communication + +**What it does**: Transforms SuperClaude's communication style to use symbols, abbreviations, and compressed formats while preserving 95%+ of information quality. + +#### Automatic Activation 🪄 +- **Context pressure**: >75% context usage or resource constraints +- **Large operations**: Complex analysis workflows needing optimization +- **User requests**: `--uc`, `--ultracompressed` flags +- **Efficiency needs**: When speed and conciseness are priorities + +#### How It Changes SuperClaude 🔄 +- **Symbol Communication**: Visual symbols for logic, status, and technical domains +- **Abbreviation Systems**: Context-aware compression for technical terms +- **30-50% Compression**: Significant token reduction while preserving meaning +- **Structured Output**: Bullet points, tables, concise explanations + +#### Symbol Reference 🔤 + +**Core Logic & Flow** +- `→` leads to, implies (`auth.js:45 → 🛡️ security risk`) +- `⇒` transforms to (`input ⇒ validated_output`) +- `←` rollback, reverse (`migration ← rollback`) +- `⇄` bidirectional (`sync ⇄ remote`) +- `&` and, combine (`🛡️ security & ⚡ performance`) +- `|` separator, or (`react|vue|angular`) +- `:` define, specify (`scope: file|module`) +- `»` sequence, then (`build » test » deploy`) +- `∴` therefore (`tests ❌ ∴ code broken`) +- `∵` because (`slow ∵ O(n²) algorithm`) + +**Status & Progress** +- `✅` completed, passed +- `❌` failed, error +- `⚠️` warning, review needed +- `🔄` in progress +- `⏳` waiting, pending +- `🚨` critical, urgent + +**Technical Domains** +- `⚡` Performance (speed, optimization) +- `🔍` Analysis (search, investigation) +- `🔧` Configuration (setup, tools) +- `🛡️` Security (protection, safety) +- `📦` Deployment (package, bundle) +- `🎨` Design (UI, frontend) +- `🏗️` Architecture (system structure) + +#### Abbreviation Systems 📝 + +**System & Architecture** +`cfg` config • `impl` implementation • `arch` architecture • `perf` performance • `ops` operations • `env` environment + +**Development Process** +`req` requirements • `deps` dependencies • `val` validation • `test` testing • `docs` documentation • `std` standards + +**Quality & Analysis** +`qual` quality • `sec` security • `err` error • `rec` recovery • `sev` severity • `opt` optimization + +#### Real Examples 📝 + +**Standard response:** +``` +User: "Analyze the authentication system performance" +Claude: "I'll analyze the authentication system's performance. The user validation function in auth.js line 45 has a security vulnerability. The build process completed successfully, now running tests, then deploying. Performance analysis shows the algorithm is slow because it's O(n²) complexity." +``` + +**Token Efficiency mode:** +``` +User: "Analyze the authentication system performance" +Claude: "⚡ auth.js perf analysis: + 🛡️ auth.js:45 → sec risk in user val() + 📊 build ✅ » test 🔄 » deploy ⏳ + 🔍 perf: slow ∵ O(n²) algo + + ∴ rec: impl O(log n) lookup & fix sec val" +``` + +#### Perfect For 💫 +- Large context situations requiring efficiency +- Complex analysis that would normally be verbose +- Performance-critical operations +- Users who prefer concise, information-dense output + +--- + +## How Modes Work Together 🤝 + +### Mode Coordination Examples + +**Building a New Feature** (Multiple Modes) +```bash +# Starts in Brainstorming Mode +/sc:brainstorm "user dashboard" +# 🧠 Discovery questions about requirements + +# Transitions to Task Management Mode +/sc:implement user-dashboard-feature +# 📋 Breaks into coordinated implementation phases + +# Orchestration Mode kicks in for complex parts +# 🎯 Chooses best tools for UI (Magic MCP), testing (Playwright MCP) + +# Token Efficiency if context gets full +# ⚡ Compresses communication while maintaining quality +``` + +**Debugging Complex Issues** +```bash +# Starts in Introspection Mode +/sc:troubleshoot "authentication randomly failing" +# 🔍 Systematic analysis of reasoning and patterns + +# Orchestration Mode for tool selection +# 🎯 Uses Sequential MCP for structured investigation + +# Task Management if solution is complex +# 📋 Coordinates fix across multiple files and systems +``` + +### Mode Priority System 📊 + +1. **User-Triggered** (`--brainstorm`, `--uc`, etc.) - Always override automatic +2. **Context-Critical** (Token Efficiency when context >85%) - High priority +3. **Task-Appropriate** (Task Management for 3+ steps) - Standard priority +4. **Enhancement** (Orchestration for optimization) - Background priority + +### Mode Switching 🔄 + +Modes can: +- **Layer together**: Task Management + Orchestration + Token Efficiency +- **Switch dynamically**: Brainstorming → Task Management → Orchestration +- **Enhance each other**: Introspection + Task Management for better quality + +--- + +## Manual Control 🎛️ + +### Force Specific Modes + +```bash +# Force Brainstorming Mode +/sc:analyze --brainstorm project-requirements + +# Force Token Efficiency +/sc:implement --uc user-authentication + +# Force Task Management +/sc:refactor --delegate large-codebase/ + +# Force Orchestration +/sc:build --orchestrate complex-project/ + +# Force Introspection +/sc:troubleshoot --introspect "reasoning issues" + +# Disable all modes (baseline Claude) +/sc:analyze --no-modes legacy-code/ +``` + +### When to Use Manual Control 🤔 + +**Force Brainstorming when:** +- You have specific requirements but want to explore alternatives +- Working with stakeholders who need guided discovery +- Converting existing features into comprehensive specs + +**Force Token Efficiency when:** +- Working in resource-constrained environments +- Need maximum information density +- Dealing with very large contexts + +**Force Task Management when:** +- Want explicit task breakdown for complex work +- Need to coordinate multiple team members +- Require detailed progress tracking + +**Force Orchestration when:** +- Performance is critical +- Want to see tool selection reasoning +- Working with multiple MCP servers + +**Force Introspection when:** +- Learning how SuperClaude makes decisions +- Debugging framework behavior +- Want transparent reasoning for auditing + +--- + +## Real-World Scenarios 🌍 + +### Scenario 1: Building a Task Management App + +**Phase 1: Discovery** (Brainstorming Mode) +```bash +/sc:brainstorm "task management app for development teams" + +# Mode activates automatically, provides discovery questions: +# - What problems do current tools not solve? +# - How do teams currently track tasks? +# - Integration needs with existing tools? +# - Expected team size and usage patterns? + +# Result: Structured requirements brief ready for implementation +``` + +**Phase 2: Implementation** (Task Management Mode) +```bash +/sc:implement task-management-app --from-brief requirements.md + +# Mode activates for complex implementation: +# Phase 1: Data models and API design +# Phase 2: Core functionality and business logic +# Phase 3: UI components and user experience +# Phase 4: Integration, testing, and deployment + +# Each phase validates before proceeding +``` + +**Phase 3: Optimization** (Orchestration + Token Efficiency) +```bash +/sc:improve performance task-management-app/ + +# Orchestration selects best tools for analysis +# Token Efficiency kicks in for large codebase analysis +# Result: Optimized, production-ready application +``` + +### Scenario 2: Debugging Authentication Issues + +**Investigation** (Introspection Mode) +```bash +/sc:troubleshoot "users can't log in on mobile but desktop works" + +# Introspection mode analyzes systematically: +# 🔍 Pattern analysis: Mobile vs desktop differences +# 🤔 Reasoning: What could cause platform-specific auth issues? +# 📊 Evidence gathering: Session handling, cookies, API calls +# 💡 Hypothesis formation and testing approach +``` + +**Systematic Fix** (Task Management + Orchestration) +```bash +/sc:implement auth-mobile-fix + +# Task Management coordinates the fix: +# Phase 1: Mobile session analysis (Playwright MCP for testing) +# Phase 2: API compatibility fixes (Sequential MCP for logic) +# Phase 3: Cross-platform validation (multiple tools) + +# Orchestration ensures optimal tool usage throughout +``` + +### Scenario 3: Large Codebase Refactoring + +**Planning** (Brainstorming + Introspection) +```bash +/sc:brainstorm "refactor legacy PHP app to modern architecture" + +# Brainstorming explores scope and requirements +# Introspection analyzes current architecture patterns +# Result: Clear migration strategy and requirements +``` + +**Execution** (Task Management + Token Efficiency) +```bash +/sc:refactor --delegate legacy-app/ --target modern-architecture + +# Task Management breaks into systematic phases +# Token Efficiency handles large codebase analysis efficiently +# Phase coordination ensures no breaking changes +``` + +--- + +## FAQ 🙋 + +### Do I need to understand behavioral modes? + +**No!** They work automatically. You focus on what you want to do, modes handle how SuperClaude helps you. Think of them like having different experts who automatically step in when needed. + +### How do I know which mode is active? + +Look for **behavioral markers**: +- 🤔 **Questions and exploration** = Brainstorming Mode +- 🔍 **Reasoning analysis symbols** = Introspection Mode +- 📋 **Phase breakdowns and delegation** = Task Management Mode +- 🎯 **Tool selection matrices** = Orchestration Mode +- ⚡ **Symbols and abbreviations** = Token Efficiency Mode + +### Can I disable behavioral modes? + +**Yes!** Use `--no-modes` flag: +```bash +/sc:analyze --no-modes simple-file.js +``` + +This gives you baseline Claude behavior without mode enhancements. + +### Which mode should I use manually? + +**Usually none!** Automatic activation works well 95% of the time. Manual control is for: +- **Learning**: Force modes to see how they work +- **Special cases**: Unusual requirements or constraints +- **Team coordination**: Explicit task breakdowns for collaboration +- **Performance**: Force efficiency in resource-constrained environments + +### Can multiple modes be active at once? + +**Yes!** Modes often layer together: +- Task Management + Orchestration (complex projects with optimal tools) +- Introspection + Token Efficiency (deep analysis with compressed output) +- Brainstorming + Task Management (discovery → implementation pipeline) + +### Do modes work with all commands? + +Most commands work with modes, but some have natural affinities: +- `/sc:brainstorm` → Always Brainstorming Mode +- `/sc:troubleshoot` → Often Introspection Mode +- `/sc:implement` (complex) → Usually Task Management Mode +- Large operations → Often trigger Orchestration Mode +- High context → May activate Token Efficiency Mode + +### Are modes related to agents? + +**Yes, but differently!** +- **Agents** = Who helps (security-engineer, frontend-architect, etc.) +- **Modes** = How they help (systematically, efficiently, collaboratively) + +Modes determine the behavioral approach, agents provide domain expertise. A security-engineer might work in Task Management mode for complex security implementations, or Introspection mode for security analysis. + +--- + +## Technical Reference 🔧 + +### Complete Trigger Lists + +**Brainstorming Mode Triggers** +- **Keywords**: brainstorm, explore, discuss, figure out, not sure, maybe, possibly, thinking about, could we +- **Phrases**: "I want to build...", "thinking about creating...", "not sure how to...", "maybe we could..." +- **Context**: Vague requirements, early planning, stakeholder discussions +- **Manual**: `--brainstorm`, `--bs` + +**Introspection Mode Triggers** +- **Keywords**: analyze reasoning, reflect on, why did, decision logic, pattern check +- **Context**: Error recovery, unexpected results, complex problem solving, framework discussions +- **Indicators**: Multiple failed approaches, recurring issues, need for meta-analysis +- **Manual**: `--introspect`, `--introspection` + +**Task Management Mode Triggers** +- **Operations**: build, implement, create, fix, refactor (3+ steps) +- **Scope**: system, feature, comprehensive, complete, end-to-end +- **Thresholds**: >2 directories OR >3 files OR complexity score >0.4 +- **Keywords**: polish, refine, enhance, coordinate, manage +- **Manual**: `--delegate`, `--loop`, `--concurrency` + +**Orchestration Mode Triggers** +- **Conditions**: Multi-tool operations, >3 files, parallel opportunities +- **Performance**: >75% resource usage, efficiency requirements +- **Complexity**: Multiple valid approaches, tool selection decisions +- **Manual**: `--orchestrate` + +**Token Efficiency Mode Triggers** +- **Resource**: Context >75%, large-scale operations, memory constraints +- **User requests**: `--uc`, `--ultracompressed`, brevity requirements +- **Workflow**: Complex analysis needing optimization, high information density +- **Manual**: `--uc`, `--ultracompressed`, `--token-efficient` + +### Flag Reference Table 🏳️ + +| Flag | Mode | Purpose | Usage | +|------|------|---------|-------| +| `--brainstorm`, `--bs` | Brainstorming | Force discovery mode | Requirements exploration | +| `--introspect` | Introspection | Force reasoning analysis | Decision transparency | +| `--delegate` | Task Management | Force delegation mode | Complex coordination | +| `--delegate` | Task Management | Enable delegation mode | Parallel processing | +| `--loop` | Task Management | Enable iteration cycles | Improvement workflows | +| `--orchestrate` | Orchestration | Force tool optimization | Performance priority | +| `--uc`, `--ultracompressed` | Token Efficiency | Force compression | Resource constraints | +| `--no-modes` | None | Disable all modes | Baseline behavior | + +### Integration with Framework Components + +**With Agents** 🤖 +- Modes determine **how** agents work +- Agents provide **domain expertise** +- Example: security-engineer in Task Management mode = systematic security implementation + +**With Commands** 🛠️ +- Commands trigger mode activation +- Modes enhance command execution +- Example: `/sc:implement` complex features → Task Management mode activation + +**With MCP Servers** 🔧 +- Orchestration mode optimizes MCP usage +- Task Management coordinates multi-MCP operations +- Token Efficiency compresses MCP communications + +### Performance Metrics 📊 + +**Mode Efficiency Gains** +- **Brainstorming**: 60-80% better requirement clarity +- **Introspection**: 40-60% improved decision quality +- **Task Management**: 40-70% time savings via delegation +- **Orchestration**: 20-40% performance improvement via optimal tools +- **Token Efficiency**: 30-50% token reduction with 95%+ information preservation + +**Resource Impact** +- Brainstorming: Low overhead, high value for unclear requirements +- Introspection: Medium overhead, high value for complex problems +- Task Management: Variable overhead, scales with task complexity +- Orchestration: Low overhead, improves overall efficiency +- Token Efficiency: Negative overhead (saves resources), maintains quality + +--- + +*Behavioral modes are SuperClaude's intelligence system - they make Claude Code smarter about how it helps you. You don't manage them, they manage themselves to give you the best experience! 🧠✨* + +--- + +**Related Guides:** +- 🤖 [Agent System Guide](agents-guide.md) - Understanding the 13 specialized agents +- 🛠️ [Commands Guide](commands-guide.md) - All 21 commands with mode integration +- 🏳️ [Flags Guide](flags-guide.md) - Manual mode control and behavioral flags +- 📖 [SuperClaude User Guide](superclaude-user-guide.md) - Complete framework overview \ No newline at end of file diff --git a/Docs/commands-guide.md b/Guides/commands-guide.md similarity index 89% rename from Docs/commands-guide.md rename to Guides/commands-guide.md index 16d992f..10ff767 100644 --- a/Docs/commands-guide.md +++ b/Guides/commands-guide.md @@ -12,6 +12,14 @@ **Auto-activation is pretty neat** 🪄 - SuperClaude attempts to detect what you're trying to do and activate relevant specialists (security expert, performance optimizer, etc.) without you managing it. Usually works well! 😊 +## Core Philosophy + +SuperClaude commands work by: +- **Intelligent activation**: Right experts and tools activated automatically +- **Context awareness**: Understanding your project and frameworks +- **Safe operations**: Quality gates and validation throughout +- **Progressive enhancement**: Building from simple to complex solutions + --- ## Quick "Just Try These" List 🚀 @@ -33,7 +41,7 @@ --- -A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest about what works well and what's still rough around the edges. +A practical guide to all 21 SuperClaude v4.0.0 slash commands. We'll be honest about what works well and what's still rough around the edges. ## Quick Reference 📋 @@ -78,12 +86,12 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest - Want expert guidance on implementation strategy - Planning complex features with multiple dependencies -**The magic**: Auto-activates appropriate expert personas (architect, security, frontend, backend) and MCP servers (Context7 for patterns, Sequential for complex analysis) based on your feature requirements. +**The magic**: Auto-activates appropriate expert agents (architect, security, frontend, backend) and MCP servers (Context7 for patterns, Sequential for complex analysis) based on your feature requirements. **Examples**: ```bash /sc:workflow docs/feature-100-prd.md --strategy systematic --c7 --sequential -/sc:workflow "user authentication system" --persona security --output detailed +/sc:workflow "user authentication system" --agent security --output detailed /sc:workflow payment-api --strategy mvp --risks --dependencies ``` @@ -132,10 +140,10 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest ``` **Auto-activation patterns**: -- **Frontend**: UI components, React/Vue/Angular → frontend persona + Magic MCP -- **Backend**: APIs, services, databases → backend persona + Context7 -- **Security**: Auth, payments, sensitive data → security persona + validation -- **Complex features**: Multi-step implementations → Sequential MCP + architect persona +- **Frontend**: UI components, React/Vue/Angular → frontend agent + Magic MCP +- **Backend**: APIs, services, databases → backend agent + Context7 +- **Security**: Auth, payments, sensitive data → security agent + validation +- **Complex features**: Multi-step implementations → Sequential MCP + architect agent **Gotchas**: - Specify `--type` for better results (component vs service vs feature) @@ -275,14 +283,14 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest **Useful flags**: - `--logs ` - Include log file analysis -- `--systematic` - Use structured debugging approach +- `--seq` - Use structured debugging approach - `--focus network|database|frontend` - Focus area **Real examples**: ```bash /sc:troubleshoot "API returning 500" --logs server.log /sc:troubleshoot --focus database "slow queries" -/sc:troubleshoot "build failing" --systematic +/sc:troubleshoot "build failing" --seq ``` **Gotchas**: @@ -842,7 +850,7 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest ### Common Workflows -**New Project Discovery** (V4 Beta): +**New Project Discovery**: ```bash /sc:brainstorm "project idea" --prd # Explore and define requirements /sc:load --deep --summary # Understand existing codebase @@ -884,7 +892,7 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest /sc:save --checkpoint "pre-deployment validation" ``` -**Complex Task Planning** (V4 Beta): +**Complex Task Planning**: ```bash /sc:select-tool "migrate to microservices" # Get approach recommendations /sc:reflect --type task "migration strategy" # Validate approach @@ -942,6 +950,65 @@ A practical guide to all 21 SuperClaude V4 Beta slash commands. We'll be honest **Need help?** Check the GitHub issues or create a new one if you're stuck! 🚀 +## Command Flags & Options + +### Common Flags +- `--safe` - Conservative operations with validation +- `--interactive` - Guided operation with user input +- `--parallel` - Parallel execution where applicable +- `--preview` - Show changes without applying +- `--analyze` - Deep analysis mode +- `--validate` - Enhanced validation and verification +- `--depth shallow|normal|deep` - Analysis depth control +- `--strategy systematic|agile|enterprise` - Execution strategy + +### Format Options +- `--format text|json|yaml|report|diagram` - Output format control +- `--type` - Operation type specification (varies by command) +- `--style brief|detailed` - Output verbosity control + +## Expert Activation + +The framework automatically activates relevant experts: + +### Technical Specialists +- **Backend Architect** - Server architecture, APIs, databases +- **DevOps Architect** - Infrastructure, deployment, CI/CD +- **Frontend Architect** - UI architecture, state management, performance +- **Learning Guide** - Educational content, knowledge transfer +- **Performance Engineer** - Optimization, profiling, scalability +- **Python Expert** - Python-specific development and best practices +- **Quality Engineer** - Testing, quality assurance, code standards +- **Refactoring Expert** - Code restructuring and technical debt +- **Requirements Analyst** - Requirements gathering and analysis +- **Root Cause Analyst** - Problem diagnosis and systematic debugging +- **Security Engineer** - Security assessment and hardening +- **Technical Writer** - Documentation and communication + +### MCP Server Integration +- **Context7** - Official documentation and framework patterns +- **Magic** - Modern UI component generation +- **Morphllm** - Pattern-based code editing and transformations +- **Playwright** - Browser automation and E2E testing +- **Sequential** - Complex multi-step reasoning and analysis +- **Serena** - Project memory and session management + +## Command Relationships + +### Session Flow +`/sc:load` → Work with commands → `/sc:reflect` (validate) → `/sc:save` + +### Development Flow +`/sc:analyze` → `/sc:design` → `/sc:implement` → `/sc:test` → `/sc:improve` + +### Project Flow +`/sc:brainstorm` → `/sc:workflow` → `/sc:estimate` → `/sc:spawn` or `/sc:task` + +### Maintenance Flow +`/sc:troubleshoot` → `/sc:cleanup` → `/sc:improve` → `/sc:document` + +Remember: SuperClaude adapts to your needs. Start with simple requests and let the framework's intelligence guide you to more sophisticated usage patterns! + --- *Happy coding! Just remember - you can skip most of this guide and learn by doing. 🎯* diff --git a/Docs/flags-guide.md b/Guides/flags-guide.md similarity index 86% rename from Docs/flags-guide.md rename to Guides/flags-guide.md index 2d58da7..fd543f0 100644 --- a/Docs/flags-guide.md +++ b/Guides/flags-guide.md @@ -1,4 +1,4 @@ -# SuperClaude V4 Beta Flags User Guide 🏁 +# SuperClaude Framework Flags User Guide 🏁 ## 🤖 Most Flags Activate Automatically - Don't Stress About It! @@ -7,7 +7,7 @@ **Here's what actually happens:** - You type `/analyze auth.js` - SuperClaude detects it's security-related code -- **Usually activates** security-auditor agent, `--focus security`, `--validate` +- **Usually activates** security-engineer agent, `--focus security`, `--validate` - You often get expert security analysis without managing any flags **When might you manually use flags?** @@ -26,8 +26,8 @@ /sc:analyze src/ # Auto-activates appropriate expert agents /sc:build # Auto-optimizes based on your project /sc:improve messy-code.js # Auto-activates quality agents and safety flags -/sc:troubleshoot "weird error" # Auto-activates root-cause-analyzer and debugging flags -/sc:brainstorm "my app idea" # Auto-activates brainstorm-PRD agent for requirements +/sc:troubleshoot "weird error" # Auto-activates root-cause-analyst and debugging flags +/sc:brainstorm "my app idea" # Auto-activates requirements-analyst agent for discovery ``` **See? No flags needed.** Everything below is for when you get curious about what's happening behind the scenes. @@ -148,7 +148,7 @@ Enable specialized capabilities through MCP servers. #### `--magic` **What it does**: Enables Magic for UI component generation **When to use**: Creating UI components, design systems -**Auto-activates**: UI component requests, frontend persona +**Auto-activates**: UI component requests, frontend architect agent **Example**: `/build dashboard --magic` - Get modern UI components #### `--play` / `--playwright` @@ -157,8 +157,8 @@ Enable specialized capabilities through MCP servers. **Auto-activates**: Test workflows, QA specialist agent **Example**: `/test e2e --play` -#### `--morph` / `--fast-apply` -**What it does**: Enables Morphllm for intelligent file editing with Fast Apply +#### `--morph` / `--morphllm` +**What it does**: Enables Morphllm for intelligent file editing and pattern transformations **When to use**: Multi-file edits, pattern-based transformations **Auto-activates**: Complex refactoring, bulk file updates **Example**: `/refactor --morph pattern-updates/` @@ -199,12 +199,6 @@ For complex operations and workflows. **Example**: `/analyze monorepo/ --delegate auto` -#### `--wave-mode [auto|force|off]` -**What it does**: Multi-stage execution with compound intelligence -**When to use**: Complex improvements, systematic analysis -**Auto-activates**: Complexity >0.8 AND files >20 AND operation types >2 -**Example**: `/improve legacy-system/ --wave-mode force` - #### `--loop` **What it does**: Iterative improvement mode **When to use**: Quality improvement, refinement operations @@ -232,7 +226,7 @@ For complex operations and workflows. ### Session & Workflow Flags 🔄 -These V4 Beta flags control session management and advanced workflows. +These SuperClaude Framework flags control session management and advanced workflows. #### `--brainstorm` **What it does**: Activates brainstorming mode for requirements discovery @@ -251,7 +245,7 @@ These V4 Beta flags control session management and advanced workflows. **Auto-activates**: End of successful brainstorming sessions **Example**: `/brainstorm app-idea --prd` -**💡 Tip**: V4 Beta introduces powerful session management - let brainstorming mode guide requirement discovery naturally. +**💡 Tip**: SuperClaude Framework introduces powerful session management - let brainstorming mode guide requirement discovery naturally. --- @@ -270,9 +264,9 @@ Direct SuperClaude's attention to specific areas. **Example**: `/analyze --focus security --scope project` #### Agent Flags -**Available agents**: system-architect, frontend-specialist, backend-engineer, root-cause-analyzer, security-auditor, code-educator, code-refactorer, performance-optimizer, qa-specialist, devops-engineer, technical-writer, python-ultimate-expert, brainstorm-PRD -**What they do**: Activates specialized domain expert agents (V4 Beta enhancement) -**Example**: `/analyze --agent security-auditor` - Security-focused analysis with expert agent +**Available agents**: system-architect, backend-architect, frontend-architect, devops-architect, security-engineer, performance-engineer, root-cause-analyst, quality-engineer, refactoring-expert, python-expert, requirements-analyst, technical-writer, learning-guide +**What they do**: Activates specialized domain expert agents (SuperClaude Framework enhancement) +**Example**: `/analyze --agent security-engineer` - Security-focused analysis with expert agent **💡 Tip**: `--focus` is great for targeted analysis. Expert agents auto-activate but manual control helps. @@ -295,13 +289,13 @@ Direct SuperClaude's attention to specific areas. ### Large Project Work ```bash /sc:analyze monorepo/ --delegate auto --uc # Efficient large analysis -/sc:improve legacy/ --wave-mode auto --safe-mode # Safe systematic improvement +/sc:improve legacy/ --loop --safe-mode # Safe iterative improvement ``` ### Learning & Documentation ```bash /sc:explain React hooks --c7 --verbose # Detailed explanation with docs -/sc:document api/ --persona-scribe # Professional documentation +/sc:document api/ --agent technical-writer # Professional documentation ``` ### Performance-Focused @@ -313,7 +307,7 @@ Direct SuperClaude's attention to specific areas. ### Security-Focused ```bash /sc:analyze --focus security --think --validate # Thorough security analysis -/sc:scan --persona-security --safe-mode # Conservative security scan +/sc:scan --agent security-engineer --safe-mode # Conservative security scan ``` ## Practical Examples 💡 @@ -355,8 +349,8 @@ Direct SuperClaude's attention to specific areas. **After** (safe): ```bash -/sc:improve legacy-system/ --safe-mode --loop --validate --preview -# → Safe changes only, iterative approach, validates first, shows preview +/sc:improve legacy-system/ --safe-mode --loop --validate +# → Safe changes only, iterative approach, validates first, systematic improvement # → Much safer, progressive improvement ``` @@ -378,11 +372,11 @@ SuperClaude usually adds flags based on context. Here's when it tries: ### Domain-Based ```bash /sc:build react-app/ -# Auto-activates: frontend-specialist agent + --c7 +# Auto-activates: frontend-architect agent + --c7 # Why: Frontend framework detected /sc:analyze --focus security -# Auto-activates: security-auditor agent + --validate +# Auto-activates: security-engineer agent + --validate # Why: Security focus triggers security specialist ``` @@ -405,20 +399,20 @@ SuperClaude usually adds flags based on context. Here's when it tries: **Comprehensive Code Review**: ```bash -/sc:review codebase/ --agent qa-specialist --think-hard --focus quality --validate --c7 -# → QA specialist agent + deep thinking + quality focus + validation + docs +/sc:review codebase/ --agent quality-engineer --think-hard --focus quality --validate --c7 +# → Quality engineer agent + deep thinking + quality focus + validation + docs ``` **Legacy System Modernization**: ```bash -/sc:improve legacy/ --wave-mode force --agent system-architect --safe-mode --loop --c7 -# → Wave orchestration + architect agent + safety + iteration + docs +/sc:improve legacy/ --delegate auto --agent system-architect --safe-mode --loop --c7 +# → Systematic orchestration + architect agent + safety + iteration + docs ``` **Security Audit**: ```bash -/sc:scan --agent security-auditor --ultrathink --focus security --validate --seq -# → Security auditor agent + maximum thinking + security focus + validation + systematic analysis +/sc:scan --agent security-engineer --ultrathink --focus security --validate --seq +# → Security engineer agent + maximum thinking + security focus + validation + systematic analysis ``` ### Performance Optimization @@ -440,14 +434,14 @@ SuperClaude usually adds flags based on context. Here's when it tries: **Bug Investigation Workflow**: ```bash /sc:troubleshoot "specific error" --seq --think --validate -/sc:analyze affected-files/ --focus quality --agent root-cause-analyzer +/sc:analyze affected-files/ --focus quality --agent root-cause-analyst /sc:test --play --coverage ``` **Feature Development Workflow**: ```bash /sc:design new-feature --agent system-architect --c7 -/sc:build --magic --agent frontend-specialist --validate +/sc:build --magic --agent frontend-architect --validate /sc:test --play --coverage /sc:document --agent technical-writer --c7 ``` @@ -471,7 +465,7 @@ SuperClaude usually adds flags based on context. Here's when it tries: ### Flag Combinations That Work Well ```bash # Safe improvement ---safe-mode --validate --preview +--safe-mode --validate # Deep analysis --think --seq --c7 @@ -480,13 +474,13 @@ SuperClaude usually adds flags based on context. Here's when it tries: --delegate auto --uc --focus # Learning ---verbose --c7 --agent code-educator +--verbose --c7 --agent learning-guide # Security work ---agent security-auditor --focus security --validate +--agent security-engineer --focus security --validate # Performance work ---agent performance-optimizer --focus performance --play +--agent performance-engineer --focus performance --play # Requirements discovery --brainstorm --max-rounds 10 --prd @@ -508,7 +502,7 @@ SuperClaude usually adds flags based on context. Here's when it tries: ### Common Problems **"Flags don't seem to work"** -- Check spelling (common typos: `--ultracompresed`, `--agent fronted-specialist`) +- Check spelling (common typos: `--ultracompresed`, `--agent frontend-architect`) - Some flags need values: `--scope project`, `--focus security` - Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, `--serena`, etc. @@ -525,19 +519,19 @@ SuperClaude usually adds flags based on context. Here's when it tries: **"Not thorough enough"** - Add `--think` or `--think-hard` - Enable relevant MCP servers: `--seq`, `--c7` -- Use appropriate agent: `--agent root-cause-analyzer` +- Use appropriate agent: `--agent root-cause-analyst` **"Changes too risky"** - Always use `--safe-mode` for important code - Add `--validate` to check first -- Use `--preview` to see changes before applying +- Use `--validate` to check changes before applying ### Flag Conflicts **These override others**: - `--no-mcp` overrides all MCP flags (`--c7`, `--seq`, `--serena`, etc.) - `--safe-mode` overrides optimization flags -- Last agent flag wins: `--agent frontend-specialist --agent backend-engineer` → backend-engineer +- Last agent flag wins: `--agent frontend-architect --agent backend-architect` → backend-architect **Precedence order**: 1. Safety flags (`--safe-mode`) beat optimization @@ -554,7 +548,7 @@ SuperClaude usually adds flags based on context. Here's when it tries: 4. **Trust the automation** - SuperClaude usually picks reasonable defaults ### Getting Advanced (If You Want To) -1. **Experiment with overrides** - Try `--agent security-auditor` on non-security code for different perspectives +1. **Experiment with overrides** - Try `--agent security-engineer` on non-security code for different perspectives 2. **Learn the useful combos** - `--safe-mode --validate` for important stuff, `--brainstorm --prd` for new projects 3. **Understand the performance trade-offs** - Fast (`--uc --no-mcp`) vs thorough (`--think-hard --all-mcp`) 4. **Use flags for learning** - `--verbose` when you want to understand what's happening @@ -562,8 +556,8 @@ SuperClaude usually adds flags based on context. Here's when it tries: ### Performance Tips (For Power Users) - **For speed**: `--uc --no-mcp --scope file` - **For thoroughness**: `--think-hard --all-mcp --delegate auto` -- **For safety**: `--safe-mode --validate --preview` -- **For learning**: `--verbose --c7 --agent code-educator` +- **For safety**: `--safe-mode --validate` +- **For learning**: `--verbose --c7 --agent learning-guide` - **For project discovery**: `--brainstorm --max-rounds 15 --prd` --- diff --git a/Guides/installation-guide.md b/Guides/installation-guide.md new file mode 100644 index 0000000..108e77d --- /dev/null +++ b/Guides/installation-guide.md @@ -0,0 +1,449 @@ +# SuperClaude Installation Guide 📦 + +## 🎯 It's Easier Than It Looks! + +**The honest truth**: This guide looks comprehensive because we want to cover all the details, but installation is actually simple. Most people are done in 2 minutes with one command! + +## Quick Start 🚀 + +**🏆 The "Just Get It Working" Approach (Recommended for 90% of Users)** + +### Option A: From PyPI (Recommended) +```bash +pip install SuperClaude + +# Install with interactive selection +SuperClaude install + +# That's it! 🎉 +``` + +### Option B: From Source +```bash +git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git +cd SuperClaude_Framework +pip install . + +# Install with interactive selection +SuperClaude install + +# That's it! 🎉 +``` + +**What you just got:** +- ✅ 21 intelligent commands that auto-activate specialized capabilities +- ✅ 13 specialized AI agents with domain expertise and smart routing +- ✅ 5 behavioral modes for different types of work +- ✅ 6 MCP servers for extended functionality (optional) +- ✅ Session lifecycle management with persistent context +- ✅ About 2 minutes of your time and ~50MB disk space + +**Nervous about what it will do?** See first with: +```bash +SuperClaude install --dry-run +``` + +## Before You Start 🔍 + +### What You Need 💻 + +SuperClaude works on **Windows**, **macOS**, and **Linux**. Here's what you need: + +**Required:** +- **Python 3.8 or newer** - The framework is written in Python +- **Claude Code** - SuperClaude enhances Claude Code, so you need it installed first + +**Optional (but recommended):** +- **Node.js 16+** - Only needed if you want MCP server integration +- **Git** - Helpful for development workflows + +### Quick Check 🔍 + +Before installing, let's make sure you have the basics: + +```bash +# Check Python version (should be 3.8+) +python3 --version + +# Check if Claude Code is available +claude --version + +# Check Node.js (optional, for MCP servers) +node --version +``` + +If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below. + +## Installation Options 🎛️ + +### 🎯 Interactive Installation (Default - Recommended) +```bash +SuperClaude install +``` +- **Stage 1**: Select MCP servers (Context7, Sequential, Magic, Playwright, etc.) +- **Stage 2**: Choose framework components (Core, Commands, Agents, Modes) +- **Time**: ~3-5 minutes depending on selections +- **Space**: ~50-100MB depending on selections +- **Good for**: All users - gives you full control over what gets installed +- **Interactive**: Shows detailed descriptions and lets you pick exactly what you want + +### ⚡ Component-Specific Installation +```bash +SuperClaude install --components core commands modes +``` +- **What**: Install only specific components you need +- **Available components**: core, commands, agents, modes, mcp, mcp_docs +- **Good for**: Users who know exactly what they want + +### 🔍 Other Useful Options +```bash +# See all available components +SuperClaude install --list-components + +# See what would be installed without doing it +SuperClaude install --dry-run + +# System diagnostics and installation help +SuperClaude install --diagnose + +# Quiet installation (minimal output) +SuperClaude install --quiet + +# Install everything +SuperClaude install --components all +``` + +## Step-by-Step Installation 📋 + +### Prerequisites Setup 🛠️ + +**Missing Python?** +```bash +# Linux (Ubuntu/Debian) +sudo apt update && sudo apt install python3 python3-pip + +# macOS +brew install python3 + +# Windows +# Download from https://python.org/downloads/ +# Or use winget +winget install python +``` + +**Missing Claude Code?** +- Visit https://claude.ai/code for installation instructions +- SuperClaude enhances Claude Code, so you need it first + +**Missing Node.js? (Optional)** +```bash +# Linux (Ubuntu/Debian) +sudo apt update && sudo apt install nodejs npm + +# macOS +brew install node + +# Windows +# Download from https://nodejs.org/ +# Or use winget +winget install nodejs +``` + +### Getting SuperClaude 📥 + +**Option 1: From PyPI (Recommended)** +```bash +pip install SuperClaude +``` + +**Option 2: Clone from Git** +```bash +git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git +cd SuperClaude_Framework +pip install . +``` + +### Running the Installer 🎬 + +The installer is smart and will guide you through the process: + +```bash +# See all available options +SuperClaude install --help + +# Interactive installation (recommended) +SuperClaude install + +# Want to see what would happen first? +SuperClaude install --dry-run + +# Install specific components +SuperClaude install --components core commands agents modes + +# Quiet installation (minimal output) +SuperClaude install --quiet +``` + +### During Installation 📱 + +Here's what happens when you install: + +1. **System Check** - Verifies you have required dependencies +2. **Component Selection** - Interactive selection of what to install +3. **MCP Server Setup** - Downloads and configures MCP servers (if selected) +4. **API Key Collection** - Prompts for required API keys for selected servers +5. **Framework Installation** - Copies framework documentation files +6. **Configuration Setup** - Creates settings and CLAUDE.md imports +7. **Validation** - Tests that everything works + +The installer shows progress and will tell you if anything goes wrong. + +## After Installation ✅ + +### Quick Test 🧪 + +Let's make sure everything worked: + +```bash +# Check if files were installed +ls ~/.claude/ + +# Should show: CLAUDE.md, RULES.md, PRINCIPLES.md, etc. +``` + +**Test with Claude Code:** +1. Open Claude Code +2. Try typing `/sc:help` - you should see SuperClaude commands +3. Try `/sc:analyze --help` - should show command options + +### What Got Installed 📂 + +SuperClaude installs to `~/.claude/` by default. Here's what you'll find: + +``` +~/.claude/ +├── CLAUDE.md # Main framework entry point +├── FLAGS.md # Command flags and options +├── PRINCIPLES.md # Development principles +├── RULES.md # Operational rules +├── MCP_*.md # MCP server configurations +├── MODE_*.md # Behavioral modes +├── settings.json # Configuration file (if created) +└── SuperClaude/ # Framework components + ├── Core/ # Core framework files + ├── Commands/ # 21 command definitions + ├── Agents/ # 13 specialized agents + ├── Modes/ # 5 behavioral modes + └── MCP/ # MCP server configurations +``` + +**What each file does:** +- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files +- **RULES.md** - Operational rules and workflow patterns +- **PRINCIPLES.md** - Development principles and decision frameworks +- **FLAGS.md** - Command flags and behavioral controls +- **SuperClaude/** - Complete framework with commands, agents, and modes + +### First Steps 🎯 + +Try these commands to get started: + +```bash +# In Claude Code, try these: +/sc:help # See available commands +/sc:analyze README.md # Analyze a file +/sc:build --help # See build options +/sc:improve --help # See improvement options +/sc:brainstorm "my app idea" # Try brainstorming mode +/sc:load # Initialize session with context +``` + +**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want. + +## Managing Your Installation 🛠️ + +### Updates 📅 + +Keep SuperClaude up to date: + +```bash +# Update the package +pip install --upgrade SuperClaude + +# Reinstall components +SuperClaude install --force + +# Update specific components only +SuperClaude install --components core commands --force +``` + +### Backups 💾 + +SuperClaude automatically creates backups during installation. You can also create manual backups of your `~/.claude/` directory: + +```bash +# Create a backup +cp -r ~/.claude/ ~/.claude_backup_$(date +%Y%m%d) + +# Restore from backup +rm -rf ~/.claude/ +cp -r ~/.claude_backup_20250115/ ~/.claude/ +``` + +### Uninstallation 🗑️ + +If you need to remove SuperClaude: + +```bash +# Remove just the package +pip uninstall SuperClaude + +# Remove all SuperClaude files (keeps your other Claude settings) +rm -rf ~/.claude/SuperClaude/ +rm -f ~/.claude/CLAUDE.md ~/.claude/RULES.md ~/.claude/PRINCIPLES.md ~/.claude/FLAGS.md +rm -f ~/.claude/MCP_*.md ~/.claude/MODE_*.md +``` + +**What gets removed:** +- All SuperClaude files in `~/.claude/` +- The SuperClaude Python package + +**What stays:** +- Your other Claude Code settings +- Your projects and other files +- Any backups you created + +## Troubleshooting 🔧 + +### Common Issues 🚨 + +**"Python not found"** +```bash +# Try python instead of python3 +python --version + +# Or check if it's installed but not in PATH +which python3 +``` + +**"Claude Code not found"** +- Make sure Claude Code is installed first +- Visit https://claude.ai/code for installation help + +**"Permission denied"** +```bash +# Try with explicit Python path +/usr/bin/python3 -m SuperClaude install + +# Or check if you need different permissions +ls -la ~/.claude/ +``` + +**"MCP servers won't install"** +- Check that Node.js is installed: `node --version` +- Check that npm is available: `npm --version` +- Try installing without MCP first: select "Skip MCP Server installation" during interactive setup + +**"Installation fails partway through"** +```bash +# Try with verbose output to see what's happening +SuperClaude install --verbose + +# Or try a dry run first +SuperClaude install --dry-run + +# Try system diagnostics +SuperClaude install --diagnose +``` + +### Platform-Specific Issues 🖥️ + +**Windows:** +- Use `python` instead of `python3` if you get "command not found" +- Run Command Prompt as Administrator if you get permission errors +- Make sure Python is in your PATH + +**macOS:** +- You might need to approve SuperClaude in Security & Privacy settings +- Use `brew install python3` if you don't have Python 3.8+ +- Try using `python3` explicitly instead of `python` + +**Linux:** +- Make sure you have `python3-pip` installed +- You might need `sudo` for some package installations +- Check that `~/.local/bin` is in your PATH + +### Still Having Issues? 🤔 + +**Check our troubleshooting resources:** +- GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues +- Look for existing issues similar to yours +- Create a new issue if you can't find a solution + +**When reporting bugs, please include:** +- Your operating system and version +- Python version (`python3 --version`) +- Claude Code version (`claude --version`) +- The exact command you ran +- The complete error message +- What you expected to happen + +## Advanced Options ⚙️ + +### Custom Installation Directory +```bash +# Install to custom location +SuperClaude install --install-dir /custom/path + +# Use environment variable +export SUPERCLAUDE_DIR=/custom/path +SuperClaude install +``` + +### Development Setup + +If you're planning to contribute or modify SuperClaude: + +```bash +# Clone the repository +git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git +cd SuperClaude_Framework + +# Install in development mode +pip install -e . + +# Install all components +SuperClaude install --components all +``` + +## What's Next? 🚀 + +**Now that SuperClaude is installed:** + +1. **Just start using it** - Try `/sc:analyze some-file.js` or `/sc:build` and see what happens ✨ +2. **Don't stress about learning** - SuperClaude usually figures out what you need +3. **Experiment freely** - Commands like `/sc:improve` and `/sc:troubleshoot` are pretty forgiving +4. **Use session management** - Try `/sc:load` and `/sc:save` for persistent context +5. **Explore behavioral modes** - Let SuperClaude adapt to your workflow automatically +6. **Give feedback** - Let us know what works and what doesn't + +**The real secret**: SuperClaude is designed to enhance your existing workflow without you having to learn a bunch of new stuff. Just use it like you'd use regular Claude Code, but notice how much smarter it gets! 🎯 + +**Still feeling uncertain?** Start with just `/sc:help` and `/sc:analyze README.md` - you'll see how approachable it actually is. + +--- + +## Final Notes 📝 + +- **Installation takes 1-5 minutes** depending on what you choose +- **Disk space needed: 20-100MB** (not much!) +- **Works alongside existing tools** - doesn't interfere with your setup +- **Easy to uninstall** if you change your mind +- **Community supported** - we actively read and respond to issues +- **Available commands**: Use `SuperClaude [command]`, `python3 -m SuperClaude [command]`, or `/sc:[command]` in Claude Code + +Thanks for trying SuperClaude! We hope it makes your development workflow smoother and more intelligent. 🙂 + +--- + +*Last updated: August 2025 - Let us know if anything in this guide is wrong or confusing!* \ No newline at end of file diff --git a/Docs/superclaude-user-guide.md b/Guides/superclaude-user-guide.md similarity index 80% rename from Docs/superclaude-user-guide.md rename to Guides/superclaude-user-guide.md index 93ffae0..2255014 100644 --- a/Docs/superclaude-user-guide.md +++ b/Guides/superclaude-user-guide.md @@ -4,7 +4,7 @@ **Behind the apparent complexity, SuperClaude is actually simple to use.** -You don't need to learn all the commands, flags, and personas. Just start using it! 🎈 +You don't need to learn all the commands, flags, and agents. Just start using it! 🎈 SuperClaude has an **intelligent routing system** that tries to figure out what you need: - Type `/analyze some-code/` → It picks the right analysis tools @@ -22,13 +22,13 @@ The detailed guides below? They're here **when you want to understand** what jus --- -A comprehensive guide to understanding and using SuperClaude V4 Beta effectively. But remember - you can skip straight to trying it out! +A comprehensive guide to understanding and using SuperClaude v4.0.0 effectively. But remember - you can skip straight to trying it out! ## Table of Contents 📖 1. [Welcome & Overview](#welcome--overview-) 2. [Core Components](#core-components-) -3. [The Four Behavioral Modes](#the-four-behavioral-modes-) +3. [The Five Behavioral Modes](#the-five-behavioral-modes-) 4. [Session Lifecycle System](#session-lifecycle-system-) 5. [The Orchestrator System](#the-orchestrator-system-) 6. [Rules & Principles](#rules--principles-) @@ -76,7 +76,7 @@ Want to understand how it works? Keep reading. Want to just keep experimenting? SuperClaude makes Claude Code smarter for development work. Instead of generic responses, you get specialized help from different agents (security, performance, frontend, etc.) who know their stuff, plus session persistence and behavioral intelligence. -**The honest truth**: V4 Beta represents a major architectural evolution with new session lifecycle management, behavioral modes, and an advanced hooks system. While still in beta, it's significantly more capable than v3, with better context management and intelligent agent coordination. +**The honest truth**: SuperClaude v4.0.0 represents a major architectural evolution with new session lifecycle management and behavioral modes. It's significantly more capable than v3, with better context management and intelligent agent coordination. **The neat part?** You don't need to manage any of this complexity. Just use normal commands like `/analyze` or `/build` and SuperClaude usually figures out which experts to involve and what tools to use. 🪄 @@ -90,15 +90,15 @@ SuperClaude makes Claude Code smarter for development work. Instead of generic r - **Session tools**: `/load` (NEW!), `/save` (NEW!), `/reflect` (NEW!) - **Plus utilities** for documentation, git, deployment, and more - **You just use them** - SuperClaude handles the complexity automatically -- **V4 NEW**: Session lifecycle commands for persistent context -- **V4 NEW**: Interactive brainstorming and reflection capabilities +- **v4.0.0 NEW**: Session lifecycle commands for persistent context +- **v4.0.0 NEW**: Interactive brainstorming and reflection capabilities **🤖 13 Specialized Agents** *(that know when to jump in)* - AI agents that adapt behavior for different domains - **Auto-activate based on your requests** (security agent for security tasks, etc.) - Manual control available, but usually not needed - Think of it as having a whole dev team that knows when to help -- **V4 NEW**: Enhanced agent system with better specialization +- **v4.0.0 NEW**: Enhanced agent system with better specialization **🔧 MCP Server Integration** *(6 smart external tools)* - **Context7**: Official library documentation lookup @@ -109,11 +109,12 @@ SuperClaude makes Claude Code smarter for development work. Instead of generic r - **Serena**: Semantic code analysis and memory (NEW!) - **Auto-connects when needed** - you don't manage this stuff -**🧠 4 Behavioral Modes** *(intelligent adaptation)* +**🧠 5 Behavioral Modes** *(intelligent adaptation)* - **Brainstorming Mode**: Interactive requirements discovery (NEW!) - **Introspection Mode**: Meta-cognitive analysis and debugging (NEW!) -- **Task Management Mode**: Multi-layer orchestration with wave systems (NEW!) +- **Task Management Mode**: Multi-layer orchestration and systematic delegation (NEW!) - **Token Efficiency Mode**: Smart compression and optimization (NEW!) +- **Orchestration Mode**: Intelligent tool selection and resource efficiency (NEW!) - **Auto-activate based on context** - you don't configure them **🏗️ Session Lifecycle System** *(persistent intelligence)* @@ -123,38 +124,29 @@ SuperClaude makes Claude Code smarter for development work. Instead of generic r - Session reflection and insights with `/sc:reflect` (NEW!) - **Cross-session learning** - SuperClaude remembers and improves -**🔌 Hooks System** *(extensible architecture)* -- Performance monitoring and optimization (NEW!) -- Quality gates with 8-step validation (NEW!) -- Framework coordination and orchestration (NEW!) -- Session lifecycle integration (NEW!) -- **SuperClaude-Lite** variant for streamlined usage (NEW!) - -### Current Status (V4 Beta) 📊 +### Current Status (v4.0.0) 📊 **✅ What's Working Well:** - Complete session lifecycle with persistent memory - 21 commands including new brainstorming and reflection tools - 13 specialized agents with enhanced coordination - 6 MCP servers with Morphllm and Serena integration -- 4 behavioral modes with intelligent auto-activation -- Advanced hooks system with performance monitoring -- SuperClaude-Lite for streamlined workflows +- 5 behavioral modes with intelligent auto-activation -**⚠️ What's Still Beta:** -- Session persistence optimization (performance tuning ongoing) -- Behavioral mode coordination (refining trigger patterns) -- Hooks system reliability (extensive testing in progress) -- Agent handoff protocols (improving seamless transitions) +**🎯 Stable & Production Ready:** +- All core functionality tested and validated +- Session persistence optimized for performance +- Behavioral modes with refined trigger patterns +- Robust framework components with comprehensive validation +- Seamless agent handoff protocols **🚀 Major V4 Improvements:** - **Session Intelligence**: Persistent context across sessions - **Behavioral Modes**: Adaptive intelligence based on task type - **Enhanced Memory**: Cross-session learning and pattern recognition - **Advanced Orchestration**: Multi-layer task coordination -- **Extensible Architecture**: Robust hooks system for customization -V4 Beta represents a significant architectural evolution with much more sophisticated context management and intelligent coordination. +SuperClaude v4.0.0 represents a significant architectural evolution with much more sophisticated context management and intelligent coordination. ### How It Works 🔄 @@ -179,7 +171,7 @@ The nice thing is that most of this usually happens automatically. You make a re | **Flags** | Modifiers that mostly activate automatically | [Flags Guide](flags-guide.md) | | **Agents** | 13 AI specialists that know when to help | [This guide](#agents-ai-specialists-) | | **MCP Servers** | 6 external integrations that connect when useful | [This guide](#mcp-servers-external-capabilities-) | -| **Behavioral Modes** | 4 adaptive modes for different workflows | [This guide](#the-four-behavioral-modes-) | +| **Behavioral Modes** | 5 adaptive modes for different workflows | [This guide](#the-five-behavioral-modes-) | | **Session Lifecycle** | Persistent context across sessions | [This guide](#session-lifecycle-system-) | | **Orchestrator** | The smart routing that makes it all work | [This guide](#the-orchestrator-system-) | @@ -212,7 +204,7 @@ Commands are specialized tools that handle specific types of development work. I - `/cleanup` - Technical debt reduction - `/test` - Testing and coverage analysis -**Session Management** 🧠 *(NEW in V4!)* +**Session Management** 🧠 *(NEW in v4.0.0!)* - `/load` - Initialize session with persistent context - `/save` - Save session state and insights - `/reflect` - Task validation and completion analysis @@ -229,7 +221,7 @@ Commands are specialized tools that handle specific types of development work. I - `/spawn` - Complex operation orchestration - `/index` - Command navigation and help -Each command has its own flags, auto-activates appropriate personas, and integrates with relevant MCP servers. For detailed examples and usage patterns, see the [Commands Guide](commands-guide.md). +Each command has its own flags, auto-activates appropriate agents, and integrates with relevant MCP servers. For detailed examples and usage patterns, see the [Commands Guide](commands-guide.md). ### Flags: Behavior Modifiers 🏁 @@ -254,19 +246,19 @@ Flags change how SuperClaude processes your requests. They're like command-line **Advanced Orchestration** 🎭 - `--delegate` - Enable sub-agent delegation for parallel processing -- `--wave-mode` - Multi-stage execution with compound intelligence +- `--delegate` - Enable sub-agent delegation for systematic execution - `--loop` - Iterative improvement mode **Focus & Scope** 🎯 - `--focus security` - Focus on specific domains - `--scope project` - Set analysis scope -- `--persona-[name]` - Activate specific personas +- `--agent-[name]` - Activate specific agents -Flags often auto-activate based on context. For example, security-related requests usually get `--persona-security` and `--focus security`. See the [Flags Guide](flags-guide.md) for comprehensive details and patterns. +Flags often auto-activate based on context. For example, security-related requests usually get `--agent-security` and `--focus security`. See the [Flags Guide](flags-guide.md) for comprehensive details and patterns. ### Agents: AI Specialists 🤖 -Agents are like having a team of specialists available on demand. Each brings different expertise, priorities, and approaches to problems. V4 Beta features an enhanced agent system with better specialization and coordination. +Agents are like having a team of specialists available on demand. Each brings different expertise, priorities, and approaches to problems. SuperClaude v4.0.0 features an enhanced agent system with better specialization and coordination. **13 Agents Organized by Domain:** @@ -278,20 +270,20 @@ Agents are like having a team of specialists available on demand. Each brings di - ⚡ **performance** - Optimization, bottleneck elimination **Process & Quality** ✨ -- 🔍 **analyzer** - Root cause analysis, investigation -- 🧪 **qa** - Testing, quality assurance -- 🔄 **refactorer** - Code quality, technical debt -- 🚀 **devops** - Infrastructure, deployment +- 🔍 **root-cause-analyst** - Root cause analysis, investigation +- 🧪 **quality-engineer** - Testing, quality assurance +- 🔄 **refactoring-expert** - Code quality, technical debt +- 🚀 **devops-architect** - Infrastructure, deployment **Knowledge & Communication** 📚 -- 👨‍🏫 **mentor** - Education, knowledge transfer -- ✍️ **scribe** - Documentation, technical writing +- 👨‍🏫 **learning-guide** - Education, knowledge transfer +- ✍️ **technical-writer** - Documentation, technical writing -**V4 Beta Enhancements** 🆕 -- 🎯 **brainstorm-PRD** - Requirements analysis and PRD generation *(NEW!)* +**v4.0.0 Enhancements** 🆕 +- 🎯 **requirements-analyst** - Requirements analysis and PRD generation *(NEW!)* - 🔮 **workflow-agent** - Advanced workflow orchestration *(NEW!)* -Agents usually auto-activate based on request patterns but you can override with `--agent-[name]` flags. Each has different priorities (e.g., security agent prioritizes security over speed). V4 Beta improves agent handoff and coordination patterns. +Agents usually auto-activate based on request patterns but you can override with `--agent-[name]` flags. Each has different priorities (e.g., security agent prioritizes security over speed). SuperClaude v4.0.0 improves agent handoff and coordination patterns. ### MCP Servers: External Capabilities 🔧 @@ -323,13 +315,13 @@ MCP (Model Context Protocol) servers provide specialized capabilities beyond Cla - **What it provides**: Cross-browser testing, visual validation, metrics - **Example**: `/test e2e --play` runs comprehensive browser tests -**Morphllm** 🔧 *(NEW in V4!)* +**Morphllm** 🔧 *(NEW in v4.0.0!)* - **Purpose**: Intelligent file editing with Fast Apply capability - **When it activates**: Complex refactoring, multi-file edits - **What it provides**: Context-aware code modifications, pattern transformations - **Example**: `/improve legacy-code/ --morph` applies intelligent refactoring -**Serena** 🧠 *(NEW in V4!)* +**Serena** 🧠 *(NEW in v4.0.0!)* - **Purpose**: Semantic code analysis and persistent memory - **When it activates**: Project analysis, session persistence, memory operations - **What it provides**: Cross-session context, semantic understanding, project memory @@ -359,9 +351,9 @@ This coordination usually happens for most requests - SuperClaude tries to figur --- -## The Four Behavioral Modes 🧠 +## The Five Behavioral Modes 🧠 -SuperClaude V4 Beta features four intelligent behavioral modes that automatically adapt to different types of work. These modes provide specialized behavior patterns while maintaining the same command interface. +SuperClaude v4.0.0 features five intelligent behavioral modes that automatically adapt to different types of work. These modes provide specialized behavior patterns while maintaining the same command interface. ### 1. Brainstorming Mode 🎯 *(NEW!)* @@ -405,13 +397,13 @@ SuperClaude V4 Beta features four intelligent behavioral modes that automaticall ### 3. Task Management Mode 📋 -**What it is**: Multi-layer orchestration with wave systems and advanced delegation. +**What it is**: Multi-layer orchestration with systematic delegation and progressive enhancement. **When it activates**: Multi-step operations, complex projects, large-scale work. **How it works**: - Four-layer task hierarchy (Session → Project → Orchestration → Iterative) -- Wave orchestration for compound intelligence +- Progressive orchestration for systematic enhancement - Sub-agent delegation for parallel processing - Real-time analytics and performance monitoring @@ -488,11 +480,40 @@ SuperClaude V4 Beta features four intelligent behavioral modes that automaticall - **Selective Compression**: Framework content preserved, operational data compressed - **Quality Validation**: Real-time monitoring of information preservation +### 5. Orchestration Mode 🎭 *(NEW!)* + +**What it is**: Intelligent tool selection and resource efficiency optimization for optimal task routing. + +**When it activates**: Multi-tool operations, performance constraints, parallel execution opportunities. + +**How it works**: +- Smart tool selection matrix for optimal efficiency +- Resource awareness and adaptive approach selection +- Parallel thinking for concurrent execution identification +- Performance optimization based on system constraints + +**Example Features**: +```bash +# Automatically selects best tools for each task +/sc:build complex-app/ +# → Magic MCP for UI components +# → Context7 for framework patterns +# → Playwright for testing validation +# → Parallel execution where possible +``` + +**Tool Selection Intelligence**: +- **UI Components**: Magic MCP over manual coding +- **Deep Analysis**: Sequential MCP over native reasoning +- **Symbol Operations**: Serena MCP over manual search +- **Documentation**: Context7 MCP over web search +- **Multi-file Edits**: MultiEdit over sequential operations + --- -## Session Lifecycle System 🏗️ *(NEW in V4!)* +## Session Lifecycle System 🏗️ *(NEW in v4.0.0!)* -SuperClaude V4 Beta introduces persistent session management that remembers your work across multiple sessions, enabling continuous learning and context preservation. +SuperClaude v4.0.0 introduces persistent session management that remembers your work across multiple sessions, enabling continuous learning and context preservation. ### Core Concept @@ -565,21 +586,82 @@ SuperClaude automatically creates checkpoints: ### Session Memory Organization ``` -memories/ -├── session/ -│ ├── current # Latest session -│ ├── {timestamp} # Individual sessions -│ └── history/ # Archived sessions -├── checkpoints/ -│ ├── latest # Latest checkpoint -│ ├── {timestamp} # Individual checkpoints -│ └── task-{id} # Task-specific checkpoints -├── summaries/ -│ ├── daily/{date} # Daily summaries -│ └── insights/{topic} # Topical insights -└── project_state/ - ├── context_enhanced # Accumulated context - └── decisions_log # Architecture decisions +Session Memory Organization + +SuperClaude v4.0.0 implements a sophisticated dual-layer memory system that enables +persistent learning and context preservation across sessions: + +~/.claude/ # Global behavioral configuration +├── 🧠 Core Behavioral Files +│ ├── CLAUDE.md # Master configuration & MCP coordination +│ ├── FLAGS.md # Behavioral flags & execution modes +│ ├── RULES.md # Operational rules & quality gates +│ └── PRINCIPLES.md # Engineering principles & philosophy +├── 🔧 MCP Server Configurations +│ ├── MCP_Context7.md # Documentation lookup & pattern guidance +│ ├── MCP_Magic.md # UI component generation (21st.dev) +│ ├── MCP_Morphllm.md # Pattern-based code transformations +│ ├── MCP_Playwright.md # Browser automation & E2E testing +│ ├── MCP_Sequential.md # Multi-step reasoning & analysis +│ └── MCP_Serena.md # Semantic understanding & project memory +└── 🎭 Behavioral Mode Definitions + ├── MODE_Brainstorming.md # Interactive discovery & ideation + ├── MODE_Introspection.md # Meta-cognitive analysis & reflection + ├── MODE_Orchestration.md # Tool selection & resource optimization + ├── MODE_Task_Management.md # Multi-layer orchestration & delegation + └── MODE_Token_Efficiency.md # Symbol-enhanced communication + +~/.serena/ # Project-specific session persistence +├── 📂 sessions/ # Session checkpoint storage +│ ├── project-{hash}/ # Project-specific session data +│ │ ├── checkpoints/ # Automatic checkpoint creation +│ │ │ ├── {timestamp}-task.json # Task completion checkpoints +│ │ │ ├── {timestamp}-time.json # 30-minute automatic saves +│ │ │ └── {timestamp}-risk.json # Pre-operation safety saves +│ │ ├── context.json # Current session context +│ │ └── metadata.json # Session configuration & preferences +├── 🧠 context/ # Cross-session project understanding +│ ├── project-{hash}/ # Project-specific learning data +│ │ ├── architecture.json # System architecture understanding +│ │ ├── patterns.json # Recognized code patterns & styles +│ │ ├── decisions.json # Historical decisions & rationale +│ │ └── dependencies.json # Dependency relationships & history +├── 💡 memory/ # Long-term learning & insights +│ ├── successful_patterns.json # Proven approaches & solutions +│ ├── error_patterns.json # Common mistakes & prevention +│ ├── optimization_history.json # Performance improvements made +│ └── preference_learning.json # User preferences & working styles +└── 🔍 patterns/ # Pattern recognition & reuse + ├── code_patterns/ # Reusable code structures + ├── workflow_patterns/ # Effective development workflows + ├── problem_patterns/ # Common problems & solutions + └── integration_patterns/ # Integration approaches & configs + +Memory Flow & Learning Process: + +1. Session Initialization (/sc:load) + └── Loads: ~/.claude/* + ~/.serena/sessions/current + ~/.serena/context/project + +2. Active Work Session + ├── Continuous context building in memory + ├── Pattern recognition across operations + └── Automatic checkpointing (task/time/risk triggers) + +3. Session Persistence (/sc:save) + ├── Context serialization to ~/.serena/sessions/ + ├── Pattern extraction to ~/.serena/patterns/ + ├── Learning insights to ~/.serena/memory/ + └── Project understanding to ~/.serena/context/ + +4. Cross-Session Learning + ├── Pattern reuse from previous sessions + ├── Architecture understanding builds over time + ├── Preference learning adapts behavior + └── Error prevention through historical analysis + +This dual-layer approach ensures that SuperClaude becomes more effective over time, +building project-specific expertise while maintaining consistent behavioral patterns +across all development work. ``` ### Benefits @@ -601,179 +683,15 @@ memories/ --- -## Hooks System & SuperClaude-Lite 🔌 *(NEW in V4!)* - -V4 Beta introduces an advanced hooks system for extensibility and SuperClaude-Lite for streamlined workflows. - -### Hooks System Architecture - -**8-Step Quality Gates** -1. **Syntax Validation**: Language-specific syntax checking -2. **Type Analysis**: Type compatibility and inference -3. **Code Quality**: Linting rules and quality standards -4. **Security Assessment**: Vulnerability analysis and compliance -5. **E2E Testing**: End-to-end test execution and validation -6. **Performance Analysis**: Performance benchmarking and optimization -7. **Documentation**: Documentation completeness and accuracy -8. **Integration Testing**: Deployment and cross-browser validation - -**Performance Monitoring** -- Real-time operation timing and resource usage -- Automatic performance optimization suggestions -- Bottleneck detection and resolution -- Quality preservation metrics - -**Framework Coordination** -- Seamless integration with all SuperClaude components -- Session lifecycle management and checkpointing -- Cross-mode behavioral coordination -- MCP server orchestration - -### SuperClaude-Lite Variant - -**What it is**: Streamlined version of SuperClaude optimized for specific workflows. - -**Key Features**: -- **Reduced complexity**: Simplified command set focused on core functionality -- **Faster performance**: Optimized for speed with minimal overhead -- **Targeted use cases**: Specialized for quick analysis, code review, and documentation -- **Easy deployment**: Lighter installation with fewer dependencies - -**When to use SuperClaude-Lite**: -- Quick code reviews and analysis -- Documentation generation workflows -- Performance-critical environments -- Teams wanting focused functionality -- CI/CD pipeline integration - -**Relationship to Full SuperClaude**: -- Shares core architecture and quality standards -- Compatible session formats and memory systems -- Can upgrade to full SuperClaude when needed -- Maintains behavioral consistency -- Considers alternative approaches -- Identifies optimization opportunities - -**Framework Compliance Check** 🔍 -- Validates actions against SuperClaude rules and principles -- Identifies deviations from standard patterns -- Provides corrective guidance when needed -- Ensures quality standards are met - -**Learning Recognition** 💡 -- Extracts insights from outcomes -- Identifies successful patterns for reuse -- Recognizes knowledge gaps for improvement -- Suggests future optimization strategies - -#### Analysis Markers - -When introspection mode is active, you'll see these markers: - -- 🧠 **Reasoning Analysis** - Examining logical flow and decisions -- 🔄 **Action Sequence Review** - Analyzing workflow effectiveness -- 🎯 **Self-Assessment** - Meta-cognitive evaluation -- 📊 **Pattern Recognition** - Identifying behavioral patterns -- 🔍 **Framework Compliance** - Checking rule adherence -- 💡 **Retrospective Insight** - Learning from outcomes - -#### When Introspection Activates - -**Usually activates for**: -- Complex multi-step problems requiring meta-cognitive oversight -- Error recovery when outcomes don't match expectations -- Framework discussions or SuperClaude troubleshooting -- Pattern recognition needs for recurring behaviors - -**Manual activation**: -```bash -/sc:analyze complex-system/ --introspect -/sc:troubleshoot "framework confusion" --introspection -``` - -### Token Efficiency Mode ⚡ - -**What it is**: Intelligent optimization system that maximizes information density while preserving quality. - -**When it's used**: Large operations, when context approaches limits, or when you need faster execution. - -**How it works**: Adaptive compression using symbols, abbreviations, and structural optimization based on context and persona awareness. - -#### Compression Strategies - -**5-Level Adaptive Compression**: -1. **Minimal** (0-40% usage): Full detail with persona-optimized clarity -2. **Efficient** (40-70% usage): Balanced compression with domain awareness -3. **Compressed** (70-85% usage): Aggressive optimization with quality gates -4. **Critical** (85-95% usage): Maximum compression preserving essential context -5. **Emergency** (95%+ usage): Ultra-compression with information validation - -#### Symbol System - -**Core Logic & Flow**: -- `→` leads to, implies (`auth.js:45 → security risk`) -- `⇒` transforms to (`input ⇒ validated_output`) -- `&` and, combine (`security & performance`) -- `»` sequence, then (`build » test » deploy`) -- `∴` therefore (`tests fail ∴ code broken`) - -**Status & Progress**: -- ✅ completed, passed -- ❌ failed, error -- ⚠️ warning -- 🔄 in progress -- 🎯 target, goal - -**Technical Domains**: -- ⚡ Performance -- 🔍 Analysis -- 🛡️ Security -- 📦 Deployment -- 🎨 Design - -#### Activation Strategy - -**Usually activates when**: -- Context usage >75% → Enables compression -- Large-scale operations → Prevents token overflow -- Complex orchestration → Optimizes communication - -**Manual activation**: -```bash -/sc:analyze huge-codebase/ --uc # Ultra-compressed mode -/sc:improve legacy-system/ --uc --delegate auto # Efficient large operations -``` - -**Performance Goals** (still improving!): -- Target: ~30-50% token reduction -- Quality: Tries to preserve ~95% of information -- Speed: Usually <100ms compression decisions -- Integration: Works with framework components - -#### Mode Integration - -The three modes often work together: - -```bash -/sc:improve large-legacy-system/ --wave-mode auto --uc --introspect -``` - -**What happens**: -- **Task Management**: Creates structured improvement plan with progress tracking -- **Token Efficiency**: Compresses output for large-scale operation -- **Introspection**: Analyzes improvement strategy and validates approach - ---- - ## The Orchestrator System 🎯 -The orchestrator is SuperClaude's intelligent routing system that tries to analyze your requests and coordinate a good combination of tools, personas, and integrations. It's what hopefully makes SuperClaude feel smart and responsive rather than just a collection of separate tools. +The orchestrator is SuperClaude's intelligent routing system that tries to analyze your requests and coordinate a good combination of tools, agents, and integrations. It's what hopefully makes SuperClaude feel smart and responsive rather than just a collection of separate tools. ### How the Orchestrator Works 🔄 **Think of it as a smart dispatcher** that: 1. **Analyzes** your request to understand intent and complexity -2. **Routes** to the best combination of commands, flags, personas, and MCP servers +2. **Routes** to the best combination of commands, flags, agents, and MCP servers 3. **Coordinates** execution for optimal results 4. **Validates** through quality gates to ensure good outcomes 5. **Optimizes** performance and resource usage @@ -790,29 +708,29 @@ The detection engine analyzes every request through multiple lenses: - **Complex**: System-wide changes, architectural decisions (>10 steps) → Advanced orchestration **Domain Identification**: -- **Frontend**: Keywords like "UI", "component", "responsive" → 🎨 frontend persona + Magic MCP -- **Backend**: Keywords like "API", "database", "service" → ⚙️ backend persona + Context7 MCP -- **Security**: Keywords like "vulnerability", "auth", "compliance" → 🛡️ security persona + Sequential MCP -- **Performance**: Keywords like "slow", "optimize", "bottleneck" → ⚡ performance persona + Playwright MCP +- **Frontend**: Keywords like "UI", "component", "responsive" → 🎨 frontend agent + Magic MCP +- **Backend**: Keywords like "API", "database", "service" → ⚙️ backend agent + Context7 MCP +- **Security**: Keywords like "vulnerability", "auth", "compliance" → 🛡️ security agent + Sequential MCP +- **Performance**: Keywords like "slow", "optimize", "bottleneck" → ⚡ performance agent + Playwright MCP **Operation Type Classification**: -- **Analysis**: "analyze", "review", "understand" → Sequential MCP + analyzer persona +- **Analysis**: "analyze", "review", "understand" → Sequential MCP + root-cause-analyst agent - **Creation**: "create", "build", "implement" → Magic MCP (if UI) or Context7 (patterns) -- **Modification**: "improve", "refactor", "optimize" → Appropriate specialist persona -- **Debugging**: "troubleshoot", "fix", "debug" → Sequential MCP + analyzer persona +- **Modification**: "improve", "refactor", "optimize" → Appropriate specialist agent +- **Debugging**: "troubleshoot", "fix", "debug" → Sequential MCP + root-cause-analyst agent #### Auto-Activation Logic **High-Confidence Triggers** (90%+ activation): ```bash /sc:analyze auth-system/ --focus security -# → 🛡️ security persona + Sequential MCP + --validate flag +# → 🛡️ security agent + Sequential MCP + --validate flag ``` **Context-Based Activation**: ```bash /sc:build react-components/ -# → 🎨 frontend persona + Magic MCP + --c7 flag (React docs) +# → 🎨 frontend agent + Magic MCP + --c7 flag (React docs) ``` **Performance-Based Activation**: @@ -833,7 +751,7 @@ The routing system uses dynamic decision trees to map detected patterns to optim | "analyze architecture" | 🏗️ architect + --ultrathink + Sequential | Most times | Complex system analysis | | "create UI component" | 🎨 frontend + Magic + --uc | Pretty often | Frontend domain with generation | | "security audit" | 🛡️ security + --ultrathink + Sequential | Most times | Security expertise needed | -| "debug complex issue" | 🔍 analyzer + --think + Sequential | Often | Investigation methodology | +| "debug complex issue" | 🔍 root-cause-analyst + --think + Sequential | Often | Investigation methodology | | "improve performance" | ⚡ performance + --think-hard + Playwright | Pretty often | Performance expertise + testing | #### Intelligent Coordination @@ -843,8 +761,8 @@ The routing system uses dynamic decision trees to map detected patterns to optim /sc:design user-dashboard --type api ``` **Orchestrator usually coordinates**: -- 🏗️ architect persona (system design) -- 🎨 frontend persona (UI design) +- 🏗️ architect agent (system design) +- 🎨 frontend agent (UI design) - Context7 MCP (framework patterns) - Sequential MCP (design methodology) @@ -907,11 +825,11 @@ The orchestrator tries to optimize for good performance through several strategi # → --delegate auto flag + parallel processing ``` -**Wave Orchestration**: +**Progressive Orchestration**: ```bash # Auto-activates when complexity >0.7 + files >20 + operation types >2 /sc:improve legacy-system/ -# → --wave-mode auto + multi-stage execution +# → --delegate auto + multi-stage execution ``` ### Real-World Orchestration Examples 💡 @@ -927,7 +845,7 @@ The orchestrator tries to optimize for good performance through several strategi - Operation: Analysis + scanning **Usually coordinates**: -- 🛡️ security persona (threat modeling perspective) +- 🛡️ security agent (threat modeling perspective) - Sequential MCP (systematic analysis) - --validate flag (pre-operation safety check) - --think flag (complex security patterns) @@ -945,8 +863,8 @@ The orchestrator tries to optimize for good performance through several strategi - Operation: Improvement + validation **Usually coordinates**: -- ⚡ performance persona (primary) -- 🎨 frontend persona (secondary, if UI detected) +- ⚡ performance agent (primary) +- 🎨 frontend agent (secondary, if UI detected) - Playwright MCP (performance testing) - --think-hard flag (complex optimization) @@ -965,7 +883,7 @@ The orchestrator tries to optimize for good performance through several strategi **Usually coordinates**: - --delegate auto flag (parallel processing) - --uc flag (token optimization) -- 🏗️ architect persona (system-level analysis) +- 🏗️ architect agent (system-level analysis) - Sequential MCP (structured analysis) **Quality Gates**: Distributed validation across sub-agents @@ -987,7 +905,7 @@ orchestrator_config: learning_enabled: true confidence_threshold: 0.7 pattern_detection: aggressive - wave_score_threshold: 0.7 + delegation_threshold: 0.7 ``` The orchestrator tries to learn from successful patterns and improve future routing decisions based on outcomes. @@ -1078,7 +996,7 @@ Because SuperClaude follows consistent rules, you can predict how it will approa **You can expect**: - Reading existing code before suggesting changes - Following your project's existing patterns -- Security-first approach (security persona likely activates) +- Security-first approach (security agent likely activates) - Evidence-based recommendations with reasoning - Quality gates before marking improvements complete @@ -1123,7 +1041,7 @@ You should usually understand what SuperClaude is doing and why: **Request**: "Add authentication to our API" **Rules Applied**: -- Security persona usually auto-activates +- Security agent usually auto-activates - Never compromise on security fundamentals - Check existing patterns first - Quality gates include security validation @@ -1172,14 +1090,14 @@ Sometimes rules might seem to conflict with immediate needs: ### Principles That Guide Persona Behavior 🎭 -Each persona follows the core principles but emphasizes different aspects: +Each agent follows the core principles but emphasizes different aspects: -- **🛡️ Security persona**: Security > compliance > reliability > performance -- **⚡ Performance persona**: Measure first > optimize critical path > user experience -- **🏗️ Architect persona**: Long-term maintainability > scalability > performance -- **🎨 Frontend persona**: User needs > accessibility > performance > technical elegance +- **🛡️ Security agent**: Security > compliance > reliability > performance +- **⚡ Performance agent**: Measure first > optimize critical path > user experience +- **🏗️ Architect agent**: Long-term maintainability > scalability > performance +- **🎨 Frontend agent**: User needs > accessibility > performance > technical elegance -**Why this matters**: You can predict how different personas will prioritize trade-offs based on their core principles. +**Why this matters**: You can predict how different agents will prioritize trade-offs based on their core principles. ### Living Principles 🌱 @@ -1211,7 +1129,7 @@ If you haven't installed SuperClaude yet, see the [Installation Guide](installat /sc:save # Save session state (NEW!) ``` -#### V4 Beta Session Workflow +#### v4.0.0 Session Workflow Experience the new session persistence: ```bash @@ -1245,7 +1163,7 @@ Try these commands to see how SuperClaude automatically chooses the right tools: /sc:analyze --focus performance slow-endpoints/ ``` -Watch for auto-activated flags and personas in the output. This shows SuperClaude's intelligent routing in action. +Watch for auto-activated flags and agents in the output. This shows SuperClaude's intelligent routing in action. ### Development Workflow Patterns 🔄 @@ -1295,7 +1213,7 @@ For developing new features: # 4. Testing with cross-session context /sc:test --type e2e dashboard/ -# → 🧪 qa agent + Playwright MCP for testing +# → 🧪 quality-engineer agent + Playwright MCP for testing # → Session memory ensures test consistency # 5. Reflection and checkpoint @@ -1310,7 +1228,7 @@ For systematic debugging: ```bash # 1. Problem investigation /sc:troubleshoot "login randomly fails" --think -# → 🔍 analyzer persona + Sequential MCP for methodology +# → 🔍 root-cause-analyst agent + Sequential MCP for methodology # 2. Root cause analysis /sc:analyze auth-flow/ --focus debugging @@ -1331,7 +1249,7 @@ For improving existing code: ```bash # 1. Quality assessment /sc:analyze legacy-code/ --focus quality -# → 🔄 refactorer persona identifies improvement opportunities +# → 🔄 refactoring-expert agent identifies improvement opportunities # 2. Safe improvements /sc:improve --preview legacy-code/ @@ -1351,16 +1269,16 @@ For improving existing code: #### Security-First Development ```bash # Development with security focus -/sc:analyze --persona-security --focus security +/sc:analyze --agent-security --focus security /sc:build --validate --safe-mode /sc:test --type security -/sc:git --persona-security --validate +/sc:git --agent-security --validate ``` #### Performance-Optimized Workflow ```bash # Performance-focused development -/sc:analyze --focus performance --persona-performance +/sc:analyze --focus performance --agent-performance /sc:improve --type performance --benchmark /sc:test --focus performance --play /sc:test --focus performance --play @@ -1369,8 +1287,8 @@ For improving existing code: #### Team Collaboration Workflow ```bash # Collaborative development patterns -/sc:analyze team-code/ --persona-qa --focus quality -/sc:document features/ --persona-scribe --type guide +/sc:analyze team-code/ --agent-quality-engineer --focus quality +/sc:document features/ --agent-technical-writer --type guide /sc:git --smart-commit --branch-strategy /sc:task status # Check team progress ``` @@ -1386,7 +1304,7 @@ For working with enterprise-scale projects: # → Parallel processing + compression + architectural focus # Systematic improvements -/sc:improve legacy-system/ --wave-mode auto --safe-mode +/sc:improve legacy-system/ --delegate auto --safe-mode # → Multi-stage improvements with safety checks # Comprehensive quality review @@ -1399,7 +1317,7 @@ For updating old codebases: ```bash # Assessment phase -/sc:analyze legacy/ --persona-architect --ultrathink +/sc:analyze legacy/ --agent-architect --ultrathink # → Deep architectural analysis # Planning phase @@ -1407,7 +1325,7 @@ For updating old codebases: # → Comprehensive modernization plan # Implementation phase -/sc:improve legacy/ --wave-mode systematic --safe-mode --loop +/sc:improve legacy/ --delegate systematic --safe-mode --loop # → Iterative, safe improvements with validation # Migration support @@ -1424,9 +1342,9 @@ For projects spanning multiple technical domains: # → All MCP servers + parallel processing # Domain-specific improvements -/sc:improve frontend/ --persona-frontend --magic -/sc:improve backend/ --persona-backend --c7 -/sc:improve infrastructure/ --persona-devops --seq +/sc:improve frontend/ --agent-frontend --magic +/sc:improve backend/ --agent-backend --c7 +/sc:improve infrastructure/ --agent-devops-architect --seq # Integration validation /sc:test --type integration --play @@ -1456,18 +1374,18 @@ For projects spanning multiple technical domains: /sc:build project/ --think --c7 # Full orchestration -/sc:build project/ --wave-mode auto --all-mcp --delegate auto +/sc:build project/ --delegate auto --all-mcp ``` #### Combine Complementary Personas ```bash # Security + Performance analysis -/sc:analyze api/ --persona-security -/sc:analyze api/ --persona-performance +/sc:analyze api/ --agent-security +/sc:analyze api/ --agent-performance # Architecture + Quality review -/sc:review system/ --persona-architect --focus architecture -/sc:review system/ --persona-qa --focus quality +/sc:review system/ --agent-architect --focus architecture +/sc:review system/ --agent-quality-engineer --focus quality ``` ### Troubleshooting Workflows 🚨 @@ -1479,7 +1397,7 @@ For projects spanning multiple technical domains: # → Meta-cognitive analysis of what went wrong # Try different approaches -/sc:analyze problem/ --persona-analyzer --seq +/sc:analyze problem/ --agent-root-cause-analyst --seq # → Systematic investigation methodology # Check framework status @@ -1503,11 +1421,11 @@ For projects spanning multiple technical domains: # Use specific focus flags /sc:analyze code/ --focus security --scope file -# Activate appropriate personas manually -/sc:analyze frontend-code/ --persona-security # Security view of frontend +# Activate appropriate agents manually +/sc:analyze frontend-code/ --agent-security # Security view of frontend # Combine multiple approaches -/sc:analyze --focus performance --persona-performance --play +/sc:analyze --focus performance --agent-performance --play ``` ### Building Your Own Workflows 🛠️ @@ -1517,10 +1435,10 @@ Track what combinations work well for your specific needs: ```bash # Security-focused API development -alias secure-api="/build api/ --persona-security --validate --c7" +alias secure-api="/build api/ --agent-security --validate --c7" # Performance-optimized frontend work -alias perf-frontend="/build ui/ --persona-performance --magic --benchmark" +alias perf-frontend="/build ui/ --agent-performance --magic --benchmark" # Quality improvement workflow alias quality-check="/scan --focus quality && /improve --safe-mode && /test --coverage" @@ -1531,7 +1449,7 @@ Try different combinations to find what works best: ```bash # For learning: verbose explanations with docs -/sc:explain concept --persona-mentor --verbose --c7 +/sc:explain concept --agent-learning-guide --verbose --c7 # For safety: maximum validation and checking /sc:improve critical-code/ --safe-mode --validate --preview @@ -1546,7 +1464,7 @@ Remember: SuperClaude learns from successful patterns, so the more you use effec ## Integration & Coordination 🤝 -Understanding how SuperClaude's components work together is key to using the framework effectively. This section shows you how commands, flags, personas, and MCP servers coordinate automatically - and how to control that coordination when needed. +Understanding how SuperClaude's components work together is key to using the framework effectively. This section shows you how commands, flags, agents, and MCP servers coordinate automatically - and how to control that coordination when needed. ### Auto-Coordination Examples 🤖 @@ -1588,7 +1506,7 @@ SuperClaude automatically coordinates components based on context. Here's how it **Automatic coordination**: - **Command**: `/troubleshoot` handles investigation - **Persona**: ⚡ performance auto-activates (performance keywords) -- **Persona**: 🔍 analyzer provides investigation methodology +- **Agent**: 🔍 root-cause-analyst provides investigation methodology - **MCP**: Sequential structures the debugging process - **MCP**: Playwright provides performance testing - **Flags**: `--think` auto-activates (complex debugging) @@ -1602,12 +1520,12 @@ Sometimes you want to override auto-coordination for specific needs: #### Override Persona Selection ```bash # View frontend code from security perspective -/sc:analyze react-components/ --persona-security +/sc:analyze react-components/ --agent-security # → Security analysis of UI components (XSS, data exposure, etc.) # Apply architectural thinking to small utility -/sc:improve utility-function.js --persona-architect -# → Design patterns and extensibility for simple code +/sc:improve utility-function.js --agent-architect +# → Design patterns and architecture for simple code ``` #### Control MCP Server Usage @@ -1627,10 +1545,10 @@ Sometimes you want to override auto-coordination for specific needs: #### Combine Multiple Perspectives ```bash -# Sequential analysis with different personas -/sc:analyze payment-system/ --persona-security # Security view -/sc:analyze payment-system/ --persona-performance # Performance view -/sc:analyze payment-system/ --persona-architect # Architecture view +# Sequential analysis with different agents +/sc:analyze payment-system/ --agent-security # Security view +/sc:analyze payment-system/ --agent-performance # Performance view +/sc:analyze payment-system/ --agent-architect # Architecture view # Or coordinate automatically /sc:review payment-system/ --focus quality @@ -1648,7 +1566,7 @@ Flags work together to create powerful combinations: # → Conservative changes + risk assessment + preview before applying # Safe exploration of large changes -/sc:improve legacy-system/ --wave-mode auto --safe-mode --validate +/sc:improve legacy-system/ --delegate auto --safe-mode --validate # → Multi-stage improvements + safety checks + validation gates ``` @@ -1666,11 +1584,11 @@ Flags work together to create powerful combinations: #### Learning-Focused Patterns ```bash # Educational explanations with full context -/sc:explain complex-concept --persona-mentor --verbose --c7 +/sc:explain complex-concept --agent-learning-guide --verbose --c7 # → Educational approach + detailed explanations + official docs # Deep understanding with transparency -/sc:analyze mysterious-code/ --persona-analyzer --think-hard --introspect +/sc:analyze mysterious-code/ --agent-root-cause-analyst --think-hard --introspect # → Investigation methodology + deep analysis + thinking transparency ``` @@ -1737,26 +1655,26 @@ Personas automatically collaborate on complex requests: /sc:improve legacy-code/ --focus quality ``` **Persona collaboration**: -- 🔄 refactorer: Code quality and patterns -- 🧪 qa: Testing and validation +- 🔄 refactoring-expert: Code quality and patterns +- 🧪 quality-engineer: Testing and validation - 🏗️ architect: Structural improvements - Result: Clean, tested, well-architected code ### Advanced Coordination Strategies 🚀 -#### Wave Orchestration +#### Progressive Coordination For complex multi-stage operations: ```bash -/sc:improve enterprise-system/ --wave-mode systematic +/sc:improve enterprise-system/ --delegate systematic ``` -**Wave coordination**: -1. **Analysis Wave**: 🔍 analyzer + Sequential assess current state -2. **Planning Wave**: 🏗️ architect + Context7 design improvements -3. **Implementation Wave**: Appropriate specialists + tools implement changes -4. **Validation Wave**: 🧪 qa + Playwright verify improvements -5. **Optimization Wave**: ⚡ performance + metrics optimize results +**Progressive coordination**: +1. **Analysis Phase**: 🔍 root-cause-analyst + Sequential assess current state +2. **Planning Phase**: 🏗️ architect + Context7 design improvements +3. **Implementation Phase**: Appropriate specialists + tools implement changes +4. **Validation Phase**: 🧪 quality-engineer + Playwright verify improvements +5. **Optimization Phase**: ⚡ performance + metrics optimize results #### Sub-Agent Delegation For parallel processing: @@ -1775,15 +1693,15 @@ For parallel processing: SuperClaude adapts coordination based on context: **Development Phase Detection**: -- Planning phase → 🏗️ architect + ✍️ scribe emphasis +- Planning phase → 🏗️ architect + ✍️ technical-writer emphasis - Implementation phase → Domain specialists + Magic/Context7 -- Testing phase → 🧪 qa + Playwright emphasis -- Deployment phase → 🚀 devops + validation emphasis +- Testing phase → 🧪 quality-engineer + Playwright emphasis +- Deployment phase → 🚀 devops-architect + validation emphasis **Complexity-Based Scaling**: - Simple tasks → Direct execution - Moderate complexity → Persona + MCP coordination -- High complexity → Wave orchestration + delegation +- High complexity → Progressive orchestration + delegation ### Coordination Troubleshooting 🔧 @@ -1793,9 +1711,9 @@ SuperClaude adapts coordination based on context: /sc:analyze simple-file.js --no-mcp --answer-only # → Minimal tooling for simple tasks -# Wrong persona activated -/sc:analyze backend-api/ --persona-security -# → Override with explicit persona choice +# Wrong agent activated +/sc:analyze backend-api/ --agent-security +# → Override with explicit agent choice # Not enough analysis depth /sc:troubleshoot complex-issue --ultrathink --all-mcp @@ -1828,12 +1746,12 @@ SuperClaude adapts coordination based on context: #### Understand Flag Interactions - Some flags override others (`--no-mcp` overrides `--c7`, `--seq`) - Safety flags take precedence over optimization flags -- Persona flags can be overridden by more specific persona requests +- Persona flags can be overridden by more specific agent requests #### Use Appropriate Scope -- File-level: Single persona + minimal MCP -- Module-level: Domain personas + relevant MCP -- System-level: Multiple personas + full MCP coordination +- File-level: Single agent + minimal MCP +- Module-level: Domain agents + relevant MCP +- System-level: Multiple agents + full MCP coordination #### Monitor Resource Usage - Large operations → Use `--uc` and `--delegate` @@ -1857,7 +1775,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:load --deep --summary ``` **What happens**: -- 🔍 analyzer persona activates (investigation needed) +- 🔍 root-cause-analyst agent activates (investigation needed) - Sequential MCP structures the analysis - Context7 MCP identifies framework patterns - Creates comprehensive project overview @@ -1869,7 +1787,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:analyze --focus quality ``` **Auto-coordination**: -- 🧪 qa persona activates (quality focus) +- 🧪 quality-engineer agent activates (quality focus) - Sequential MCP provides systematic analysis - Scans for code quality, security, and performance issues - Generates actionable improvement recommendations @@ -1878,10 +1796,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 3: Architecture Understanding ```bash -/sc:analyze --focus architecture --persona-architect +/sc:analyze --focus architecture --agent-architect ``` **What happens**: -- 🏗️ architect persona provides system design perspective +- 🏗️ architect agent provides system design perspective - Context7 MCP brings in React/Node.js architectural patterns - Sequential MCP structures the architectural analysis - Identifies design patterns, data flow, and component relationships @@ -1890,10 +1808,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 4: Getting Started Guide ```bash -/sc:document onboarding --type guide --persona-scribe +/sc:document onboarding --type guide --agent-technical-writer ``` **What happens**: -- ✍️ scribe persona creates professional documentation +- ✍️ technical-writer agent creates professional documentation - Context7 MCP provides documentation standards - Synthesizes previous analysis into newcomer-friendly guide - Includes setup instructions and key concepts @@ -1908,10 +1826,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 1: Security-Focused Analysis ```bash -/sc:scan auth-system/ --persona-security --focus security +/sc:scan auth-system/ --agent-security --focus security ``` **Auto-coordination**: -- 🛡️ security persona activates (security expertise) +- 🛡️ security agent activates (security expertise) - Sequential MCP provides systematic threat modeling - Context7 MCP brings in OWASP and security best practices - `--validate` flag auto-activates (high-risk operation) @@ -1923,7 +1841,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:troubleshoot "JWT token exposure in logs" --think --seq ``` **What happens**: -- 🔍 analyzer persona provides investigation methodology +- 🔍 root-cause-analyst agent provides investigation methodology - `--think` flag enables deep analysis - Sequential MCP structures the debugging process - Traces data flow and identifies exposure points @@ -1935,7 +1853,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:improve auth-system/ --focus security --safe-mode --validate ``` **Auto-coordination**: -- 🛡️ security persona maintains security focus +- 🛡️ security agent maintains security focus - `--safe-mode` ensures conservative changes - `--validate` confirms changes before applying - Context7 MCP provides secure coding patterns @@ -1947,7 +1865,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:test auth-system/ --type security --play ``` **What happens**: -- 🧪 qa persona provides testing expertise +- 🧪 quality-engineer agent provides testing expertise - Playwright MCP executes security testing scenarios - Tests authentication flows, session management, and access controls - Validates security improvements are working @@ -1962,10 +1880,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 1: Performance Analysis ```bash -/sc:analyze dashboard/ --focus performance --persona-performance +/sc:analyze dashboard/ --focus performance --agent-performance ``` **Auto-coordination**: -- ⚡ performance persona activates (performance expertise) +- ⚡ performance agent activates (performance expertise) - Playwright MCP provides performance metrics and testing - Context7 MCP brings in React performance best practices - `--think-hard` auto-activates (complex performance analysis) @@ -1974,11 +1892,11 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 2: Frontend Performance Deep Dive ```bash -/sc:analyze frontend/ --persona-frontend --focus performance --play +/sc:analyze frontend/ --agent-frontend --focus performance --play ``` **What happens**: -- 🎨 frontend persona provides UI/UX perspective -- ⚡ performance persona coordinates (dual expertise) +- 🎨 frontend agent provides UI/UX perspective +- ⚡ performance agent coordinates (dual expertise) - Playwright MCP measures Core Web Vitals, bundle sizes, render times - Magic MCP suggests modern optimization patterns @@ -1986,10 +1904,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 3: Backend API Performance ```bash -/sc:analyze api/ --persona-backend --focus performance +/sc:analyze api/ --agent-backend --focus performance ``` **Auto-coordination**: -- ⚙️ backend persona provides server-side expertise +- ⚙️ backend agent provides server-side expertise - Sequential MCP analyzes database queries and API patterns - Context7 MCP provides Node.js/Express optimization patterns - Identifies slow queries, inefficient endpoints, and caching opportunities @@ -2001,7 +1919,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:improve dashboard/ --focus performance --loop --iterations 3 ``` **What happens**: -- ⚡ performance persona leads optimization +- ⚡ performance agent leads optimization - `--loop` enables iterative improvement - Each iteration: optimize → measure → validate → improve - Progressive enhancement with metrics validation @@ -2028,10 +1946,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 1: Legacy Assessment ```bash -/sc:analyze legacy-app/ --persona-architect --ultrathink +/sc:analyze legacy-app/ --agent-architect --ultrathink ``` **Auto-coordination**: -- 🏗️ architect persona provides structural analysis +- 🏗️ architect agent provides structural analysis - `--ultrathink` enables maximum analysis depth - Context7 MCP compares against current React patterns - Sequential MCP provides systematic modernization assessment @@ -2040,10 +1958,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 2: Modernization Planning ```bash -/sc:design modernization-strategy --type architecture --persona-architect +/sc:design modernization-strategy --type architecture --agent-architect ``` **What happens**: -- 🏗️ architect persona designs migration strategy +- 🏗️ architect agent designs migration strategy - Context7 MCP provides current React ecosystem patterns - Sequential MCP structures the modernization plan - Identifies migration phases, dependencies, and risks @@ -2052,14 +1970,14 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 3: Safe Incremental Improvements ```bash -/sc:improve legacy-components/ --safe-mode --wave-mode systematic --loop +/sc:improve legacy-components/ --safe-mode --delegate systematic --loop ``` **Auto-coordination**: -- 🔄 refactorer persona leads code improvements +- 🔄 refactoring-expert agent leads code improvements - `--safe-mode` ensures minimal risk -- `--wave-mode systematic` enables multi-stage improvements +- `--delegate systematic` enables multi-stage improvements - `--loop` allows iterative refinement -- Multiple personas coordinate: architect, frontend, qa +- Multiple agents coordinate: architect, frontend, quality-engineer **Output**: Systematic modernization with safety checks and progressive enhancement. @@ -2068,7 +1986,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:test modernized-app/ --type integration --coverage --play ``` **What happens**: -- 🧪 qa persona ensures quality throughout modernization +- 🧪 quality-engineer agent ensures quality throughout modernization - Playwright MCP provides comprehensive testing - Tests legacy compatibility and new functionality - Validates modernization doesn't break existing features @@ -2083,11 +2001,11 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 1: Requirements Analysis ```bash -/sc:design user-service-api --type api --persona-backend +/sc:design user-service-api --type api --agent-backend ``` **Auto-coordination**: -- ⚙️ backend persona provides API design expertise -- 🏗️ architect persona coordinates for system integration +- ⚙️ backend agent provides API design expertise +- 🏗️ architect agent coordinates for system integration - Context7 MCP provides API design best practices - Sequential MCP structures requirement analysis @@ -2095,10 +2013,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 2: Security Review ```bash -/sc:review api-design/ --persona-security --focus security +/sc:review api-design/ --agent-security --focus security ``` **What happens**: -- 🛡️ security persona evaluates API security +- 🛡️ security agent evaluates API security - Reviews authentication, authorization, and data protection - Context7 MCP provides OWASP API security guidelines - Identifies security requirements and threat vectors @@ -2107,10 +2025,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 3: Performance Considerations ```bash -/sc:analyze api-design/ --persona-performance --focus performance +/sc:analyze api-design/ --agent-performance --focus performance ``` **Auto-coordination**: -- ⚡ performance persona evaluates scalability +- ⚡ performance agent evaluates scalability - Analyzes endpoint performance, caching strategies, rate limiting - Context7 MCP provides high-performance API patterns - Projects performance under load @@ -2119,10 +2037,10 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h #### Step 4: Documentation for Multiple Teams ```bash -/sc:document api/ --type api --persona-scribe --detailed +/sc:document api/ --type api --agent-technical-writer --detailed ``` **What happens**: -- ✍️ scribe persona creates professional API documentation +- ✍️ technical-writer agent creates professional API documentation - Context7 MCP provides API documentation standards - Creates examples, integration guides, and troubleshooting - Tailored for multiple consuming teams @@ -2134,21 +2052,21 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h /sc:build api-implementation/ --validate --test-coverage ``` **Auto-coordination**: -- ⚙️ backend persona implements API patterns -- 🧪 qa persona ensures quality and testing +- ⚙️ backend agent implements API patterns +- 🧪 quality-engineer agent ensures quality and testing - Sequential MCP validates implementation against design - Comprehensive testing and validation **Output**: Production-ready API implementation with comprehensive testing and validation. -**Collaboration efficiency**: Multi-persona coordination reduces design iteration cycles by 60% and improves cross-team alignment. +**Collaboration efficiency**: Multi-agent coordination reduces design iteration cycles by 60% and improves cross-team alignment. ### Common Pattern Recognition 🔍 These examples show recurring patterns in how SuperClaude components coordinate: #### Investigation → Analysis → Implementation → Validation -Most complex workflows follow this pattern with appropriate personas and tools for each phase. +Most complex workflows follow this pattern with appropriate agents and tools for each phase. #### Multi-Persona Coordination Complex problems benefit from multiple perspectives (security + performance, architecture + frontend, etc.). @@ -2180,7 +2098,7 @@ Based on real-world usage patterns and successful workflows, here are practical /sc:build --help # Not here - complex orchestration -/sc:improve entire-codebase/ --wave-mode force --all-mcp --delegate auto +/sc:improve entire-codebase/ --delegate force --all-mcp ``` **Why**: Understanding basic behavior before adding complexity prevents confusion and helps you learn the framework gradually. @@ -2189,10 +2107,10 @@ Based on real-world usage patterns and successful workflows, here are practical ```bash # Let SuperClaude choose tools /sc:analyze auth-system/ -# → Watch what auto-activates (likely security persona + validation) +# → Watch what auto-activates (likely security agent + validation) # Then experiment with manual control -/sc:analyze auth-system/ --persona-performance +/sc:analyze auth-system/ --agent-performance # → See different perspective on same code ``` @@ -2240,10 +2158,10 @@ Based on real-world usage patterns and successful workflows, here are practical /sc:troubleshoot issue --think --seq → /analyze affected-code/ --focus quality # Learning and documentation workflow -/sc:explain concept --persona-mentor --verbose --c7 +/sc:explain concept --agent-learning-guide --verbose --c7 # Performance optimization workflow -/sc:analyze --focus performance --persona-performance --play +/sc:analyze --focus performance --agent-performance --play ``` **Why**: These combinations are proven patterns that work well together and don't conflict. @@ -2267,10 +2185,10 @@ Based on real-world usage patterns and successful workflows, here are practical #### Let Domain Auto-Activation Work ```bash -# These will automatically get the right persona -/sc:build react-components/ # → frontend persona -/sc:scan auth/ --focus security # → security persona -/sc:troubleshoot slow-api/ # → performance + analyzer personas +# These will automatically get the right agent +/sc:build react-components/ # → frontend agent +/sc:scan auth/ --focus security # → security agent +/sc:troubleshoot slow-api/ # → performance + root-cause-analyst agents ``` **Why**: Auto-activation is based on proven patterns and usually selects the most appropriate expertise. @@ -2278,26 +2196,26 @@ Based on real-world usage patterns and successful workflows, here are practical #### Manual Override for Different Perspectives ```bash # Get different viewpoints on same code -/sc:analyze payment-flow/ --persona-security # Security perspective -/sc:analyze payment-flow/ --persona-performance # Performance perspective -/sc:analyze payment-flow/ --persona-architect # Architecture perspective +/sc:analyze payment-flow/ --agent-security # Security perspective +/sc:analyze payment-flow/ --agent-performance # Performance perspective +/sc:analyze payment-flow/ --agent-architect # Architecture perspective ``` -**Why**: Different personas provide unique insights that can reveal issues or opportunities others might miss. +**Why**: Different agents provide unique insights that can reveal issues or opportunities others might miss. #### Use Appropriate Personas for Project Phases ```bash # Planning phase -/sc:design new-feature --persona-architect +/sc:design new-feature --agent-architect # Implementation phase -/sc:build feature/ --persona-frontend # or backend, etc. +/sc:build feature/ --agent-frontend # or backend, etc. # Testing phase -/sc:test feature/ --persona-qa +/sc:test feature/ --agent-quality-engineer # Documentation phase -/sc:document feature/ --persona-scribe +/sc:document feature/ --agent-technical-writer ``` **Why**: Each project phase benefits from different types of expertise and perspectives. @@ -2470,23 +2388,23 @@ Based on real-world usage patterns and successful workflows, here are practical #### Use Mentor Persona for Learning ```bash # Learn new concepts -/sc:explain GraphQL --persona-mentor --verbose +/sc:explain GraphQL --agent-learning-guide --verbose # Understand complex code -/sc:analyze complex-algorithm.js --persona-mentor +/sc:analyze complex-algorithm.js --agent-learning-guide # Get step-by-step guidance -/sc:build new-feature/ --persona-mentor --plan +/sc:build new-feature/ --agent-learning-guide --plan ``` -**Why**: Mentor persona optimizes for understanding and knowledge transfer rather than just task completion. +**Why**: Learning-guide agent optimizes for understanding and knowledge transfer rather than just task completion. #### Experiment with Different Approaches ```bash -# Try different personas on same problem -/sc:analyze api-design/ --persona-architect -/sc:analyze api-design/ --persona-security -/sc:analyze api-design/ --persona-performance +# Try different agents on same problem +/sc:analyze api-design/ --agent-architect +/sc:analyze api-design/ --agent-security +/sc:analyze api-design/ --agent-performance # Compare tool combinations /sc:build app/ --magic --c7 @@ -2499,12 +2417,12 @@ Based on real-world usage patterns and successful workflows, here are practical ```bash # Identify what works for your workflow # Security-focused API development -/sc:design api --persona-security --validate -/sc:build api --persona-backend --c7 +/sc:design api --agent-security --validate +/sc:build api --agent-backend --c7 /sc:test api --type security --play # Create your own efficient combinations -/sc:analyze code/ --think --c7 --safe-mode # Your personal "thorough analysis" +/sc:analyze code/ --think --c7 --safe-mode # Your agentl "thorough analysis" ``` **Why**: Developing your own proven patterns increases productivity and ensures consistent quality. @@ -2514,7 +2432,7 @@ Based on real-world usage patterns and successful workflows, here are practical #### Don't Over-Engineer Simple Tasks ```bash # ❌ Overkill for simple tasks -/sc:analyze simple-utility.js --ultrathink --all-mcp --wave-mode force +/sc:analyze simple-utility.js --ultrathink --all-mcp --delegate force # ✅ Appropriate for simple tasks /sc:analyze simple-utility.js --focus quality @@ -2523,10 +2441,10 @@ Based on real-world usage patterns and successful workflows, here are practical #### Don't Ignore Auto-Activation Wisdom ```bash # ❌ Fighting the system -/sc:build react-app/ --persona-backend --no-magic # Wrong tools for the job +/sc:build react-app/ --agent-backend --no-magic # Wrong tools for the job # ✅ Working with the system -/sc:build react-app/ # Let frontend persona and Magic activate automatically +/sc:build react-app/ # Let frontend agent and Magic activate automatically ``` #### Don't Skip Safety for Speed @@ -2578,7 +2496,7 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common # → Shows decision-making process # Try with explicit control -/sc:analyze code.js --persona-analyzer --think --seq +/sc:analyze code.js --agent-root-cause-analyst --think --seq # → Override auto-activation ``` @@ -2679,7 +2597,7 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common 1. Safety flags (`--safe-mode`) > optimization flags 2. Explicit flags > auto-activation 3. `--no-mcp` overrides all individual MCP flags -4. Last specified persona wins +4. Last specified agent wins 5. Scope: system > project > module > file **Diagnosis**: @@ -2691,12 +2609,12 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common #### Auto-Activation Issues -**Problem**: Wrong flags or personas auto-activate. +**Problem**: Wrong flags or agents auto-activate. **Solutions**: ```bash # Override auto-activation explicitly -/sc:analyze frontend-code/ --persona-security # Force security view +/sc:analyze frontend-code/ --agent-security # Force security view /sc:build project/ --no-mcp # Force native tools only # Use more specific language @@ -2722,49 +2640,49 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common **Diagnosis**: ```bash -# Check what triggered persona activation +# Check what triggered agent activation /sc:analyze code/ --introspect -# → Shows persona selection reasoning +# → Shows agent selection reasoning ``` **Solutions**: ```bash -# Override with explicit persona -/sc:analyze backend-api/ --persona-security # Security view of backend code -/sc:analyze ui-component/ --persona-performance # Performance view of frontend +# Override with explicit agent +/sc:analyze backend-api/ --agent-security # Security view of backend code +/sc:analyze ui-component/ --agent-performance # Performance view of frontend # Use more specific language -/sc:analyze "security issues in payment processing" # Triggers security persona -/sc:analyze "slow database queries" # Triggers performance persona +/sc:analyze "security issues in payment processing" # Triggers security agent +/sc:analyze "slow database queries" # Triggers performance agent -# Try different personas for different perspectives -/sc:analyze payment-system/ --persona-security # Security view -/sc:analyze payment-system/ --persona-architect # Architecture view +# Try different agents for different perspectives +/sc:analyze payment-system/ --agent-security # Security view +/sc:analyze payment-system/ --agent-architect # Architecture view ``` #### Persona Doesn't Seem Active -**Problem**: Expected persona behavior but getting generic responses. +**Problem**: Expected agent behavior but getting generic responses. **Check Persona Activation**: ```bash -# Verify persona is active -/sc:analyze auth/ --persona-security --introspect +# Verify agent is active +/sc:analyze auth/ --agent-security --introspect # → Should show security-focused reasoning # Check if domain keywords are clear -/sc:scan authentication --focus security # Should auto-activate security persona +/sc:scan authentication --focus security # Should auto-activate security agent ``` **Solutions**: ```bash -# Be explicit about persona and focus -/sc:analyze code/ --persona-security --focus security +# Be explicit about agent and focus +/sc:analyze code/ --agent-security --focus security -# Use appropriate commands for personas -/sc:scan --persona-security # Security scanning -/sc:test --persona-qa # Quality-focused testing -/sc:document --persona-scribe # Professional documentation +# Use appropriate commands for agents +/sc:scan --agent-security # Security scanning +/sc:test --agent-quality-engineer # Quality-focused testing +/sc:document --agent-technical-writer # Professional documentation ``` ### MCP Server Issues 🔧 @@ -2913,9 +2831,9 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common # Be explicit about project type /sc:analyze react-typescript-app/ --c7 # Include tech stack in description -# Use appropriate personas -/sc:analyze node-api/ --persona-backend -/sc:analyze react-ui/ --persona-frontend +# Use appropriate agents +/sc:analyze node-api/ --agent-backend +/sc:analyze react-ui/ --agent-frontend ``` #### Inconsistent Results @@ -2928,13 +2846,13 @@ When SuperClaude doesn't work as expected, here's how to diagnose and fix common /sc:command args --introspect # Use explicit flags for consistency -/sc:analyze code/ --persona-analyzer --think --c7 # Explicit configuration +/sc:analyze code/ --agent-root-cause-analyst --think --c7 # Explicit configuration ``` **Solutions**: ```bash # Be more explicit about requirements -/sc:improve code/ --focus performance --persona-performance --safe-mode +/sc:improve code/ --focus performance --agent-performance --safe-mode # Use consistent flag patterns /sc:analyze --think --c7 # Your standard thorough analysis @@ -2986,11 +2904,11 @@ When reporting problems, include: | Problem | Quick Fix | Command | |---------|-----------|---------| | Too slow | Reduce scope + compression | `--scope file --uc` | -| Wrong persona | Override explicitly | `--persona-security` | +| Wrong agent | Override explicitly | `--agent-security` | | Too much output | Use compression | `--uc` | | Risky changes | Use safety features | `--safe-mode --preview` | | MCP not working | Force activation or disable | `--all-mcp` or `--no-mcp` | -| Inconsistent results | Use explicit flags | `--persona-x --think --c7` | +| Inconsistent results | Use explicit flags | `--agent-x --think --c7` | | Context issues | Load project context | `/load --deep` | | Token limits | Enable compression + delegation | `--uc --delegate auto` | @@ -3028,14 +2946,10 @@ SuperClaude v3.0 is fresh out of beta, and we're honest about what that means: i #### What We Removed (And Why) -**Hooks System (Coming Back in v4)** -- The v2 hooks system became too complex and buggy -- Caused performance issues and unpredictable behavior -- Being redesigned from scratch with better architecture - Will return in v4 with improved reliability and simpler configuration **Some Advanced Commands** -- Consolidated 20+ commands down to 16 essential ones +- Consolidated multiple command variants into 21 essential commands - Removed experimental commands that weren't stable enough - Focus on making core commands excellent rather than having many mediocre ones @@ -3071,11 +2985,6 @@ Our immediate focus is making v3 stable and polished: The next major version will focus on intelligence and user experience: -#### Redesigned Hooks System -- **Event-Driven Architecture**: Clean separation between framework and hooks -- **Performance Optimized**: No impact on core operations when hooks aren't used -- **Simple Configuration**: Easy setup and debugging -- **Extensibility**: Community hooks and custom integrations #### Enhanced AI Coordination - **Smarter Auto-Activation**: Better context understanding and tool selection @@ -3132,9 +3041,9 @@ We actively monitor: - **Documentation Feedback**: Gaps in documentation highlight areas for improvement - **Integration Requests**: Requests for specific tool/framework integrations guide MCP development -#### Beta Testing Program -- **Early Access**: Test new features before public release -- **Feedback Loop**: Direct input on experimental features +#### Community Participation +- **Early Access**: Help test new features and capabilities +- **Feedback Loop**: Direct input on framework improvements - **Performance Testing**: Help validate optimizations across different environments - **Use Case Validation**: Ensure new features work for real development scenarios @@ -3200,17 +3109,17 @@ We believe SuperClaude can become significantly more helpful for software develo ## Conclusion 🎉 -You've now got a comprehensive understanding of SuperClaude V4 Beta - its components, capabilities, and how to use them effectively. Let's wrap up with the key takeaways that will help you get the most out of the framework. +You've now got a comprehensive understanding of SuperClaude v4.0.0 - its components, capabilities, and how to use them effectively. Let's wrap up with the key takeaways that will help you get the most out of the framework. ### Key Takeaways 🎯 #### SuperClaude's Core Value -SuperClaude V4 Beta transforms Claude Code into an intelligent development partner through: +SuperClaude v4.0.0 transforms Claude Code into an intelligent development partner through: - **21 specialized commands** including session management and brainstorming - **13 expert agents** with enhanced coordination and specialization -- **4 behavioral modes** that adapt intelligently to different work types +- **5 behavioral modes** that adapt intelligently to different work types - **Session persistence** that remembers and learns across sessions -- **Advanced orchestration** with hooks system and quality gates +- **Advanced orchestration** with quality gates - **6 MCP servers** including intelligent editing and semantic analysis #### The Power is in the Coordination @@ -3223,17 +3132,17 @@ SuperClaude V4's power comes from intelligent system integration: - **Memory system** enables continuous learning and improvement #### Start Simple, Scale Intelligently -The best approach to SuperClaude V4 Beta is progressive: +The best approach to SuperClaude v4.0.0 is progressive: 1. **Initialize sessions** with `/sc:load` to experience persistent context 2. **Try brainstorming** with `/sc:brainstorm` for interactive discovery 3. **Trust behavioral modes** to adapt automatically to your work patterns 4. **Use session persistence** with `/sc:save` to build continuous context -5. **Experiment with advanced features** like hooks and multi-layer orchestration +5. **Experiment with advanced features** like multi-layer orchestration ### What Makes SuperClaude Different 🌟 #### Honest About Limitations -- V4 Beta represents major architectural improvements but is still in beta +- v4.0.0 represents major architectural improvements and is stable for production - We clearly document what's working well vs. what's still being refined - Session persistence and behavioral modes are sophisticated but still evolving - We prioritize reliability and user experience over flashy features @@ -3262,13 +3171,12 @@ The best approach to SuperClaude V4 Beta is progressive: #### For Experienced Users 1. **Leverage session persistence**: Build long-term project context across sessions 2. **Master behavioral modes**: Understand how brainstorming, introspection, task management, and token efficiency work -3. **Explore advanced orchestration**: Wave systems, hooks integration, and multi-layer coordination -4. **Contribute feedback**: Share what works (and what doesn't) with V4 Beta features -5. **Try SuperClaude-Lite**: Experiment with the streamlined variant for specific workflows +3. **Explore advanced orchestration**: Progressive systems and multi-layer coordination +4. **Contribute feedback**: Share what works (and what doesn't) with v4.0.0 features ### When to Use SuperClaude 🤔 -#### SuperClaude V4 Beta Excels At +#### SuperClaude v4.0.0 Excels At - **Persistent development workflows**: Long-term projects with cross-session context - **Interactive requirements discovery**: Brainstorming and clarifying project goals - **Intelligent code analysis**: Semantic understanding with Serena and Morphllm @@ -3307,7 +3215,6 @@ The framework gets better through: - Better documentation based on user questions and feedback #### Medium-Term (6-18 Months) -- Redesigned hooks system with better architecture and performance - Smarter auto-activation based on learning from usage patterns - Extended MCP ecosystem with community-contributed servers - Advanced orchestration with true parallel processing @@ -3320,7 +3227,7 @@ The framework gets better through: ### Final Thoughts 🎉 -SuperClaude V4 Beta represents a significant architectural evolution in AI-assisted development. With persistent sessions, behavioral intelligence, and advanced orchestration, it demonstrates how AI can become a true development partner that learns and adapts while respecting existing workflows and human expertise. +SuperClaude v4.0.0 represents a significant architectural evolution in AI-assisted development. With persistent sessions, behavioral intelligence, and advanced orchestration, it demonstrates how AI can become a true development partner that learns and adapts while respecting existing workflows and human expertise. The framework succeeds when it makes you more productive, helps you learn new things, or catches issues you might have missed. It's designed to be a helpful colleague rather than a replacement for understanding your craft. @@ -3335,6 +3242,6 @@ Whether you use SuperClaude occasionally for specific tasks or integrate it deep --- *Last updated: January 2025* -*SuperClaude V4 Beta User Guide* +*SuperClaude v4.0.0 User Guide* *For questions, feedback, or contributions, visit our GitHub repository or join the community discussions. We're always happy to hear from users and learn about your experiences with the framework.*