Complete comprehensive documentation implementation

- Implement content for 200+ TODO placeholders across all documentation
- Create complete documentation structure: Getting-Started, User-Guide, Developer-Guide, Reference
- Add comprehensive guides for commands, agents, modes, MCP servers, flags, session management
- Implement technical architecture, contributing, testing, and security documentation
- Create examples cookbook, troubleshooting guide, and best practices documentation
- Update administrative files: CONTRIBUTING.md, SECURITY.md, PUBLISHING.md, CODE_OF_CONDUCT.md
- Ensure factual accuracy based on actual SuperClaude implementation analysis
- Maintain professional structure with progressive complexity and cross-references
- Provide complete coverage from beginner to expert level usage

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

User-Guide/agents.md

@@ -0,0 +1,326 @@
+# SuperClaude Agents Guide 🤖
+
+## Overview
+
+SuperClaude employs 13 specialized AI agents that automatically activate based on task context and keywords. The intelligent routing system analyzes your requests and coordinates the most relevant domain experts for optimal results.
+
+**Automatic Activation**: Type `/sc:implement "secure user login"` and watch as the security-engineer, backend-architect, and frontend-architect agents coordinate automatically.
+
+**Intelligent Coordination**: Multiple agents can work together on complex tasks, with each contributing their specialized expertise to different aspects of the problem.
+
+## 🚀 Just Try These (No Agent Knowledge Required)
+
+**Automatic Agent Examples:**
+```bash
+# Triggers: security-engineer + backend-architect
+/sc:implement "JWT authentication with rate limiting"
+
+# Triggers: frontend-architect + ux-designer
+/sc:design "responsive dashboard with accessibility"
+
+# Triggers: devops-architect + performance-engineer
+/sc:troubleshoot "slow deployment pipeline"
+
+# Triggers: qa-specialist + security-engineer
+/sc:test "payment processing security"
+```
+
+**Pattern Recognition Logic:**
+- **Keywords**: "auth", "security" → security-engineer
+- **File types**: ".jsx", ".vue" → frontend-architect
+- **Context**: API endpoints → backend-architect
+- **Complexity**: Multi-domain tasks → Multiple agents
+
+---
+
+## The SuperClaude Agent Team 👥
+
+### Architecture & System Design Agents 🏗️
+
+#### system-architect 🏢
+**Expertise**: Large-scale system design, microservices, distributed architectures
+**Auto-Activation**: "architecture", "microservices", "scalability", "system design"
+**Capabilities**: Service boundaries, data flow design, technology selection, scalability planning
+
+**Examples**: Microservices architecture, event-driven systems, API gateway design, database sharding strategies
+
+---
+
+#### backend-architect ⚙️
+**Expertise**: Reliable backend systems, APIs, data integrity, fault tolerance
+**Auto-Activation**: "API", "backend", "server", "database", "REST", "GraphQL"
+**Capabilities**: API design, database modeling, error handling, authentication, caching strategies
+
+**Examples**: REST API architecture, database schema design, authentication flows, message queue implementation
+
+---
+
+#### frontend-architect 🎨
+**Expertise**: Accessible UI design, modern frameworks, performance optimization
+**Auto-Activation**: "UI", "frontend", "React", "Vue", "component", "accessibility"
+**Capabilities**: Component architecture, state management, accessibility compliance, performance optimization
+
+**Examples**: React component hierarchies, state management patterns, responsive design systems, accessibility implementations
+
+---
+
+#### devops-architect 🚀
+**Expertise**: Infrastructure automation, CI/CD, deployment strategies, observability
+**Auto-Activation**: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring"
+**Capabilities**: Pipeline design, containerization, orchestration, monitoring setup, deployment strategies
+
+**Examples**: CI/CD pipeline configuration, Docker containerization, Kubernetes deployments, monitoring dashboards
+
+### Quality & Analysis Agents 🔍
+
+#### security-engineer 🔒
+**Expertise**: Threat modeling, vulnerability assessment, security compliance
+**Auto-Activation**: "security", "auth", "vulnerability", "encryption", "compliance"
+**Capabilities**: Security audits, threat analysis, compliance validation, secure coding practices
+
+**Examples**: Authentication systems, data encryption, vulnerability scanning, compliance reporting
+
+---
+
+#### performance-engineer ⚡
+**Expertise**: Performance optimization, bottleneck identification, scalability tuning
+**Auto-Activation**: "performance", "slow", "optimization", "bottleneck", "latency"
+**Capabilities**: Performance profiling, optimization strategies, load testing, caching solutions
+**Examples**: Database query optimization, API response time improvement, memory leak detection, caching implementation
+
+---
+
+#### root-cause-analyst 🔍
+**Expertise**: Systematic problem investigation, evidence-based analysis, hypothesis testing
+**Auto-Activation**: "bug", "issue", "problem", "debugging", "investigation"
+**Capabilities**: Error analysis, dependency tracking, systematic debugging, evidence collection
+
+**Examples**: Complex bug investigation, system failure analysis, performance degradation diagnosis
+
+---
+
+#### quality-engineer ✅
+**Expertise**: Quality assurance, testing strategies, edge case detection
+**Auto-Activation**: "test", "quality", "QA", "validation", "coverage"
+**Capabilities**: Test strategy design, edge case identification, quality metrics, validation frameworks
+
+**Examples**: Test suite architecture, quality gate implementation, automated testing, compliance validation
+
+---
+
+#### refactoring-expert 🔧
+**Expertise**: Code quality improvement, SOLID principles, technical debt reduction
+**Auto-Activation**: "refactor", "clean code", "technical debt", "SOLID", "maintainability"
+**Capabilities**: Code structure improvement, design pattern application, debt identification, clean code practices
+
+**Examples**: Legacy code modernization, design pattern implementation, code smell elimination, architecture improvement
+
+### Specialized Development Agents 🎯
+
+#### python-expert 🐍
+**Expertise**: Production-ready Python development, modern frameworks, best practices
+**Auto-Activation**: ".py" files, "Python", "Django", "FastAPI", "Flask", "asyncio"
+**Capabilities**: Python architecture, framework selection, performance optimization, security practices
+
+**Examples**: FastAPI applications, Django systems, async programming, Python packaging, data processing pipelines
+
+---
+
+#### requirements-analyst 📝
+**Expertise**: Requirements discovery, specification development, stakeholder analysis
+**Auto-Activation**: "requirements", "specification", "PRD", "user story", "functional"
+**Capabilities**: Requirements elicitation, specification writing, stakeholder mapping, acceptance criteria
+
+**Examples**: Product requirement documents, user story creation, functional specifications, acceptance criteria definition
+
+### Communication & Learning Agents 📚
+
+#### technical-writer 📚
+**Expertise**: Technical documentation, audience analysis, clear communication
+**Auto-Activation**: "documentation", "readme", "API docs", "user guide", "technical writing"
+**Capabilities**: Documentation architecture, audience targeting, clarity optimization, information design
+
+**Examples**: API documentation, user guides, technical tutorials, architecture documentation
+
+---
+
+#### learning-guide 🎓
+**Expertise**: Educational content design, progressive learning, mentorship
+**Auto-Activation**: "explain", "learn", "tutorial", "beginner", "teaching"
+**Capabilities**: Learning path design, concept explanation, skill progression, educational assessment
+
+**Examples**: Programming tutorials, concept explanations, skill assessments, learning roadmaps
+
+---
+
+## Agent Coordination & Integration 🤝
+
+**Agent Collaboration Patterns:**
+
+**Full-Stack Development**: frontend-architect + backend-architect + security-engineer
+**Quality Assurance**: quality-engineer + performance-engineer + security-engineer
+**System Design**: system-architect + devops-architect + performance-engineer
+**Problem Solving**: root-cause-analyst + performance-engineer + security-engineer
+
+**Multi-Domain Coordination:**
+Complex projects automatically activate multiple agents based on scope and requirements. Agents coordinate through shared context and complementary expertise.
+
+**MCP Server Integration:**
+- **Context7**: Provides domain-specific patterns and documentation
+- **Sequential**: Enables systematic multi-step reasoning
+- **Magic**: Enhances UI/UX capabilities for frontend agents
+- **Playwright**: Enables browser automation for testing agents
+- **Morphllm**: Accelerates code transformation for refactoring agents
+- **Serena**: Provides project memory and context for all agents
+
+**Command Integration:**
+Each SuperClaude command automatically selects appropriate agents:
+- `/sc:implement` → domain-specific architects (frontend, backend, security)
+- `/sc:analyze` → quality-engineer + security-engineer + performance-engineer
+- `/sc:troubleshoot` → root-cause-analyst + domain specialists
+- `/sc:improve` → refactoring-expert + performance-engineer
+- `/sc:document` → technical-writer + domain specialists
+
+## Quick Reference 📋
+
+| Agent | Domain | Key Triggers | Best For |
+|-------|--------|--------------|----------|
+| system-architect | Architecture | "architecture", "microservices" | Large-scale design |
+| backend-architect | Backend | "API", "server", "database" | Server-side systems |
+| frontend-architect | Frontend | "UI", "React", "component" | User interfaces |
+| devops-architect | Infrastructure | "deploy", "CI/CD", "Docker" | DevOps & deployment |
+| security-engineer | Security | "security", "auth", "vulnerability" | Security & compliance |
+| performance-engineer | Performance | "performance", "optimization" | Speed & efficiency |
+| quality-engineer | Quality | "test", "quality", "validation" | Testing & QA |
+| refactoring-expert | Code Quality | "refactor", "clean code" | Code improvement |
+| root-cause-analyst | Debugging | "bug", "issue", "debugging" | Problem investigation |
+| python-expert | Python | ".py", "Python", "Django" | Python development |
+| requirements-analyst | Analysis | "requirements", "PRD" | Requirements gathering |
+| technical-writer | Documentation | "documentation", "API docs" | Technical writing |
+| learning-guide | Education | "explain", "tutorial" | Teaching & learning |
+
+**Most Useful Agent Combinations:**
+
+**Web Application**: frontend-architect + backend-architect + security-engineer
+**API Development**: backend-architect + security-engineer + technical-writer
+**Legacy Modernization**: refactoring-expert + system-architect + quality-engineer
+**Security Audit**: security-engineer + quality-engineer + root-cause-analyst
+**Performance Optimization**: performance-engineer + system-architect + devops-architect
+
+**Multi-Agent Workflow Examples:**
+```bash
+# E-commerce platform (4 agents activate)
+/sc:implement "secure payment processing with fraud detection"
+# → backend-architect + security-engineer + quality-engineer + performance-engineer
+
+# Learning platform (3 agents activate)
+/sc:design "interactive coding tutorial system"
+# → frontend-architect + learning-guide + technical-writer
+```
+
+## Best Practices 💡
+
+**Getting Started (Simple Approach):**
+1. **Start Simple**: Just describe what you want - agents activate automatically
+2. **Trust the System**: SuperClaude selects the right experts for your context
+3. **Learn from Patterns**: Notice which agents activate for different tasks
+4. **Gradual Complexity**: Add more detail to trigger additional specialist agents
+
+**Advanced Agent Control:**
+- **Cross-Domain Projects**: Combine keywords to trigger multiple agents
+- **Specific Expertise**: Use domain-specific terminology for targeted activation
+- **Quality Focus**: Include "security", "performance", "quality" for comprehensive coverage
+- **Learning Mode**: Add "explain" or "tutorial" to include educational perspective
+
+**Common Usage Patterns:**
+
+**New Project Startup:**
+```bash
+/sc:brainstorm "fintech mobile app"
+# → Activates: system-architect + frontend-architect + security-engineer
+```
+
+**Existing Code Analysis:**
+```bash
+/sc:analyze src/ --focus security
+# → Activates: security-engineer + quality-engineer + refactoring-expert
+```
+
+**Learning & Understanding:**
+```bash
+/sc:explain "microservices architecture patterns"
+# → Activates: system-architect + learning-guide + technical-writer
+```
+
+**Performance Investigation:**
+```bash
+/sc:troubleshoot "API response time > 2 seconds"
+# → Activates: performance-engineer + root-cause-analyst + backend-architect
+```
+
+**Quality Improvement:**
+```bash
+/sc:improve legacy-code/ --focus maintainability
+# → Activates: refactoring-expert + quality-engineer + technical-writer
+```
+
+---
+
+## Final Notes 📝
+
+**The Truth About Agent Usage:**
+
+SuperClaude agents activate automatically based on keywords and context - you don't need to manage them. The system is designed to be sophisticated under the hood while remaining simple to use.
+
+**Agent Knowledge Usefulness:**
+- **Useful**: Understanding why certain agents activate can help you craft better commands
+- **Useful**: Knowing agent specialties helps you choose the right keywords and approaches
+- **Unnecessary**: Manual agent selection or micromanagement - the system handles this
+- **Unnecessary**: Memorizing all agent capabilities - the system routes intelligently
+
+**Simple Usage Approach:**
+1. **Focus on Your Goal**: Describe what you want to accomplish clearly
+2. **Use Natural Language**: Include domain keywords naturally ("security", "performance", "UI")
+3. **Trust the System**: Let SuperClaude activate appropriate agents automatically
+4. **Learn from Results**: Notice which agents activate and why, but don't force it
+
+---
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - Get up and running with basic commands
+- [Installation Guide](../Getting-Started/installation.md) - Setup and configuration
+- [Commands Guide](commands.md) - Master core commands that trigger agents
+
+**🌿 Recommended (Week 2-3)**
+- [Behavioral Modes](modes.md) - Context optimization and agent coordination
+- [Examples Cookbook](../Reference/examples-cookbook.md) - Practical patterns and workflows
+- [Best Practices](../Reference/best-practices.md) - Agent optimization strategies
+
+**🌳 Advanced (Month 2+)**
+- [MCP Servers](mcp-servers.md) - Enhanced capabilities through server integration
+- [Session Management](session-management.md) - Long-term workflows and persistence
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - System understanding
+
+**🔧 Expert Development**
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Framework development
+- [Testing & Debugging](../Developer-Guide/testing-debugging.md) - Quality procedures
+
+---
+
+**Your SuperClaude Agent Journey:**
+
+SuperClaude's agent system represents the best of both worlds: sophisticated coordination happening automatically behind a simple, intuitive interface. You get the benefit of 13 specialized experts without the complexity of managing them.
+
+**The Magic is in the Simplicity:**
+- Type `/sc:implement "secure user login"` and watch security engineers, backend architects, and frontend specialists coordinate seamlessly
+- No agent configuration, no manual routing, no complex setup - just describe your goal and let the system work
+- The more you use SuperClaude, the better you'll understand the patterns, but you never need to micromanage the agents
+
+**Start Simple, Stay Simple:**
+Begin with basic commands and let complexity emerge naturally. SuperClaude handles the orchestration so you can focus on building great software. The agent system grows with your needs while maintaining the same straightforward interface.
+
+🚀 **Ready to experience intelligent agent coordination? Try `/sc:brainstorm` and watch the magic happen.**

User-Guide/commands.md

@@ -0,0 +1,767 @@
+# SuperClaude Commands Guide 🛠️
+
+## 💡 Don't Overthink It - SuperClaude Tries to Help
+
+SuperClaude provides 21 specialized commands that automatically coordinate domain experts, MCP servers, and behavioral modes based on context. The system intelligently routes tasks to appropriate specialists while maintaining a simple, discoverable interface.
+
+**Auto-Activation Philosophy**: Type `/sc:implement "user auth"` and watch as the security specialist activates, Context7 provides authentication patterns, and quality gates ensure completeness.
+
+**Progressive Discovery**: Use `/sc:index` to explore commands relevant to your current context.
+
+## Core Philosophy
+
+**Core Principles:**
+- **Context-Aware Routing**: Commands analyze intent and activate appropriate specialists
+- **Safety First**: Dry-run options, backup creation, and validation gates
+- **Progressive Enhancement**: Simple tasks stay simple, complex tasks get expert attention
+- **Session Persistence**: Long-running workflows maintained across sessions
+
+**Intelligent Activation:**
+1. Parse command intent and parameters
+2. Analyze complexity and domain requirements
+3. Activate relevant specialists (frontend, backend, security, etc.)
+4. Connect appropriate MCP servers (Context7, Sequential, Magic)
+5. Apply behavioral modes (brainstorming, orchestration, etc.)
+6. Execute with quality gates and progress tracking
+
+---
+
+## Quick "Just Try These" List 🚀
+
+**Essential Commands (Start Here):**
+```bash
+/sc:brainstorm "mobile app idea"     # Interactive discovery
+/sc:analyze src/                      # Code analysis
+/sc:implement "user login"           # Feature implementation
+/sc:troubleshoot "API not working"   # Problem solving
+/sc:test --coverage                   # Quality assurance
+```
+
+**Discovery Pattern:**
+1. Use `/sc:index` to explore available commands
+2. Try `/sc:brainstorm` for project planning
+3. Progress to `/sc:implement` for development
+4. Use `/sc:reflect` to validate completion
+
+---
+
+**Realistic Command Assessment:**
+
+**Highly Mature** (🔥 Production Ready): brainstorm, analyze, implement, troubleshoot
+**Well Developed** (✅ Reliable): workflow, design, test, document, git
+**Solid Foundation** (🔧 Functional): improve, cleanup, build, load, save
+**Emerging** (🌱 Growing): spawn, task, estimate, reflect, select-tool
+**Experimental** (🧪 Testing): index, explain
+
+**Expectation**: Core commands deliver consistent results. Emerging commands are improving rapidly with each release.
+
+## Quick Reference 📋
+
+## Command Reference
+
+| Command | Category | Specialists | MCP Servers | Best For |
+|---------|----------|-------------|-------------|----------|
+| **brainstorm** | Discovery | architect, analyst | sequential, context7 | Requirements exploration |
+| **workflow** | Planning | architect, pm | sequential | Implementation planning |
+| **implement** | Development | frontend, backend, security | context7, magic | Feature creation |
+| **build** | Development | devops | - | Compilation, packaging |
+| **design** | Planning | architect, ux | - | System architecture |
+| **analyze** | Quality | analyzer | - | Code assessment |
+| **troubleshoot** | Debug | analyzer, devops | sequential | Problem diagnosis |
+| **explain** | Learning | - | - | Code explanation |
+| **improve** | Quality | analyzer | morphllm | Code enhancement |
+| **cleanup** | Quality | analyzer | morphllm | Technical debt |
+| **test** | Quality | qa-specialist | playwright | Testing, validation |
+| **document** | Quality | doc-specialist | - | Documentation |
+| **estimate** | Planning | pm | - | Project estimation |
+| **task** | Management | pm | serena | Task coordination |
+| **spawn** | Management | pm | serena | Complex orchestration |
+| **git** | Utility | devops | - | Version control |
+| **index** | Utility | - | - | Command discovery |
+| **load** | Session | - | serena | Context loading |
+| **save** | Session | - | serena | Session persistence |
+| **reflect** | Session | - | serena | Task validation |
+| **select-tool** | Meta | - | all | Tool optimization |
+
+**Selection Strategy**: Commands auto-activate based on keywords, file types, and project context. Use `/sc:select-tool` for optimization recommendations.
+
+## Development Commands 🔨
+
+### /sc:workflow - Implementation Planning
+
+**Purpose**: Generate structured implementation workflows from PRDs and feature requirements
+
+**Usage**:
+```bash
+/sc:workflow "user authentication system"
+/sc:workflow --strategy agile --format markdown
+/sc:workflow "payment integration" --depth detailed
+```
+
+**Expert Activation**: Architect + Project Manager
+**MCP Integration**: Sequential for structured analysis
+
+**Examples**:
+```bash
+# Basic workflow generation
+/sc:workflow "real-time chat feature"
+
+# Agile sprint planning
+/sc:workflow "e-commerce cart" --strategy agile --format sprint
+
+# Enterprise architecture
+/sc:workflow "microservices migration" --strategy enterprise
+```
+
+**Output**: Structured tasks, dependency mapping, time estimates, risk assessment
+
+### /sc:implement - Feature Implementation
+
+**Purpose**: Feature and code implementation with intelligent persona activation and MCP integration
+
+**Usage**:
+```bash
+/sc:implement "user login with JWT"
+/sc:implement --type frontend --framework react
+/sc:implement "REST API" --focus security --validate
+```
+
+**Expert Activation**: Context-dependent (frontend, backend, security, database)
+**MCP Integration**: Context7 (patterns), Magic (UI), Sequential (complex logic)
+
+**Examples**:
+```bash
+# Full-stack feature
+/sc:implement "user registration with email verification"
+
+# Frontend focus
+/sc:implement "responsive dashboard" --type frontend
+
+# Security-focused
+/sc:implement "OAuth integration" --focus security
+
+# API development
+/sc:implement "GraphQL mutations" --type backend --validate
+```
+
+**Auto-Activation Patterns**:
+- "UI", "component" → Frontend specialist + Magic MCP
+- "API", "endpoint" → Backend specialist + Context7
+- "auth", "security" → Security specialist + validation gates
+- "database", "schema" → Database specialist
+
+---
+
+### /sc:build - Project Building
+
+**Purpose**: Build, compile, and package projects with intelligent error handling and optimization
+
+**Usage**:
+```bash
+/sc:build
+/sc:build --optimize --parallel
+/sc:build --target production --fix-errors
+```
+
+**Expert Activation**: DevOps specialist
+**Build System Detection**: npm, webpack, cargo, maven, gradle, make
+
+**Examples**:
+```bash
+# Basic build
+/sc:build
+
+# Production optimization
+/sc:build --target production --optimize
+
+# Parallel compilation
+/sc:build --parallel --jobs 4
+
+# Error fixing
+/sc:build --fix-errors --verbose
+```
+
+**Common Issues & Solutions**:
+- **Missing dependencies**: Auto-installs with confirmation
+- **Version conflicts**: Suggests resolution strategies
+- **Memory issues**: Optimizes build parameters
+- **Type errors**: Provides TypeScript fixes
+
+---
+
+### /sc:design - System Design
+
+**Purpose**: Design system architecture, APIs, and component interfaces with comprehensive specifications
+
+**Usage**:
+```bash
+/sc:design "microservices architecture"
+/sc:design --type api --format openapi
+/sc:design "database schema" --focus performance
+```
+
+**Expert Activation**: Architect + UX Designer (for UI)
+**Output Formats**: Markdown, Mermaid diagrams, OpenAPI specs, ERD
+
+**Examples**:
+```bash
+# System architecture
+/sc:design "e-commerce platform architecture"
+
+# API specification
+/sc:design "REST API for blog" --type api --format openapi
+
+# Database design
+/sc:design "user management schema" --type database
+
+# Component architecture
+/sc:design "React component hierarchy" --type frontend
+```
+
+**Design Types**:
+- **system**: Full architecture with service boundaries
+- **api**: REST/GraphQL specifications
+- **database**: Schema design with relationships
+- **frontend**: Component and state architecture
+- **integration**: Service communication patterns
+
+## Analysis Commands 🔍
+
+### /sc:analyze - Code Analysis
+
+**Purpose**: Comprehensive code analysis across quality, security, performance, and architecture domains
+
+**Usage**:
+```bash
+/sc:analyze src/
+/sc:analyze --focus security --depth deep
+/sc:analyze . --format report --export html
+```
+
+**Expert Activation**: Analyzer + domain specialists based on focus
+**Language Support**: Python, JavaScript, TypeScript, Java, C++, Rust, Go, and more
+
+**Examples**:
+```bash
+# Full project analysis
+/sc:analyze .
+
+# Security audit
+/sc:analyze src/ --focus security --depth deep
+
+# Performance bottlenecks
+/sc:analyze --focus performance --profile
+
+# Architecture review
+/sc:analyze --focus architecture --dependencies
+```
+
+**Focus Areas**:
+- **quality**: Code smells, maintainability, complexity
+- **security**: Vulnerabilities, best practices, compliance
+- **performance**: Bottlenecks, optimization opportunities
+- **architecture**: Dependencies, coupling, design patterns
+
+---
+
+### /sc:troubleshoot - Problem Diagnosis
+
+**Purpose**: Diagnose and resolve issues in code, builds, deployments, and system behavior
+
+**Usage**:
+```bash
+/sc:troubleshoot "API returns 500 error"
+/sc:troubleshoot --logs server.log --focus performance
+/sc:troubleshoot --type build --verbose
+```
+
+**Expert Activation**: Analyzer + DevOps (for deployment issues)
+**MCP Integration**: Sequential for systematic debugging
+
+**Examples**:
+```bash
+# General issue diagnosis
+/sc:troubleshoot "users can't login"
+
+# Build failures
+/sc:troubleshoot --type build --fix-suggestions
+
+# Performance issues
+/sc:troubleshoot "slow page load" --logs access.log
+
+# Database problems
+/sc:troubleshoot "connection timeout" --focus database
+```
+
+**Systematic Methodology**:
+1. **Symptom Analysis**: Parse error messages and logs
+2. **Root Cause Investigation**: Follow dependency chains
+3. **Hypothesis Testing**: Validate potential causes
+4. **Solution Ranking**: Prioritize fixes by impact/effort
+5. **Verification**: Ensure resolution doesn't break other components
+
+---
+
+### /sc:explain - Code & Concept Explanation
+
+**Purpose**: Provide clear explanations of code, concepts, and system behavior with educational clarity
+
+**Usage**:
+```bash
+/sc:explain "async/await in JavaScript"
+/sc:explain src/auth.py --level beginner
+/sc:explain --concept "dependency injection" --examples
+```
+
+**Teaching Approaches**: Beginner, intermediate, expert levels with progressive detail
+**Educational Focus**: Concepts, patterns, best practices, common pitfalls
+
+**Examples**:
+```bash
+# Code explanation
+/sc:explain src/components/UserAuth.jsx
+
+# Concept clarification
+/sc:explain "microservices vs monolith" --pros-cons
+
+# Pattern explanation
+/sc:explain "observer pattern" --examples react
+
+# Beginner-friendly
+/sc:explain "what is REST API" --level beginner --examples
+```
+
+**Explanation Styles**:
+- **code-walkthrough**: Line-by-line code analysis
+- **concept**: High-level explanation with examples
+- **pattern**: Design pattern with use cases
+- **comparison**: Side-by-side analysis of approaches
+- **tutorial**: Step-by-step learning progression
+
+## Quality Commands ✨
+
+### /sc:improve - Code Enhancement
+
+**Purpose**: Apply systematic improvements to code quality, performance, and maintainability
+
+**Usage**:
+```bash
+/sc:improve src/components/
+/sc:improve --type performance --preview
+/sc:improve . --focus maintainability --safe-mode
+```
+
+**Expert Activation**: Analyzer + Performance Engineer (for performance focus)
+**MCP Integration**: Morphllm for pattern-based improvements
+
+**Examples**:
+```bash
+# General improvements
+/sc:improve src/
+
+# Performance optimization
+/sc:improve --type performance --measure-impact
+
+# Code quality enhancement
+/sc:improve --focus quality --preview --backup
+
+# Safe refactoring
+/sc:improve legacy/ --safe-mode --tests-required
+```
+
+**Improvement Types**:
+- **performance**: Optimization, caching, algorithm improvements
+- **quality**: Code smells, readability, maintainability
+- **security**: Vulnerability fixes, best practices
+- **accessibility**: UI/UX improvements
+- **architecture**: Design pattern application
+
+---
+
+### /sc:cleanup - Technical Debt Reduction
+
+**Purpose**: Systematically clean up code, remove dead code, and optimize project structure
+
+**Usage**:
+```bash
+/sc:cleanup
+/sc:cleanup --type imports --organize
+/sc:cleanup --dead-code --confirm-before-delete
+```
+
+**Expert Activation**: Analyzer
+**MCP Integration**: Morphllm for pattern-based cleanup
+
+**Examples**:
+```bash
+# Full project cleanup
+/sc:cleanup --comprehensive --backup
+
+# Import optimization
+/sc:cleanup --type imports --sort --remove-unused
+
+# Dead code removal
+/sc:cleanup --dead-code --analyze-usage
+
+# File organization
+/sc:cleanup --organize-files --follow-conventions
+```
+
+**Cleanup Operations**:
+- **dead-code**: Unused functions, variables, imports
+- **imports**: Sort, deduplicate, organize imports
+- **formatting**: Consistent code style
+- **files**: Directory organization and naming
+- **dependencies**: Remove unused packages
+
+---
+
+### /sc:test - Testing & Quality Assurance
+
+**Purpose**: Execute tests with coverage analysis and automated quality reporting
+
+**Usage**:
+```bash
+/sc:test
+/sc:test --type e2e --coverage
+/sc:test --fix --watch
+```
+
+**Expert Activation**: QA Specialist
+**MCP Integration**: Playwright (for E2E testing)
+
+**Examples**:
+```bash
+# Run all tests
+/sc:test --coverage --report
+
+# Unit tests only
+/sc:test --type unit --watch
+
+# E2E browser testing
+/sc:test --type e2e --browsers chrome,firefox
+
+# Fix failing tests
+/sc:test --fix --preview-changes
+```
+
+**Test Types**:
+- **unit**: Individual function/component testing
+- **integration**: Module interaction testing
+- **e2e**: End-to-end browser automation
+- **performance**: Load and stress testing
+- **accessibility**: WCAG compliance validation
+
+## Documentation Commands 📝
+
+### /sc:document - Documentation Generation
+
+**Purpose**: Generate focused documentation for components, functions, APIs, and features
+
+**Usage**:
+```bash
+/sc:document src/api/
+/sc:document --type api --format openapi
+/sc:document . --style technical --audience developers
+```
+
+**Expert Activation**: Documentation Specialist
+**Documentation Types**: API docs, README, inline comments, user guides
+
+**Examples**:
+```bash
+# Component documentation
+/sc:document src/components/ --inline-comments
+
+# API documentation
+/sc:document --type api --format swagger
+
+# User documentation
+/sc:document --type user-guide --audience end-users
+
+# Technical documentation
+/sc:document --style technical --diagrams
+```
+
+**Documentation Styles**:
+- **technical**: Developer-focused with code examples
+- **user**: End-user guides and tutorials
+- **api**: REST/GraphQL API specifications
+- **inline**: Code comments and docstrings
+- **architectural**: System design documentation
+
+## Project Management Commands 📊
+
+### /sc:estimate - Project Estimation
+
+**Purpose**: Provide development estimates for tasks, features, or projects with intelligent analysis
+
+**Usage**: `/sc:estimate "user authentication system"`, `/sc:estimate --detailed --team-size 3`
+
+**Expert Activation**: Project Manager
+**Features**: Time estimates, complexity analysis, resource allocation, risk assessment
+
+**Examples**: Project estimates, sprint planning, resource allocation, timeline forecasting
+
+---
+
+### /sc:task - Project Management
+
+**Purpose**: Execute complex tasks with intelligent workflow management and delegation
+
+**Usage**: `/sc:task "implement payment system"`, `/sc:task --breakdown --priority high`
+
+**Expert Activation**: Project Manager
+**MCP Integration**: Serena for task persistence
+**Features**: Task breakdown, priority management, cross-session tracking, dependency mapping
+
+---
+
+### /sc:spawn - Meta-System Orchestration
+
+**Purpose**: Meta-system task orchestration with intelligent breakdown and delegation
+
+**Usage**: `/sc:spawn "full-stack e-commerce platform"`, `/sc:spawn --parallel --monitor`
+
+**Expert Activation**: Project Manager + Multiple domain specialists
+**Features**: Complex workflow orchestration, parallel execution, progress monitoring, resource management
+
+## Version Control Commands 🔄
+
+### /sc:git - Version Control
+
+**Purpose**: Git operations with intelligent commit messages and workflow optimization
+
+**Usage**: `/sc:git commit "add user auth"`, `/sc:git --smart-messages --conventional`
+
+**Expert Activation**: DevOps specialist
+**Features**: Smart commit messages, branch management, conflict resolution, workflow optimization
+
+**Examples**: Intelligent commits, branch strategies, merge conflict resolution, release management
+
+## Utility Commands 🔧
+
+### /sc:index - Command Discovery
+
+**Purpose**: Generate comprehensive project documentation and knowledge base with intelligent organization
+
+**Usage**: `/sc:index`, `/sc:index --category development`, `/sc:index --search "testing"`
+
+**Features**: Command discovery, capability exploration, contextual recommendations, usage patterns
+
+**Examples**: Find relevant commands, explore capabilities, discover usage patterns, get contextual help
+
+---
+
+### /sc:load - Session Context Loading
+
+**Purpose**: Session lifecycle management with Serena MCP integration for project context loading
+
+**Usage**: `/sc:load src/`, `/sc:load --focus architecture`, `/sc:load "previous session"`
+
+**Expert Activation**: Context analysis
+**MCP Integration**: Serena for project memory
+**Features**: Project structure analysis, context restoration, session initialization, intelligent onboarding
+
+## Session & Intelligence Commands 🧠
+
+### /sc:brainstorm - Interactive Requirements Discovery
+
+**Purpose**: Interactive requirements discovery through Socratic dialogue and systematic exploration
+
+**Usage**: `/sc:brainstorm "mobile app idea"`, `/sc:brainstorm --strategy systematic --depth deep`
+
+**Expert Activation**: Architect + Analyst + PM
+**MCP Integration**: Sequential for structured reasoning, Context7 for patterns
+
+**Features**: Socratic dialogue, requirement elicitation, PRD generation, feasibility analysis, creative problem solving
+
+---
+
+### /sc:reflect - Task Reflection & Validation
+
+**Purpose**: Task reflection and validation using Serena MCP analysis capabilities
+
+**Usage**: `/sc:reflect`, `/sc:reflect --type completion`, `/sc:reflect "payment integration"`
+
+**Expert Activation**: Context analysis
+**MCP Integration**: Serena for intelligence analysis
+
+**Features**: Progress analysis, completion validation, quality assessment, next steps recommendation
+
+---
+
+### /sc:save - Session Persistence
+
+**Purpose**: Session lifecycle management with Serena MCP integration for session context persistence
+
+**Usage**: `/sc:save "payment-integration-complete"`, `/sc:save --checkpoint --description "auth module done"`
+
+**Expert Activation**: Session management
+**MCP Integration**: Serena for context persistence
+
+**Features**: Session checkpointing, context preservation, progress tracking, cross-session continuity
+
+---
+
+### /sc:select-tool - Intelligent Tool Selection
+
+**Purpose**: Intelligent MCP tool selection based on complexity scoring and operation analysis
+
+**Usage**: `/sc:select-tool "implement user auth"`, `/sc:select-tool --analyze-complexity --recommend`
+
+**Expert Activation**: Meta-analysis
+**MCP Integration**: All servers for capability assessment
+
+**Features**: Complexity analysis, tool recommendation, MCP coordination, optimization strategies, resource planning
+
+## Command Tips & Patterns 💡
+
+**Effective Flag Combinations:**
+```bash
+# Development workflow
+/sc:analyze --focus quality && /sc:improve --preview && /sc:test --coverage
+
+# Production preparation
+/sc:build --optimize --target production && /sc:test --type e2e
+
+# Deep analysis
+/sc:analyze --focus security --depth deep --export report
+
+# Safe refactoring
+/sc:improve --safe-mode --backup --tests-required
+```
+
+**Command Chaining Strategies:**
+- **Analysis → Improvement → Testing**: Quality enhancement workflow
+- **Brainstorm → Design → Implement**: Feature development lifecycle
+- **Load → Analyze → Reflect**: Project onboarding pattern
+- **Build → Test → Document**: Release preparation sequence
+
+**Common Workflow Patterns:**
+
+**New Project Onboarding:**
+```bash
+/sc:load . → /sc:analyze --comprehensive → /sc:document --type overview → /sc:save "project-analyzed"
+```
+
+**Feature Development:**
+```bash
+/sc:brainstorm "feature idea" → /sc:design → /sc:implement → /sc:test → /sc:document
+```
+
+**Bug Investigation:**
+```bash
+/sc:troubleshoot "issue description" → /sc:analyze --focus problem-area → /sc:improve --fix
+```
+
+**Pre-Deployment:**
+```bash
+/sc:test --comprehensive → /sc:analyze --focus security → /sc:build --production → /sc:git commit
+```
+
+**Quality Improvement:**
+```bash
+/sc:analyze --focus quality → /sc:cleanup → /sc:improve → /sc:test → /sc:reflect
+```
+
+**Common Issues & Solutions:**
+
+**Command Not Found:**
+- Verify SuperClaude installation: `SuperClaude --version`
+- Check component installation: `SuperClaude install --list-components`
+- Restart Claude Code session
+
+**Slow Performance:**
+- Use `--scope file` to limit analysis scope
+- Enable specific MCP servers only: `--c7 --seq` instead of `--all-mcp`
+- Use `--concurrency 2` to limit parallel operations
+
+**MCP Server Issues:**
+- Check server status: `ls ~/.claude/.claude.json`
+- Restart with: `SuperClaude install --components mcp --force`
+- Use `--no-mcp` for native-only execution
+
+**Scope Management:**
+- Use `--scope file|module|project` to control analysis depth
+- Limit with `--focus` specific areas
+- Use `--dry-run` for preview without execution
+
+---
+
+## Final Notes 📝
+
+**Command Reliability & Evolution:**
+
+SuperClaude commands are actively developed with regular improvements. Core commands (brainstorm, analyze, implement) are production-ready, while emerging commands (spawn, estimate) are rapidly maturing.
+
+**Discovery-Based Learning:**
+1. Start with `/sc:index` to explore available commands
+2. Use `/sc:brainstorm` for project-specific guidance
+3. Try commands in `--dry-run` mode first
+4. Progress from simple to complex commands naturally
+5. Save successful patterns with `/sc:save`
+
+**Getting Help:**
+- In-app: `/sc:index --help` or `/sc:explain "command name"`
+- Documentation: [SuperClaude Guides](../README.md)
+- Issues: [GitHub Repository](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
+- Community: [Discussions](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions)
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - Get up and running
+- [Installation Guide](../Getting-Started/installation.md) - Setup and configuration
+- This Commands Guide - Master core commands
+
+**🌿 Recommended (Week 2-3)**
+- [Behavioral Modes](modes.md) - Context optimization
+- [Agents Guide](agents.md) - Specialist coordination
+- [Examples Cookbook](../Reference/examples-cookbook.md) - Practical patterns
+
+**🌳 Advanced (Month 2+)**
+- [MCP Servers](mcp-servers.md) - Enhanced capabilities
+- [Best Practices](../Reference/best-practices.md) - Optimization mastery
+- [Session Management](session-management.md) - Long-term workflows
+
+**🔧 Expert**
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - System understanding
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Framework development
+
+## Command Flags & Options
+
+**Common Flags Across Commands:**
+
+**Scope Control**: `--scope file|module|project|system`
+**Focus Areas**: `--focus quality|security|performance|architecture`
+**Output Control**: `--format text|json|html|markdown`
+**Safety**: `--dry-run`, `--backup`, `--safe-mode`
+**Performance**: `--parallel`, `--concurrency N`
+**MCP Control**: `--c7`, `--seq`, `--magic`, `--morph`, `--serena`, `--play`
+
+**Expert Activation System:**
+- **Context-based**: Keywords trigger appropriate specialists
+- **Domain-specific**: Frontend, backend, security, DevOps, QA
+- **Progressive**: Simple tasks use fewer experts, complex tasks activate multiple
+- **Intelligent routing**: Best expert for each subtask
+
+**MCP Server Integration:**
+- **Context7**: Documentation and patterns
+- **Sequential**: Multi-step reasoning
+- **Magic**: UI component generation
+- **Playwright**: Browser automation
+- **Morphllm**: Code transformation
+- **Serena**: Session and memory management
+
+---
+
+**Your SuperClaude Journey:**
+
+SuperClaude grows with you. Start simple with `/sc:brainstorm` and `/sc:analyze`, then discover advanced capabilities naturally. Each command learns from your usage patterns and becomes more helpful over time.
+
+🚀 **The magic happens when you stop thinking about tools and start focusing on your goals.** SuperClaude handles the orchestration, expert coordination, and quality gates automatically.
+
+**Remember**: There's no wrong way to explore. Use `/sc:index` whenever you need guidance, and don't hesitate to experiment with new commands and flag combinations.

User-Guide/flags.md

@@ -0,0 +1,780 @@
+# SuperClaude Framework Flags User Guide 🏁
+
+## 🤖 Most Flags Activate Automatically - Don't Stress About It!
+
+SuperClaude's intelligent flag system automatically detects task complexity and context, then activates appropriate flags behind the scenes. You get optimized performance without memorizing flag combinations.
+
+**Intelligent Auto-Activation**: Type `/sc:analyze large-codebase/` → `--think-hard` + `--serena` + `--orchestrate` activate automatically. Type complex multi-file operations → `--task-manage` + `--delegate` optimize execution. Work under resource pressure → `--uc` compresses output.
+
+**Manual Override Available**: When you want specific behavior, flags provide precise control. But in most cases, SuperClaude's automatic selection delivers optimal results.
+
+---
+
+## 🚀 Just Try These (No Flag Knowledge Required)
+
+**Commands Work Great Without Flags:**
+```bash
+# These automatically get optimal flags
+/sc:brainstorm "mobile fitness app"
+# → Auto-activates: --brainstorm, --think, --context7
+
+/sc:analyze src/ --focus security  
+# → Auto-activates: --think-hard, --serena, --orchestrate
+
+/sc:implement "user authentication system"
+# → Auto-activates: --task-manage, --c7, --magic, --validate
+
+/sc:troubleshoot "API performance issues"
+# → Auto-activates: --think-hard, --seq, --serena, --introspect
+
+/sc:improve legacy-code/ --focus maintainability
+# → Auto-activates: --task-manage, --morph, --serena, --safe-mode
+```
+
+**Behind-the-Scenes Optimization:**
+- **Context Analysis**: Keywords trigger appropriate specialists and tools
+- **Complexity Detection**: Multi-file operations get coordination flags
+- **Resource Awareness**: System load triggers efficiency optimizations
+- **Quality Gates**: Risky operations automatically enable safety flags
+- **Performance Tuning**: Optimal tool combinations selected automatically
+
+**When Manual Flags Help:**
+- Override automatic detection: `--no-mcp` for lightweight execution
+- Force specific behavior: `--uc` for compressed output
+- Learning and exploration: `--introspect` to see reasoning
+- Resource control: `--concurrency 2` to limit parallel operations
+
+---
+
+## What Are Flags? 🤔
+
+**Flags are Modifiers** that adjust SuperClaude's behavior for specific contexts and requirements:
+
+**Flag Syntax:**
+```bash
+/sc:command [args] --flag-name [value]
+
+# Examples
+/sc:analyze src/ --focus security --depth deep
+/sc:implement "auth" --brainstorm --task-manage --validate
+/sc:troubleshoot issue/ --think-hard --uc --concurrency 3
+```
+
+**Two Types of Activation:**
+1. **Automatic** (90% of use): SuperClaude detects context and activates optimal flags
+2. **Manual** (10% of use): You override or specify exact behavior needed
+
+**Flag Functions:**
+- **Behavioral Modes**: `--brainstorm`, `--introspect`, `--task-manage`
+- **Tool Selection**: `--c7`, `--seq`, `--magic`, `--morph`, `--serena`, `--play`
+- **Analysis Depth**: `--think`, `--think-hard`, `--ultrathink`
+- **Efficiency Control**: `--uc`, `--concurrency`, `--scope`
+- **Safety & Quality**: `--safe-mode`, `--validate`, `--dry-run`
+
+**Auto-Activation vs Manual Override:**
+- **Auto**: `/sc:implement "React dashboard"` → Magic + Context7 + task coordination
+- **Manual**: `/sc:implement "simple function" --no-mcp` → Native-only execution
+
+## Flag Categories 📂
+
+### Planning & Analysis Flags 🧠
+
+**Thinking Depth Control:**
+
+**`--think`** - Standard Analysis (~4K tokens)
+- **Auto-Triggers**: Multi-component analysis, moderate complexity
+- **Manual Use**: Force structured thinking for simple tasks
+- **Enables**: Sequential MCP for systematic reasoning
+```bash
+/sc:analyze auth-system/ --think
+# → Structured analysis with evidence-based reasoning
+```
+
+**`--think-hard`** - Deep Analysis (~10K tokens)  
+- **Auto-Triggers**: Architectural analysis, system-wide dependencies
+- **Manual Use**: Force comprehensive analysis
+- **Enables**: Sequential + Context7 for deep understanding
+```bash
+/sc:troubleshoot "performance degradation" --think-hard
+# → Comprehensive root cause analysis with framework patterns
+```
+
+**`--ultrathink`** - Maximum Analysis (~32K tokens)
+- **Auto-Triggers**: Critical system redesign, legacy modernization
+- **Manual Use**: Force maximum analytical depth
+- **Enables**: All MCP servers for comprehensive capability
+```bash
+/sc:analyze enterprise-architecture/ --ultrathink
+# → Maximum depth with all tools and reasoning capacity
+```
+
+**Mode Activation Flags:**
+
+**`--brainstorm`** / **`--bs`** - Interactive Discovery
+- **Auto-Triggers**: Vague requests, exploration keywords
+- **Manual Use**: Force collaborative requirement discovery
+```bash
+/sc:implement "better user experience" --brainstorm
+# → Socratic questions to clarify requirements before implementation
+```
+
+**`--introspect`** - Reasoning Transparency
+- **Auto-Triggers**: Error recovery, learning contexts
+- **Manual Use**: Expose decision-making process for learning
+```bash
+/sc:analyze complex-algorithm/ --introspect
+# → Transparent reasoning with 🤔, 🎯, ⚡ markers
+```
+
+### Efficiency & Control Flags ⚡
+
+**Output Compression:**
+
+**`--uc`** / **`--ultracompressed`** - Token Efficiency (30-50% reduction)
+- **Auto-Triggers**: Context usage >75%, large operations, resource pressure
+- **Manual Use**: Force compressed communication
+- **Effect**: Symbol-enhanced output while preserving ≥95% information quality
+```bash
+/sc:analyze large-project/ --uc
+# → "auth.js:45 → 🛡️ sec risk in user val()" vs verbose explanations
+```
+
+**`--token-efficient`** - Moderate Compression
+- **Auto-Triggers**: Medium resource pressure, efficiency requirements
+- **Manual Use**: Balance between detail and efficiency
+```bash
+/sc:troubleshoot "memory leak" --token-efficient
+# → Structured but concise problem analysis
+```
+
+**Execution Control:**
+
+**`--concurrency [n]`** - Parallel Operation Control (1-15)
+- **Auto-Triggers**: Resource optimization needs
+- **Manual Use**: Control system load and parallel processing
+```bash
+/sc:improve large-codebase/ --concurrency 3
+# → Limit to 3 parallel operations for resource management
+```
+
+**`--scope [file|module|project|system]`** - Analysis Boundary
+- **Auto-Triggers**: Analysis boundary detection
+- **Manual Use**: Explicitly define operational scope
+```bash
+/sc:analyze src/auth/ --scope module
+# → Focus analysis on authentication module only
+```
+
+**`--loop`** / **`--iterations [n]`** - Iterative Improvement
+- **Auto-Triggers**: "polish", "refine", "enhance", "improve" keywords
+- **Manual Use**: Force iterative improvement cycles
+```bash
+/sc:improve user-interface/ --loop --iterations 3
+# → 3 improvement cycles with validation gates
+```
+
+### Focus & Specialization Flags 🎯
+
+**Domain-Specific Analysis:**
+
+**`--focus [domain]`** - Target Expertise Application
+- **Available Domains**: `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing`
+- **Auto-Triggers**: Domain-specific keywords and file patterns
+- **Manual Use**: Force specific analytical perspective
+
+```bash
+# Security-focused analysis
+/sc:analyze payment-system/ --focus security
+# → Security specialist + vulnerability assessment + compliance validation
+
+# Performance optimization focus  
+/sc:improve api-endpoints/ --focus performance
+# → Performance engineer + bottleneck analysis + optimization patterns
+
+# Architecture evaluation
+/sc:analyze microservices/ --focus architecture
+# → System architect + design pattern analysis + scalability assessment
+
+# Quality improvement
+/sc:review codebase/ --focus quality
+# → Quality engineer + code smell detection + maintainability analysis
+```
+
+**Task Management:**
+
+**`--task-manage`** / **`--delegate`** - Complex Coordination
+- **Auto-Triggers**: >3 steps, >2 directories, >3 files
+- **Manual Use**: Force hierarchical task organization for simple tasks
+```bash
+/sc:implement "simple feature" --task-manage
+# → Phase-based approach with progress tracking even for simple tasks
+```
+
+**`--delegate [auto|files|folders]`** - Orchestration Strategy
+- **Auto-Triggers**: >7 directories OR >50 files OR complexity >0.8
+- **Manual Use**: Control delegation strategy
+```bash
+/sc:refactor enterprise-codebase/ --delegate folders
+# → Delegate by directory structure for systematic organization
+```
+
+### Tool Integration Flags 🛠️
+
+**MCP Server Control:**
+
+**Individual Server Flags:**
+- **`--c7`** / **`--context7`**: Documentation and framework patterns
+- **`--seq`** / **`--sequential`**: Structured multi-step reasoning  
+- **`--magic`**: Modern UI component generation
+- **`--morph`** / **`--morphllm`**: Pattern-based code transformation
+- **`--serena`**: Semantic understanding and project memory
+- **`--play`** / **`--playwright`**: Browser automation and testing
+
+```bash
+# Specific server combinations
+/sc:implement "dashboard" --magic --c7
+# → UI generation + framework patterns
+
+/sc:analyze complex-issue/ --seq --serena  
+# → Structured reasoning + project context
+
+/sc:improve legacy-code/ --morph --serena --seq
+# → Pattern transformation + context + systematic analysis
+```
+
+**Server Group Control:**
+
+**`--all-mcp`** - Maximum Capability
+- **Auto-Triggers**: Maximum complexity scenarios, multi-domain problems
+- **Manual Use**: Force all tools for comprehensive capability
+```bash
+/sc:implement "enterprise-platform" --all-mcp
+# → All 6 MCP servers coordinated for maximum capability
+```
+
+**`--no-mcp`** - Native-Only Execution
+- **Auto-Triggers**: Performance priority, simple tasks
+- **Manual Use**: Force lightweight execution without MCP overhead
+```bash
+/sc:explain "simple function" --no-mcp
+# → Fast native response without MCP server coordination
+```
+
+**Tool Optimization:**
+
+**`--orchestrate`** - Intelligent Tool Selection
+- **Auto-Triggers**: Multi-tool operations, performance constraints, >3 files
+- **Manual Use**: Force optimal tool coordination
+```bash
+/sc:refactor components/ --orchestrate
+# → Optimal tool selection and parallel execution coordination
+```
+
+### Safety & Validation Flags 🛡️
+
+**Risk Management:**
+
+**`--validate`** - Pre-execution Risk Assessment
+- **Auto-Triggers**: Risk score >0.7, resource usage >75%, production environment
+- **Manual Use**: Force validation gates for any operation
+```bash
+/sc:implement "payment-processing" --validate
+# → Risk assessment + validation gates before implementation
+```
+
+**`--safe-mode`** - Maximum Conservative Execution
+- **Auto-Triggers**: Resource usage >85%, production environment, critical operations
+- **Manual Use**: Force maximum safety protocols
+- **Auto-Enables**: `--uc` for efficiency, `--validate` for safety
+```bash
+/sc:improve production-database/ --safe-mode
+# → Conservative execution + auto-backup + rollback planning
+```
+
+**Preview & Testing:**
+
+**`--dry-run`** - Preview Without Execution
+- **Manual Use**: Preview changes without applying them
+```bash
+/sc:cleanup legacy-code/ --dry-run
+# → Show what would be cleaned up without making changes
+```
+
+**`--backup`** - Force Backup Creation
+- **Auto-Triggers**: Risky operations, file modifications
+- **Manual Use**: Ensure backup creation before operations
+```bash
+/sc:refactor critical-module/ --backup
+# → Create backup before refactoring operations
+```
+
+**`--tests-required`** - Mandate Test Validation
+- **Auto-Triggers**: Critical code changes, production modifications
+- **Manual Use**: Force test execution before proceeding
+```bash
+/sc:improve auth-system/ --tests-required
+# → Run tests and require passing before improvement application
+```
+
+### Execution Control Flags 🎛️
+
+**Workflow Management:**
+
+**`--parallel`** - Force Parallel Execution
+- **Auto-Triggers**: Independent operations, >3 files, multi-tool scenarios
+- **Manual Use**: Force parallel processing for eligible operations
+```bash
+/sc:analyze multiple-modules/ --parallel
+# → Analyze modules concurrently instead of sequentially
+```
+
+**`--sequential`** - Force Sequential Execution  
+- **Manual Use**: Override parallel processing for dependency reasons
+```bash
+/sc:implement "multi-step-feature" --sequential
+# → Force step-by-step execution with dependencies
+```
+
+**Resource Control:**
+
+**`--memory-limit [MB]`** - Memory Usage Control
+- **Auto-Triggers**: Large operations, resource constraints
+- **Manual Use**: Explicit memory management
+```bash
+/sc:analyze large-dataset/ --memory-limit 2048
+# → Limit analysis to 2GB memory usage
+```
+
+**`--timeout [seconds]`** - Operation Timeout
+- **Auto-Triggers**: Complex operations, MCP server timeouts
+- **Manual Use**: Set explicit timeout boundaries
+```bash
+/sc:troubleshoot "complex-performance-issue" --timeout 300
+# → 5-minute timeout for troubleshooting analysis
+```
+
+**Output Control:**
+
+**`--format [text|json|html|markdown]`** - Output Format
+- **Auto-Triggers**: Analysis export, documentation generation
+- **Manual Use**: Specify exact output format
+```bash
+/sc:analyze api-performance/ --format json --export report.json
+# → JSON-formatted analysis results for processing
+```
+
+**`--verbose`** / **`--quiet`** - Verbosity Control
+- **Manual Use**: Override automatic verbosity decisions
+```bash
+/sc:build project/ --verbose
+# → Detailed build output and progress information
+
+/sc:test suite/ --quiet  
+# → Minimal output, results only
+```
+
+## Common Flag Combinations 🔗
+
+**Development Workflow Patterns:**
+
+**Full Analysis & Improvement:**
+```bash
+/sc:analyze codebase/ --think-hard --all-mcp --orchestrate
+# → Deep analysis + all tools + optimal coordination
+```
+
+**Safe Production Changes:**
+```bash
+/sc:improve production-api/ --safe-mode --validate --backup --tests-required
+# → Maximum safety protocols for production modifications
+```
+
+**Rapid Prototyping:**
+```bash
+/sc:implement "quick-feature" --magic --c7 --no-validate
+# → Fast UI generation + patterns without safety overhead
+```
+
+**Large-Scale Refactoring:**
+```bash
+/sc:refactor legacy-system/ --task-manage --serena --morph --parallel --backup
+# → Systematic coordination + context + transformation + safety
+```
+
+**Performance Investigation:**
+```bash
+/sc:troubleshoot "slow-performance" --think-hard --focus performance --seq --play
+# → Deep analysis + performance focus + reasoning + browser testing
+```
+
+**Learning & Understanding:**
+```bash
+/sc:analyze new-codebase/ --introspect --brainstorm --c7 --think
+# → Transparent reasoning + discovery + documentation + analysis
+```
+
+**Resource-Constrained Environments:**
+```bash
+/sc:implement "feature" --uc --concurrency 1 --no-mcp --scope file
+# → Compressed output + limited resources + lightweight execution
+```
+
+**Quality Assurance Workflow:**
+```bash
+/sc:review code-changes/ --focus quality --validate --tests-required --think
+# → Quality analysis + validation + testing + structured reasoning
+```
+
+**Documentation Generation:**
+```bash
+/sc:document api/ --c7 --magic --format markdown --focus accessibility
+# → Documentation patterns + UI examples + accessible format
+```
+
+**Complex Architecture Design:**
+```bash
+/sc:design "microservices-platform" --ultrathink --brainstorm --all-mcp --orchestrate
+# → Maximum analysis + discovery + all tools + optimal coordination
+```
+
+## Flag Reference Quick Cards 📋
+
+### 🧠 Analysis & Thinking Flags
+| Flag | Purpose | Auto-Trigger | Token Impact |
+|------|---------|--------------|--------------|
+| `--think` | Standard analysis | Multi-component tasks | ~4K tokens |
+| `--think-hard` | Deep analysis | Architectural tasks | ~10K tokens |
+| `--ultrathink` | Maximum analysis | Critical system work | ~32K tokens |
+| `--brainstorm` | Interactive discovery | Vague requirements | Variable |
+| `--introspect` | Reasoning transparency | Learning contexts | +10% detail |
+
+### ⚡ Efficiency & Performance Flags  
+| Flag | Purpose | Auto-Trigger | Performance Impact |
+|------|---------|--------------|-------------------|
+| `--uc` | Token compression | >75% context usage | 30-50% reduction |
+| `--token-efficient` | Moderate compression | Resource pressure | 15-30% reduction |
+| `--concurrency N` | Parallel control | Multi-file ops | +45% speed |
+| `--orchestrate` | Tool optimization | Complex coordination | +30% efficiency |
+| `--scope [level]` | Boundary control | Analysis scope | Focused execution |
+
+### 🛠️ Tool Integration Flags
+| Flag | MCP Server | Auto-Trigger | Best For |
+|------|------------|--------------|----------|
+| `--c7` / `--context7` | Context7 | Library imports | Documentation, patterns |
+| `--seq` / `--sequential` | Sequential | Complex debugging | Systematic reasoning |
+| `--magic` | Magic | UI requests | Component generation |
+| `--morph` / `--morphllm` | Morphllm | Multi-file edits | Pattern transformation |
+| `--serena` | Serena | Symbol operations | Project memory |
+| `--play` / `--playwright` | Playwright | Browser testing | E2E automation |
+| `--all-mcp` | All servers | Max complexity | Comprehensive capability |
+| `--no-mcp` | None | Simple tasks | Lightweight execution |
+
+### 🎯 Focus & Specialization Flags
+| Flag | Domain | Expert Activation | Use Case |
+|------|--------|------------------|----------|
+| `--focus security` | Security | Security engineer | Vulnerability analysis |
+| `--focus performance` | Performance | Performance engineer | Optimization |
+| `--focus quality` | Quality | Quality engineer | Code review |
+| `--focus architecture` | Architecture | System architect | Design analysis |
+| `--focus accessibility` | Accessibility | UX specialist | Compliance validation |
+| `--focus testing` | Testing | QA specialist | Test strategy |
+
+### 🛡️ Safety & Control Flags
+| Flag | Purpose | Auto-Trigger | Safety Level |
+|------|---------|--------------|--------------|
+| `--safe-mode` | Maximum safety | Production ops | Maximum |
+| `--validate` | Risk assessment | High-risk ops | High |
+| `--backup` | Force backup | File modifications | Standard |
+| `--dry-run` | Preview only | Manual testing | Preview |
+| `--tests-required` | Mandate testing | Critical changes | Validation |
+
+### 📋 Workflow & Task Flags  
+| Flag | Purpose | Auto-Trigger | Coordination |
+|------|---------|--------------|--------------|
+| `--task-manage` | Hierarchical organization | >3 steps | Phase-based |
+| `--delegate [mode]` | Sub-task routing | >50 files | Intelligent routing |
+| `--loop` | Iterative cycles | "improve" keywords | Quality cycles |
+| `--iterations N` | Cycle count | Specific improvements | Controlled iteration |
+| `--parallel` | Force concurrency | Independent ops | Performance |
+
+## Advanced Flag Usage 🚀
+
+### Context-Aware Flag Selection
+
+**Adaptive Flagging Based on Project Type:**
+
+**React/Frontend Projects:**
+```bash
+# Automatically optimized for React development
+/sc:implement "user-dashboard" 
+# → Auto-flags: --magic --c7 --focus accessibility --orchestrate
+
+# Manual optimization for specific needs
+/sc:implement "dashboard" --magic --c7 --play --focus accessibility
+# → UI generation + patterns + testing + accessibility validation
+```
+
+**Backend/API Projects:**
+```bash
+# Automatically optimized for backend development  
+/sc:implement "payment-api"
+# → Auto-flags: --focus security --validate --c7 --seq
+
+# Manual security-first approach
+/sc:implement "api" --focus security --validate --backup --tests-required
+# → Security analysis + validation + safety protocols
+```
+
+**Legacy Modernization:**
+```bash
+# Complex legacy work gets automatic coordination
+/sc:improve legacy-monolith/
+# → Auto-flags: --task-manage --serena --morph --think-hard --backup
+
+# Manual control for specific modernization strategy  
+/sc:improve legacy/ --ultrathink --task-manage --serena --morph --safe-mode
+# → Maximum analysis + coordination + transformation + safety
+```
+
+### Flag Precedence & Conflict Resolution
+
+**Priority Hierarchy:**
+1. **Safety First**: `--safe-mode` > `--validate` > optimization flags
+2. **Explicit Override**: User flags > auto-detection  
+3. **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think`
+4. **MCP Control**: `--no-mcp` overrides all individual MCP flags
+5. **Scope Precedence**: `system` > `project` > `module` > `file`
+
+**Conflict Resolution Examples:**
+```bash
+# Safety overrides efficiency
+/sc:implement "critical-feature" --uc --safe-mode
+# → Result: Safe mode wins, auto-enables backup and validation
+
+# Explicit scope overrides auto-detection
+/sc:analyze large-project/ --scope file target.js
+# → Result: Only analyzes target.js despite project size
+
+# No-MCP overrides individual server flags
+/sc:implement "feature" --magic --c7 --no-mcp  
+# → Result: No MCP servers used, native execution only
+```
+
+### Dynamic Flag Adaptation
+
+**Resource-Responsive Flagging:**
+```bash
+# System automatically adapts based on available resources
+/sc:analyze enterprise-codebase/
+# → High resources: --all-mcp --parallel --think-hard
+# → Medium resources: --c7 --seq --serena --think  
+# → Low resources: --no-mcp --uc --scope module
+```
+
+**Complexity-Driven Selection:**
+```bash
+# Flags scale with detected complexity
+/sc:implement "simple helper function"
+# → Auto-flags: minimal, fast execution
+
+/sc:implement "microservices authentication"  
+# → Auto-flags: --ultrathink --all-mcp --task-manage --validate --orchestrate
+```
+
+### Expert Flag Patterns
+
+**Security-First Development:**
+```bash
+# Progressive security validation
+/sc:implement "auth-system" --focus security --validate --tests-required
+/sc:review "payment-code" --focus security --think-hard --backup
+/sc:analyze "user-data" --focus security --all-mcp --safe-mode
+```
+
+**Performance Optimization Workflow:**
+```bash
+# Systematic performance improvement
+/sc:analyze --focus performance --think-hard --seq --play
+/sc:improve --focus performance --morph --parallel --validate  
+/sc:test --focus performance --play --format json --export metrics.json
+```
+
+**Learning & Discovery Patterns:**
+```bash
+# Understanding complex systems
+/sc:load new-codebase/ --introspect --brainstorm --serena
+/sc:analyze architecture/ --introspect --think-hard --c7 --all-mcp
+/sc:explain concepts/ --introspect --c7 --focus accessibility
+```
+
+## Flag Troubleshooting 🔧
+
+### Common Issues & Solutions
+
+**Flag Not Recognized:**
+```bash
+# Problem: Unknown flag error
+/sc:analyze code/ --unknown-flag
+
+# Solution: Check flag spelling and availability
+SuperClaude --help flags
+/sc:help --flags
+```
+
+**Conflicting Flags:**
+```bash
+# Problem: Contradictory flags
+/sc:implement "feature" --all-mcp --no-mcp
+
+# Solution: Use flag priority rules
+# --no-mcp overrides --all-mcp (explicit override wins)
+# Use: /sc:implement "feature" --no-mcp
+```
+
+**Resource Issues:**
+```bash
+# Problem: System overload with --all-mcp --ultrathink
+/sc:analyze large-project/ --all-mcp --ultrathink
+
+# Solution: Reduce resource usage
+/sc:analyze large-project/ --c7 --seq --think --concurrency 2
+# Or let auto-detection handle it: /sc:analyze large-project/
+```
+
+**MCP Server Connection Problems:**
+```bash
+# Problem: MCP flags not working
+/sc:implement "dashboard" --magic  # Magic server not responding
+
+# Solutions:
+# 1. Check MCP installation
+SuperClaude install --list-components | grep mcp
+
+# 2. Restart Claude Code session (MCP connections refresh)
+# 3. Use fallback approach
+/sc:implement "dashboard" --no-mcp  # Native execution
+
+# 4. Reinstall MCP servers
+SuperClaude install --components mcp --force
+```
+
+**Performance Problems:**
+```bash
+# Problem: Slow execution with complex flags
+/sc:analyze codebase/ --ultrathink --all-mcp --parallel
+
+# Solutions:
+# 1. Reduce complexity
+/sc:analyze codebase/ --think --c7 --seq
+
+# 2. Use scope limiting
+/sc:analyze codebase/ --scope module --focus quality
+
+# 3. Enable efficiency mode
+/sc:analyze codebase/ --uc --concurrency 1
+```
+
+### Flag Debugging
+
+**Check Auto-Activated Flags:**
+```bash
+# Add --verbose to see which flags were auto-activated
+/sc:analyze project/ --verbose
+# → Output shows: "Auto-activated: --think-hard, --serena, --orchestrate"
+```
+
+**Test Flag Combinations:**
+```bash
+# Use --dry-run to test flag effects without execution
+/sc:improve code/ --task-manage --morph --dry-run
+# → Shows planned execution without making changes
+```
+
+**Validate Flag Usage:**
+```bash
+# Check flag compatibility
+SuperClaude validate-flags --think-hard --no-mcp --magic
+# → Reports conflicts and suggests corrections
+```
+
+### Best Practices for Flag Usage
+
+**Start Simple:**
+1. **Trust Auto-Detection**: Let SuperClaude choose flags automatically
+2. **Add Specific Flags**: Override only when you need specific behavior
+3. **Use Common Patterns**: Start with proven flag combinations
+4. **Monitor Performance**: Watch for resource usage and adjust accordingly
+
+**Progressive Enhancement:**
+```bash
+# Week 1: Use commands without flags
+/sc:analyze src/
+/sc:implement "feature"
+
+# Week 2: Add specific focus
+/sc:analyze src/ --focus security
+/sc:implement "feature" --magic
+
+# Week 3: Combine for workflows  
+/sc:analyze src/ --focus security --think-hard
+/sc:implement "feature" --magic --c7 --validate
+
+# Month 2+: Advanced patterns
+/sc:improve legacy/ --task-manage --serena --morph --safe-mode
+```
+
+**Flag Selection Strategy:**
+1. **Purpose-First**: What do you want to achieve?
+2. **Context-Aware**: Consider project type and complexity
+3. **Resource-Conscious**: Monitor system load and adjust
+4. **Safety-Minded**: Use validation flags for important changes
+5. **Learning-Oriented**: Add `--introspect` when exploring
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience auto-flagging naturally
+- [Commands Reference](commands.md) - Commands automatically select optimal flags
+- [Installation Guide](../Getting-Started/installation.md) - Flag system setup
+
+**🌿 Intermediate (Week 2-3)**
+- [Behavioral Modes](modes.md) - How flags activate behavioral modes
+- [Agents Guide](agents.md) - Flag interaction with specialized agents  
+- [MCP Servers](mcp-servers.md) - MCP server activation flags
+
+**🌲 Advanced (Month 2+)**
+- [Session Management](session-management.md) - Long-term flag patterns
+- [Best Practices](../Reference/best-practices.md) - Flag optimization strategies
+- [Examples Cookbook](../Reference/examples-cookbook.md) - Real-world flag combinations
+
+**🔧 Expert**
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Flag system implementation
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Extending flag capabilities
+
+**Flag-Specific Learning Paths:**
+
+**🎯 Focus Flags Mastery:**
+- **Security**: `--focus security` → Security engineer activation
+- **Performance**: `--focus performance` → Performance optimization patterns
+- **Quality**: `--focus quality` → Code review and improvement workflows
+
+**🧠 Analysis Depth Progression:**
+- **Basic**: No flags → automatic detection
+- **Structured**: `--think` → systematic analysis
+- **Deep**: `--think-hard` → comprehensive investigation  
+- **Maximum**: `--ultrathink` → complete analytical capability
+
+**🛠️ Tool Integration Journey:**
+- **Single Tools**: `--c7`, `--magic` → specific capabilities
+- **Combinations**: `--c7 --seq` → coordinated workflows
+- **Full Suite**: `--all-mcp` → maximum capability
+- **Optimization**: `--orchestrate` → intelligent coordination
+
+**💡 Pro Tips:**
+- **Start Without Flags**: Experience automatic optimization first
+- **Add One at a Time**: Learn flag effects incrementally  
+- **Use `--introspect`**: Understand decision-making process
+- **Monitor Resources**: Watch system load and adjust accordingly
+- **Save Patterns**: Document successful flag combinations for reuse

User-Guide/mcp-servers.md

@@ -0,0 +1,826 @@
+# SuperClaude MCP Servers Guide 🔌
+
+## 🎯 The Simple Truth About MCP Servers
+
+MCP (Model Context Protocol) servers are specialized tools that extend Claude Code's capabilities beyond native functionality. SuperClaude integrates 6 carefully selected MCP servers that automatically activate based on your tasks, providing enhanced documentation access, advanced reasoning, UI generation, browser automation, code transformation, and project memory.
+
+**Seamless Integration**: Type `/sc:implement "React dashboard"` → Magic MCP activates for UI generation. Type `/sc:analyze --think-hard` → Sequential MCP enables structured reasoning. The system intelligently selects the right tools for your context.
+
+## Overview
+
+**What MCP Servers Do:**
+- **Context7**: Official library documentation and framework patterns
+- **Sequential**: Multi-step reasoning and hypothesis testing
+- **Magic**: Modern UI component generation from 21st.dev patterns
+- **Playwright**: Real browser automation and E2E testing
+- **Morphllm**: Efficient pattern-based code transformations
+- **Serena**: Semantic code understanding with project memory
+
+**How They Enhance SuperClaude:**
+- **Automatic Activation**: Intelligent context-based server selection
+- **Parallel Coordination**: Multiple servers working together on complex tasks
+- **Quality Enhancement**: Specialized tools for specific domains
+- **Efficiency Gains**: 30-50% improvement in complex workflows
+- **Session Persistence**: Maintain context across development sessions
+
+## Available MCP Servers
+
+### Context7 Server 📚
+
+**Purpose**: Official library documentation and framework pattern access
+
+**Capabilities:**
+- Curated documentation lookup for popular libraries
+- Version-specific API references and examples
+- Framework best practices and implementation patterns
+- Up-to-date code examples from official sources
+
+**Auto-Activation Triggers:**
+- Library imports: `import`, `require`, `from`, `use`
+- Framework keywords: React, Vue, Angular, Next.js, Express
+- Documentation requests: "official docs", "API reference"
+- Pattern queries: "best practices", "recommended approach"
+
+**Usage Examples:**
+```bash
+# Automatic activation
+/sc:implement "React useEffect for data fetching"
+# → Context7 provides official React hooks documentation
+
+# Manual activation
+/sc:analyze auth-system/ --c7
+# → Access authentication pattern libraries
+```
+
+**Best For:**
+- Following official framework patterns
+- Ensuring API compliance and best practices
+- Learning new libraries with authoritative sources
+- Version-specific implementation requirements
+
+---
+
+### Sequential Server 🧠
+
+**Purpose**: Structured multi-step reasoning and systematic analysis
+
+**Capabilities:**
+- Hypothesis generation and testing workflows
+- Complex problem decomposition
+- Evidence-based reasoning chains
+- Systematic debugging methodologies
+
+**Auto-Activation Triggers:**
+- Complex debugging scenarios with multiple layers
+- Architectural analysis and system design
+- `--think`, `--think-hard`, `--ultrathink` flags
+- Multi-component failure investigation
+
+**Usage Examples:**
+```bash
+# Automatic activation
+/sc:troubleshoot "API performance degrading under load"
+# → Sequential enables systematic root cause analysis
+
+# Manual activation  
+/sc:analyze --think-hard microservices-architecture/
+# → Deep architectural analysis with structured reasoning
+```
+
+**Best For:**
+- Root cause analysis of complex issues
+- System architecture design and evaluation
+- Performance bottleneck identification
+- Security vulnerability assessment
+
+---
+
+### Magic Server ✨
+
+**Purpose**: Modern UI component generation from 21st.dev design patterns
+
+**Capabilities:**
+- Production-ready React, Vue, Angular components
+- Accessibility-compliant UI elements
+- Design system integration
+- Responsive and interactive components
+
+**Auto-Activation Triggers:**
+- UI component requests: button, form, modal, table
+- `/ui` or `/21` commands
+- Frontend development keywords: responsive, accessible, component
+- Design system implementation needs
+
+**Usage Examples:**
+```bash
+# Automatic activation
+/sc:implement "responsive dashboard with data visualization" 
+# → Magic generates modern UI components with accessibility
+
+# Manual activation
+/sc:design "e-commerce checkout flow" --magic
+# → UI-focused design with component generation
+```
+
+**Best For:**
+- Creating production-ready UI components
+- Implementing accessible design systems
+- Rapid frontend prototyping
+- Modern framework component architecture
+
+---
+
+### Playwright Server 🎭
+
+**Purpose**: Real browser automation and comprehensive E2E testing
+
+**Capabilities:**
+- Cross-browser testing automation
+- Visual regression testing
+- Accessibility compliance validation
+- User interaction simulation
+
+**Auto-Activation Triggers:**
+- Browser testing and E2E scenarios
+- Visual testing and screenshot requests
+- Accessibility testing requirements
+- User workflow validation needs
+
+**Usage Examples:**
+```bash
+# Automatic activation
+/sc:test --type e2e "user registration flow"
+# → Playwright automates browser testing
+
+# Manual activation
+/sc:validate "form accessibility compliance" --play
+# → Browser-based accessibility testing
+```
+
+**Best For:**
+- End-to-end user workflow testing
+- Cross-browser compatibility validation
+- Visual regression testing
+- Accessibility compliance verification
+
+---
+
+### Morphllm Server 🔄
+
+**Purpose**: Efficient pattern-based code transformations and bulk editing
+
+**Capabilities:**
+- Multi-file pattern transformations
+- Style guide enforcement across codebases
+- Framework migration assistance
+- Bulk code modernization
+
+**Auto-Activation Triggers:**
+- Multi-file edit operations
+- Framework updates and migrations
+- Code cleanup and standardization
+- Pattern-based refactoring tasks
+
+**Usage Examples:**
+```bash
+# Automatic activation
+/sc:improve legacy-codebase/ --focus maintainability
+# → Morphllm applies consistent patterns across files
+
+# Manual activation
+/sc:cleanup src/ --morph
+# → Pattern-based code organization
+```
+
+**Best For:**
+- Large-scale refactoring projects
+- Code style standardization
+- Framework migration projects
+- Bulk code transformations
+
+---
+
+### Serena Server 🧭
+
+**Purpose**: Semantic code understanding with persistent project memory
+
+**Capabilities:**
+- Symbol-level code navigation and analysis
+- Cross-session project memory
+- Semantic code transformations
+- Large codebase architecture understanding
+
+**Auto-Activation Triggers:**
+- Symbol operations: rename, extract, move functions
+- Project-wide code navigation
+- Session management: `/sc:load`, `/sc:save`
+- Large codebase analysis requirements
+
+**Usage Examples:**
+```bash
+# Automatic activation  
+/sc:load existing-project/
+# → Serena builds project understanding and memory
+
+# Manual activation
+/sc:refactor "extract UserService class" --serena
+# → Semantic-aware code restructuring
+```
+
+**Best For:**
+- Long-term project development
+- Complex codebase navigation
+- Semantic code refactoring
+- Cross-session context preservation
+
+## Installation & Configuration
+
+### Automatic Installation (Recommended)
+
+**During SuperClaude Setup:**
+```bash
+SuperClaude install
+# → Interactive installer offers MCP server selection
+# → Automatically configures selected servers
+# → Creates .claude.json with server configurations
+```
+
+**Installation Options:**
+- **All Servers**: Complete MCP capability (recommended for full features)
+- **Essential Only**: Context7 + Sequential (minimal but powerful)
+- **Custom Selection**: Choose specific servers for your workflow
+- **Skip MCP**: Native-only installation for resource constraints
+
+### Manual Configuration
+
+**Server-Specific Installation:**
+```bash
+# Install specific MCP components
+SuperClaude install --components mcp
+
+# Individual server configuration
+SuperClaude install --components mcp_context7 mcp_sequential
+
+# Force reinstall with updated configurations
+SuperClaude install --components mcp --force
+```
+
+**Configuration File (`.claude.json`):**
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "node",
+      "args": ["/path/to/context7-server"],
+      "env": {"NODE_ENV": "production"}
+    },
+    "sequential": {
+      "command": "node", 
+      "args": ["/path/to/sequential-server"]
+    }
+  }
+}
+```
+
+### Prerequisites by Server
+
+**Node.js Required (Most Servers):**
+- Context7, Magic, Sequential, Playwright require Node.js 16+
+- Install: `brew install node` (macOS) or visit https://nodejs.org
+
+**Python Required:**
+- Morphllm, Serena work with Python environment
+- Already satisfied by SuperClaude installation
+
+**System Resources:**
+- **Minimal**: 2GB RAM for basic MCP functionality
+- **Recommended**: 4GB RAM for full MCP suite
+- **Storage**: 200MB additional for MCP server installations
+
+## Usage Patterns
+
+### Automatic Server Selection
+
+**Context-Based Activation:**
+SuperClaude analyzes your request and automatically selects optimal MCP servers:
+
+```bash
+# Frontend development → Magic + Context7
+/sc:implement "responsive navigation component"
+
+# Performance investigation → Sequential + Playwright  
+/sc:troubleshoot "page load time >3 seconds"
+
+# Large refactoring → Serena + Morphllm + Sequential
+/sc:improve legacy-authentication-system/
+
+# Documentation lookup → Context7
+/sc:explain "React useCallback best practices"
+
+# Browser testing → Playwright + Sequential
+/sc:test --type e2e user-checkout-flow/
+```
+
+**Intelligence Behind Selection:**
+- **Keywords**: "component", "UI" → Magic activation
+- **File types**: `.jsx`, `.vue` → Magic + Context7
+- **Complexity**: Multi-file operations → Serena + Morphllm
+- **Analysis depth**: `--think-hard` → Sequential + Context7
+- **Testing scope**: E2E workflows → Playwright + Sequential
+
+### Manual Server Control
+
+**Force Specific Servers:**
+```bash
+# Enable specific servers
+/sc:analyze codebase/ --c7 --seq --serena
+
+# Disable all MCP servers
+/sc:implement "simple function" --no-mcp
+
+# Enable all servers for maximum capability
+/sc:design "complex system architecture" --all-mcp
+
+# Lightweight execution
+/sc:explain "function purpose" --no-mcp
+```
+
+**Server Combination Strategies:**
+
+**Documentation + Analysis:**
+```bash
+/sc:analyze security-patterns/ --c7 --seq
+# → Context7 provides security patterns + Sequential analyzes implementation
+```
+
+**UI Development:**
+```bash
+/sc:implement "dashboard interface" --magic --c7 --play
+# → Magic generates components + Context7 patterns + Playwright testing
+```
+
+**Code Transformation:**
+```bash
+/sc:improve legacy-code/ --serena --morph --seq
+# → Serena analyzes structure + Morphllm transforms + Sequential validates
+```
+
+### Multi-Server Coordination
+
+**Complex Workflow Example:**
+```bash
+/sc:implement "e-commerce checkout system"
+```
+
+**Automatic Coordination:**
+1. **Sequential**: Breaks down checkout workflow systematically
+2. **Context7**: Provides payment integration patterns
+3. **Magic**: Generates checkout UI components
+4. **Serena**: Manages code organization and dependencies
+5. **Playwright**: Creates E2E testing for checkout flow
+
+**Efficiency Gains:**
+- **30-50% faster development** through specialized tools
+- **Higher quality output** through domain expertise
+- **Reduced context switching** with intelligent automation
+- **Comprehensive coverage** across all development aspects
+
+## Advanced Features
+
+### Multi-Server Orchestration
+
+**Intelligent Workflow Coordination:**
+SuperClaude orchestrates multiple MCP servers for complex tasks:
+
+**Full-Stack Development Workflow:**
+```bash
+/sc:implement "real-time chat application"
+```
+1. **Sequential**: Analyzes requirements and architecture
+2. **Context7**: Provides WebSocket and React patterns  
+3. **Magic**: Generates chat UI components
+4. **Serena**: Manages project structure and dependencies
+5. **Playwright**: Creates E2E tests for messaging flow
+6. **Morphllm**: Applies consistent code patterns
+
+**Performance Optimization Workflow:**
+```bash
+/sc:analyze --focus performance --ultrathink
+```
+1. **Sequential**: Systematic performance analysis methodology
+2. **Serena**: Code structure and bottleneck identification
+3. **Context7**: Framework-specific optimization patterns
+4. **Playwright**: Real browser performance testing
+5. **Morphllm**: Code optimization pattern application
+
+### Resource Management
+
+**Performance Optimization:**
+
+**Smart Resource Allocation:**
+- **Green Zone** (0-75% usage): All servers available
+- **Yellow Zone** (75-85%): Priority servers only
+- **Red Zone** (85%+): Essential servers, compressed output
+
+**Server Priority Matrix:**
+| Priority | Servers | Use Case |
+|----------|---------|----------|
+| **Essential** | Context7, Sequential | Core functionality |
+| **High** | Magic, Serena | Development workflows |
+| **Standard** | Playwright, Morphllm | Testing and optimization |
+
+**Concurrency Control:**
+```bash
+# Limit concurrent server operations
+/sc:implement "complex feature" --concurrency 2
+
+# Maximum performance mode
+/sc:analyze large-codebase/ --all-mcp --concurrency 6
+
+# Resource-constrained mode  
+/sc:troubleshoot issue/ --c7 --seq --concurrency 1
+```
+
+### Advanced Configuration
+
+**Custom Server Configurations:**
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "node",
+      "args": ["/custom/context7-server"],
+      "env": {
+        "CONTEXT7_CACHE_SIZE": "1000",
+        "CONTEXT7_TIMEOUT": "30000"
+      }
+    },
+    "sequential": {
+      "command": "node",
+      "args": ["/custom/sequential-server"],
+      "env": {
+        "MAX_THINKING_DEPTH": "10",
+        "REASONING_TIMEOUT": "60000"
+      }
+    }
+  }
+}
+```
+
+**Performance Tuning:**
+- **Context7**: Cache size, request timeout, documentation sources
+- **Sequential**: Thinking depth, reasoning timeout, branch limits
+- **Magic**: Component complexity, accessibility level, framework targets
+- **Playwright**: Browser pool size, timeout values, screenshot quality
+- **Morphllm**: Pattern matching precision, transformation scope
+- **Serena**: Memory retention, project indexing depth, symbol resolution
+
+### Integration Patterns
+
+**Mode Integration:**
+- **Brainstorming Mode**: Sequential for structured discovery
+- **Task Management Mode**: Serena for session persistence
+- **Orchestration Mode**: All servers for optimal tool selection
+- **Token Efficiency Mode**: Selective activation for resource optimization
+
+**Command Integration:**
+- **Analysis Commands**: Sequential + Serena for deep understanding
+- **Implementation Commands**: Magic + Context7 for development
+- **Testing Commands**: Playwright + Sequential for comprehensive validation
+- **Documentation Commands**: Context7 + Magic for pattern-rich docs
+
+## Troubleshooting
+
+### Common Issues & Solutions
+
+**MCP Server Not Starting:**
+```bash
+# Check server configuration
+ls ~/.claude/.claude.json
+
+# Verify server installation
+SuperClaude install --list-components
+
+# Reinstall MCP configuration
+SuperClaude install --components mcp --force
+
+# Test specific server
+SuperClaude test-mcp context7
+```
+
+**Node.js Dependency Issues:**
+```bash
+# Verify Node.js version (16+ required)
+node --version
+
+# Install missing dependencies
+npm install -g @anthropic/context7-server
+npm install -g @anthropic/sequential-server
+
+# Clear Node.js cache
+npm cache clean --force
+```
+
+**Performance Issues:**
+```bash
+# Reduce server load
+/sc:command --concurrency 1
+
+# Use selective servers
+/sc:command --c7 --seq  # Instead of --all-mcp
+
+# Check system resources
+top | grep node
+ps aux | grep mcp
+```
+
+**Server Connection Timeouts:**
+```bash
+# Increase timeout in .claude.json
+{
+  "mcpServers": {
+    "context7": {
+      "timeout": 60000  // Increase from default 30000
+    }
+  }
+}
+
+# Restart Claude Code session
+# MCP connections refresh on restart
+```
+
+### Diagnostics
+
+**MCP Server Status Check:**
+```bash
+# Check all server health
+SuperClaude status --mcp
+
+# Test individual servers
+SuperClaude test-mcp --server context7
+SuperClaude test-mcp --server sequential
+
+# Detailed diagnostics
+SuperClaude diagnose --verbose
+```
+
+**Log Analysis:**
+```bash
+# View MCP server logs
+tail -f ~/.claude/logs/mcp-context7.log
+tail -f ~/.claude/logs/mcp-sequential.log
+
+# SuperClaude operation logs  
+tail -f ~/.claude/logs/superclaude.log
+
+# Claude Code MCP logs
+tail -f ~/.claude/logs/claude-mcp.log
+```
+
+**Manual Testing:**
+```bash
+# Test Context7 documentation lookup
+echo "Test React hooks documentation" | claude --mcp context7
+
+# Test Sequential reasoning
+echo "Analyze this complex problem" | claude --mcp sequential
+
+# Test server combination
+echo "Complex analysis task" | claude --mcp context7,sequential
+```
+
+### Resolution Steps
+
+**Step 1: Basic Verification**
+1. Check SuperClaude installation: `SuperClaude --version`
+2. Verify MCP component: `SuperClaude install --list-components`
+3. Check Node.js: `node --version` (should be 16+)
+4. Restart Claude Code session
+
+**Step 2: Configuration Check**
+1. Verify `.claude.json` exists: `ls ~/.claude/.claude.json`
+2. Check server paths and permissions
+3. Test configuration syntax: `SuperClaude validate-config`
+
+**Step 3: Server Specific**
+1. **Context7**: Check documentation server connection
+2. **Sequential**: Verify reasoning engine startup
+3. **Magic**: Test UI component generation endpoint
+4. **Playwright**: Check browser automation setup
+5. **Morphllm**: Verify code transformation pipeline
+6. **Serena**: Test project memory and indexing
+
+**Step 4: Full Reset (Last Resort)**
+```bash
+# Backup existing configuration
+cp ~/.claude/.claude.json ~/.claude/.claude.json.backup
+
+# Remove and reinstall MCP
+SuperClaude uninstall --components mcp
+SuperClaude install --components mcp
+
+# Restore custom settings if needed
+```
+
+## Developer Integration
+
+### MCP Server Development
+
+**Creating Custom MCP Servers:**
+
+**Server Structure:**
+```javascript
+// custom-mcp-server.js
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+const server = new Server(
+  {
+    name: "custom-server",
+    version: "1.0.0"
+  },
+  {
+    capabilities: {
+      resources: {},
+      tools: {},
+      prompts: {}
+    }
+  }
+);
+
+// Tool implementation
+server.setRequestHandler(
+  'tools/call',
+  async (request) => {
+    // Custom tool logic
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+```
+
+**SuperClaude Integration:**
+```python
+# setup/components/custom_mcp.py
+from setup.components.base import BaseComponent
+
+class CustomMCPComponent(BaseComponent):
+    def get_metadata(self):
+        return {
+            "name": "custom_mcp",
+            "description": "Custom MCP server integration",
+            "dependencies": ["core"]
+        }
+    
+    def install(self, install_dir):
+        # Install custom server configuration
+        self._install_mcp_config(install_dir)
+```
+
+### Communication Protocols
+
+**MCP Protocol Flow:**
+1. **Initialization**: Claude Code connects to MCP server via JSON-RPC
+2. **Capability Exchange**: Server announces available tools and resources
+3. **Request/Response**: Claude sends requests, server processes and responds
+4. **Session Management**: Maintain context across multiple interactions
+
+**Message Structure:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "request-id",
+  "method": "tools/call",
+  "params": {
+    "name": "analyze-code",
+    "arguments": {
+      "code": "function example() { return 'hello'; }",
+      "language": "javascript"
+    }
+  }
+}
+```
+
+**SuperClaude MCP Interface:**
+```python
+class MCPCoordinator:
+    def select_servers(self, task_context):
+        """Intelligent server selection based on task analysis"""
+        servers = []
+        
+        if self._needs_documentation(task_context):
+            servers.append("context7")
+        
+        if self._needs_reasoning(task_context):
+            servers.append("sequential")
+            
+        if self._needs_ui_generation(task_context):
+            servers.append("magic")
+            
+        return servers
+    
+    def coordinate_request(self, servers, request):
+        """Orchestrate multi-server workflows"""
+        results = []
+        for server in servers:
+            result = await self._send_request(server, request)
+            results.append(result)
+        
+        return self._synthesize_results(results)
+```
+
+### Integration APIs
+
+**Configuration API:**
+```python
+# Register custom MCP server
+from setup.services.config_service import ConfigService
+
+config_service = ConfigService()
+config_service.add_mcp_server({
+    "name": "custom-server",
+    "command": "node",
+    "args": ["/path/to/custom-server.js"],
+    "env": {"CUSTOM_CONFIG": "value"}
+})
+```
+
+**Tool Registration:**
+```python
+# Register server capabilities with SuperClaude
+from setup.core.mcp_registry import MCPRegistry
+
+registry = MCPRegistry()
+registry.register_server("custom-server", {
+    "capabilities": ["code-analysis", "documentation"],
+    "triggers": ["custom", "analyze", "special-keyword"],
+    "priority": "standard"
+})
+```
+
+**Integration Testing:**
+```python
+# Test custom MCP server integration
+from setup.testing.mcp_test import MCPTestSuite
+
+test_suite = MCPTestSuite()
+test_suite.test_server_connection("custom-server")
+test_suite.test_tool_functionality("custom-server", "analyze-code")
+test_suite.test_integration_workflow(["custom-server", "sequential"])
+```
+
+---
+
+## MCP Server Quick Reference 📋
+
+| Server | Purpose | Auto-Triggers | Manual Flags | Best For |
+|--------|---------|---------------|--------------|----------|
+| **Context7** | Documentation | Library imports, API questions | `--c7`, `--context7` | Official patterns, framework docs |
+| **Sequential** | Reasoning | Complex debugging, analysis | `--seq`, `--sequential` | Systematic thinking, root cause |
+| **Magic** | UI Generation | Component requests, frontend | `--magic` | Modern UI, accessibility |
+| **Playwright** | Browser Testing | E2E testing, visual validation | `--play`, `--playwright` | User workflows, cross-browser |
+| **Morphllm** | Code Transform | Multi-file edits, refactoring | `--morph`, `--morphllm` | Pattern application, bulk changes |
+| **Serena** | Project Memory | Symbol operations, large codebases | `--serena` | Session persistence, navigation |
+
+**Server Combinations:**
+- **Full-Stack Development**: Magic + Context7 + Serena
+- **Quality Analysis**: Sequential + Playwright + Serena  
+- **Large Refactoring**: Serena + Morphllm + Sequential
+- **Learning/Documentation**: Context7 + Sequential + Magic
+
+**Performance Control:**
+- `--all-mcp`: Enable all servers (max capability)
+- `--no-mcp`: Disable all servers (lightweight)
+- `--concurrency N`: Control parallel operations
+- Resource awareness: Auto-scaling based on system load
+
+---
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience MCP servers naturally
+- [Installation Guide](../Getting-Started/installation.md) - MCP server setup
+- [Commands Reference](commands.md) - Commands that activate MCP servers
+
+**🌿 Intermediate (Week 2-3)**
+- [Behavioral Modes](modes.md) - How modes coordinate MCP servers
+- [Agents Guide](agents.md) - Agent-MCP server integration
+- [Examples Cookbook](../Reference/examples-cookbook.md) - MCP workflow patterns
+
+**🌲 Advanced (Month 2+)**
+- [Session Management](session-management.md) - Serena MCP workflows
+- [Best Practices](../Reference/best-practices.md) - MCP optimization strategies
+- [Flags Guide](flags.md) - Advanced MCP control
+
+**🔧 Expert**
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - MCP integration details
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Custom MCP development
+- [Testing & Debugging](../Developer-Guide/testing-debugging.md) - MCP troubleshooting
+
+**MCP-Specific Resources:**
+- **Official MCP Documentation**: https://modelcontextprotocol.io/
+- **Context7 Server**: Enhanced documentation lookup capabilities
+- **Sequential Thinking**: Advanced reasoning and analysis
+- **Magic UI**: Modern component generation from 21st.dev
+- **Community MCP Servers**: https://github.com/modelcontextprotocol/servers

User-Guide/modes.md

@@ -0,0 +1,696 @@
+# SuperClaude Behavioral Modes Guide 🧠
+
+## 💡 The Simple Truth About Modes
+
+SuperClaude employs 6 behavioral modes that automatically adapt Claude Code's communication style, tool selection, and workflow approach based on task context and complexity. Modes work seamlessly in the background - you don't need to think about them.
+
+**Automatic Intelligence**: Type `/sc:brainstorm "mobile app"` → Brainstorming mode activates with Socratic questions. Type `/sc:analyze src/` → Introspection mode provides transparent reasoning. Type complex multi-file operations → Task Management coordinates execution phases.
+
+**Behind the Scenes**: Modes enhance your experience by optimizing communication patterns, resource usage, and workflow orchestration based on what you're trying to accomplish.
+
+---
+
+## 🚀 Just Try These (See Modes in Action)
+
+**Automatic Mode Examples:**
+```bash
+# Brainstorming mode activates automatically
+/sc:brainstorm "fitness tracking app"
+# → Socratic questions about users, features, goals
+
+# Introspection mode shows reasoning
+/sc:analyze --focus security 
+# → Transparent thinking: "🤔 Why security first? 🎯 Risk assessment shows..."
+
+# Task Management coordinates complex work
+/sc:implement "user authentication with email verification"
+# → Phases: analysis → design → implementation → testing
+
+# Orchestration optimizes tool selection  
+/sc:improve src/ --focus performance
+# → Magic + Morphllm + Sequential coordination
+
+# Token Efficiency compresses output
+"--uc implement auth API"
+# → "auth.js:45 → 🔧 JWT middleware ⇒ validated_user"
+```
+
+**Mode Detection Logic:**
+- **Keywords**: "brainstorm", "maybe" → Brainstorming
+- **Complexity**: >3 files → Task Management  
+- **Performance**: Resource pressure → Token Efficiency
+- **Multi-tool**: Complex analysis → Orchestration
+- **Error recovery**: Problems → Introspection
+
+---
+
+## The Six Behavioral Modes 🌟
+
+### 🧠 Brainstorming Mode - Interactive Discovery
+
+**Purpose**: Collaborative requirements exploration through Socratic dialogue
+
+**Auto-Activation Triggers:**
+- Vague requests: "I want to build...", "Thinking about creating..."
+- Exploration keywords: brainstorm, explore, discuss, figure out, not sure
+- Uncertainty: "maybe", "possibly", "could we"
+- Manual flags: `--brainstorm`, `--bs`
+
+**What Changes:**
+- **Socratic Questions**: Probing questions to uncover hidden requirements
+- **Non-Presumptive**: Avoid assumptions, let you guide discovery
+- **Collaborative**: Partner in exploration rather than directive consultation
+- **Brief Generation**: Synthesize insights into structured requirements
+
+**Example Experience:**
+```
+You: "I want to build a web app"
+Brainstorming: "🤔 Discovery Questions:
+               - What problem does this solve for users?
+               - Who are your target users and workflows?
+               - Expected user volume and performance needs?
+               - Any existing systems to integrate with?"
+```
+
+---
+
+### 🔍 Introspection Mode - Meta-Cognitive Analysis
+
+**Purpose**: Transparent reasoning and self-analysis for learning optimization
+
+**Auto-Activation Triggers:**
+- Self-analysis requests: "analyze my reasoning", "reflect on decision"
+- Error recovery: unexpected results or outcomes
+- Complex problem solving requiring meta-cognition
+- Manual flag: `--introspect`
+
+**What Changes:**
+- **Transparency**: Expose thinking with markers (🤔, 🎯, ⚡, 📊, 💡)
+- **Pattern Detection**: Identify recurring behaviors and optimizations
+- **Self-Examination**: Analyze decision logic and reasoning chains
+- **Learning Focus**: Extract insights for continuous improvement
+
+**Example Experience:**
+```
+Standard: "I'll analyze this code structure"
+Introspective: "🧠 Reasoning: Why structural over functional analysis?
+               🔄 Alternative: Could start with data flow patterns
+               💡 Learning: Structure-first works for OOP, not functional"
+```
+
+---
+
+### 📋 Task Management Mode - Orchestration & Delegation
+
+**Purpose**: Hierarchical organization with persistent memory for complex multi-step operations
+
+**Auto-Activation Triggers:**
+- Operations >3 steps requiring coordination
+- Multiple file/directory scope (>2 directories OR >3 files)
+- Complex dependencies requiring phases
+- Manual flags: `--task-manage`, `--delegate`
+
+**What Changes:**
+- **Memory Integration**: Session persistence and context preservation
+- **Phase Coordination**: Break complex work into manageable phases
+- **Progress Tracking**: TodoWrite + memory updates for state management
+- **Quality Gates**: Systematic validation at each phase
+
+**Task Hierarchy:**
+```
+📋 Plan → 🎯 Phase → 📦 Task → ✓ Todo
+```
+
+**Example Experience:**
+```
+/sc:implement "payment system"
+→ Phase 1: Security analysis
+→ Phase 2: API design  
+→ Phase 3: Implementation
+→ Phase 4: Testing & validation
+→ Session persistence across interruptions
+```
+
+---
+
+### 🎯 Orchestration Mode - Intelligent Tool Selection
+
+**Purpose**: Optimal task routing and resource efficiency through smart tool coordination
+
+**Auto-Activation Triggers:**
+- Multi-tool operations requiring coordination
+- Performance constraints (>75% resource usage)
+- Parallel execution opportunities (>3 files)
+- Complex routing decisions
+
+**What Changes:**
+- **Smart Tool Selection**: Choose optimal tool for each task type
+- **Resource Awareness**: Adapt approach based on system constraints  
+- **Parallel Thinking**: Identify independent operations for concurrency
+- **Efficiency Focus**: Optimize tool usage for speed and effectiveness
+
+**Tool Selection Matrix:**
+- UI components → Magic MCP > Manual coding
+- Deep analysis → Sequential MCP > Native reasoning
+- Pattern edits → Morphllm MCP > Individual edits
+- Documentation → Context7 MCP > Web search
+
+**Example Experience:**
+```
+Complex multi-file refactoring:
+→ Serena: Symbol analysis
+→ Sequential: Strategy planning  
+→ Morphllm: Pattern application
+→ Parallel execution coordination
+```
+
+---
+
+### ⚡ Token Efficiency Mode - Compressed Communication
+
+**Purpose**: Symbol-enhanced communication for 30-50% token reduction while preserving clarity
+
+**Auto-Activation Triggers:**
+- Context usage >75% or resource constraints
+- Large-scale operations requiring efficiency
+- User flags: `--uc`, `--ultracompressed`
+- Complex analysis workflows
+
+**What Changes:**
+- **Symbol Communication**: Visual symbols for logic, status, domains
+- **Abbreviation Systems**: Context-aware compression for technical terms
+- **Structured Output**: Bullet points, tables over verbose paragraphs
+- **Information Density**: Maximum clarity per token
+
+**Symbol Examples:**
+```
+Standard: "The authentication system has a security vulnerability"
+Compressed: "auth.js:45 → 🛡️ sec risk in user val()"
+
+Standard: "Build completed, now testing, then deploying"
+Compressed: "build ✅ » test 🔄 » deploy ⏳"
+```
+
+---
+
+### 🎨 Standard Mode - Balanced Default
+
+**Purpose**: Balanced communication for general-purpose development tasks
+
+**Default Behavior:**
+- Clear, professional communication
+- Moderate detail level
+- Standard tool selection
+- Quality-focused workflows
+
+**When Active:**
+- Simple, straightforward tasks
+- No complexity triggers detected
+- User preference for standard behavior
+- Balanced resource usage scenarios
+
+---
+
+### 🔍 Introspection Mode - Meta-Cognitive Analysis
+
+**Purpose**: Meta-cognitive analysis and reasoning transparency for complex problem solving and decision optimization.
+
+**Auto-Activation Triggers:**
+- Self-analysis requests: "analyze my reasoning", "reflect on decision"
+- Error recovery scenarios and unexpected results
+- Complex problem solving requiring multi-step reasoning
+- Pattern recognition needs and optimization opportunities
+- Manual flag: `--introspect`
+
+**Capabilities:**
+- **Reasoning Transparency**: Expose thinking process with clear markers (🤔, 🎯, ⚡, 📊, 💡)
+- **Decision Analysis**: Evaluate choice logic and alternative approaches
+- **Pattern Detection**: Identify recurring behaviors and optimization opportunities
+- **Learning Optimization**: Extract insights for continuous improvement
+
+**Examples:**
+```bash
+# Decision analysis after unexpected results
+"The API optimization didn't improve performance as expected"
+# 🤔 Decision Analysis: Why did I choose caching over database optimization?
+# 📊 Evidence Review: Database queries actually the bottleneck
+# 💡 Learning: Profile first, then optimize based on data
+
+# Pattern recognition for improvement
+"I keep having authentication issues"
+# 🎯 Pattern Analysis: Similar auth failures in projects X, Y, Z
+# ⚡ Root Cause: Consistent token refresh logic gap
+# 📊 Solution Strategy: Centralized auth state management
+```
+
+---
+
+### 📋 Task Management Mode - Orchestration & Delegation
+
+**Purpose**: Hierarchical task organization with intelligent delegation for complex multi-step operations.
+
+**Auto-Activation Triggers:**
+- Operations with >3 steps requiring coordination
+- Multiple file/directory scope (>2 directories OR >3 files)
+- Complex dependencies requiring phases
+- Manual flags: `--task-manage`, `--delegate`
+
+**Capabilities:**
+- **Phase Management**: Break complex tasks into manageable phases with dependencies
+- **Intelligent Delegation**: Route subtasks to appropriate specialist agents
+- **Progress Tracking**: Monitor completion across multiple parallel operations
+- **Quality Gates**: Validation checkpoints between phases
+
+**Examples:**
+```bash
+# E-commerce platform development (auto-delegates to multiple agents)
+/sc:implement "complete e-commerce platform with payment integration"
+# Phase 1: Architecture → system-architect
+# Phase 2: Backend APIs → backend-architect + security-engineer  
+# Phase 3: Frontend UI → frontend-architect + quality-engineer
+# Phase 4: Payment Integration → security-engineer + backend-architect
+# Phase 5: Testing & Deployment → devops-architect + quality-engineer
+
+# Large codebase refactoring (delegates by file type and complexity)
+/sc:improve legacy-codebase/ --comprehensive
+# Delegation: Python files → python-expert + refactoring-expert
+# Delegation: React components → frontend-architect + refactoring-expert
+# Delegation: API endpoints → backend-architect + security-engineer
+```
+
+---
+
+### 🎯 Orchestration Mode - Intelligent Tool Selection
+
+**Purpose**: Intelligent tool selection and resource optimization for maximum efficiency and parallel execution.
+
+**Auto-Activation Triggers:**
+- Multi-tool operations requiring coordination
+- Performance constraints (>75% resource usage)
+- Parallel execution opportunities (>3 independent operations)
+- Complex routing decisions with multiple valid approaches
+
+**Capabilities:**
+- **Smart Tool Selection**: Choose optimal tools for each task type (MCP servers, native tools)
+- **Resource Awareness**: Adapt approach based on system constraints and availability
+- **Parallel Optimization**: Identify and execute independent operations concurrently
+- **Efficiency Focus**: Maximize speed and effectiveness through intelligent coordination
+
+**Tool Selection Matrix:**
+| Task Type | Optimal Tool | Fallback | Parallel Opportunity |
+|-----------|-------------|----------|---------------------|
+| UI Components | Magic MCP | Native coding | ✅ Multiple components |
+| Code Analysis | Sequential MCP | Native reasoning | ✅ Multiple files |
+| Documentation | Context7 MCP | Web search | ✅ Multiple topics |
+| Multi-file edits | MultiEdit | Sequential edits | ❌ Dependencies exist |
+
+**Resource Management Zones:**
+- **🟢 Green (0-75%)**: Full capabilities, all tools available
+- **🟡 Yellow (75-85%)**: Efficiency mode, reduced verbosity
+- **🔴 Red (85%+)**: Essential operations only, minimal output
+
+---
+
+### ⚡ Token Efficiency Mode - Compressed Communication
+
+**Purpose**: Symbol-enhanced communication achieving 30-50% token reduction while preserving information quality.
+
+**Auto-Activation Triggers:**
+- Context usage >75% or resource constraints
+- Large-scale operations requiring efficiency
+- User requests brevity: `--uc`, `--ultracompressed`
+- Complex analysis workflows needing optimization
+
+**Symbol Systems:**
+
+**Core Logic**: → (leads to), ⇒ (transforms), ← (rollback), ⇄ (bidirectional)
+**Status**: ✅ (completed), ❌ (failed), ⚠️ (warning), 🔄 (in progress)
+**Technical**: ⚡ (performance), 🔍 (analysis), 🔧 (config), 🛡️ (security)
+
+**Abbreviation Systems:**
+- **System**: `cfg` config, `impl` implementation, `arch` architecture, `perf` performance
+- **Process**: `req` requirements, `deps` dependencies, `val` validation, `test` testing
+- **Quality**: `qual` quality, `sec` security, `err` error, `opt` optimization
+
+**Examples (30-50% compression):**
+```
+Standard: "The authentication system has a security vulnerability in the user validation function"
+Compressed: "auth.js:45 → 🛡️ sec risk in user val()"
+
+Standard: "Performance analysis shows the algorithm is slow because of O(n²) complexity"  
+Compressed: "⚡ perf analysis: slow ∵ O(n²) complexity"
+
+Standard: "Build process completed successfully, now running tests, then deploying"
+Compressed: "build ✅ » test 🔄 » deploy ⏳"
+```
+
+---
+
+## How Modes Work Together 🤝
+
+**Mode Coordination Patterns:**
+
+**Discovery → Implementation Workflow:**
+```bash
+# Brainstorming discovers requirements
+/sc:brainstorm "e-commerce platform"
+→ Requirements brief generated
+
+# Task Management coordinates implementation  
+/sc:implement "payment integration"
+→ Phase 1: Architecture (Orchestration mode for tool selection)
+→ Phase 2: Implementation (Token Efficiency if complex)
+→ Phase 3: Testing (Introspection for quality analysis)
+```
+
+**Multi-Mode Complex Scenarios:**
+
+**Large Codebase Refactoring:**
+1. **Brainstorming**: Explore improvement goals and priorities
+2. **Introspection**: Analyze current code patterns and issues
+3. **Task Management**: Coordinate multi-phase refactoring plan
+4. **Orchestration**: Select optimal tools (Morphllm + Sequential + Serena)
+5. **Token Efficiency**: Compress communication during execution
+
+**Performance Optimization:**
+1. **Task Management**: Break into analysis → optimization → validation phases
+2. **Orchestration**: Coordinate Sequential (analysis) + Magic (UI fixes) + Playwright (testing)
+3. **Introspection**: Transparent reasoning about bottleneck identification
+4. **Token Efficiency**: Compress performance metrics and results
+
+**Mode Priority System:**
+- **Safety First**: Introspection overrides efficiency when quality matters
+- **Context Adaptation**: Modes layer based on complexity and scope
+- **Resource Management**: Token Efficiency activates under pressure
+- **User Intent**: Manual flags override automatic detection
+
+---
+
+## Manual Control 🎛️
+
+**Force Specific Modes:**
+
+**Mode Activation Flags:**
+```bash
+# Force brainstorming for requirement exploration
+/sc:implement "user auth" --brainstorm
+
+# Enable introspection for learning/debugging
+/sc:analyze src/ --introspect
+
+# Activate task management for complex coordination
+/sc:improve legacy-code/ --task-manage
+
+# Enable orchestration for optimal tool selection
+/sc:refactor components/ --orchestrate
+
+# Force token efficiency for compressed output
+/sc:analyze large-project/ --uc
+```
+
+**When to Use Manual Control:**
+
+**Override Automatic Detection:**
+- Simple task needs structured approach → `--task-manage`
+- Want transparent reasoning → `--introspect`
+- Need compressed output → `--uc`
+- Force collaborative discovery → `--brainstorm`
+
+**Learning and Development:**
+- Study reasoning patterns → `--introspect`
+- Practice requirement discovery → `--brainstorm`  
+- Understand tool coordination → `--orchestrate`
+- Optimize token usage → `--token-efficient`
+
+**Resource Management:**
+- High memory pressure → `--uc`
+- Complex multi-tool scenarios → `--orchestrate`
+- Large scope coordination → `--task-manage`
+
+**Mode Combination:**
+```bash
+# Multiple modes for complex scenarios
+/sc:implement "microservices architecture" --brainstorm --task-manage --orchestrate
+
+# Analysis with reasoning transparency
+/sc:analyze security-audit/ --introspect --uc
+```
+
+---
+
+## Real-World Scenarios 🌍
+
+**Scenario 1: New Project Startup**
+
+```bash
+# Phase 1: Discovery (Brainstorming Mode)
+/sc:brainstorm "task management mobile app"
+```
+*Experience*: Socratic questions about users, features, platform choice, backend needs
+*Outcome*: Structured requirements brief with technical specifications
+
+```bash
+# Phase 2: Planning (Task Management Mode)  
+/sc:workflow "implement core task features"
+```
+*Experience*: Multi-phase breakdown with dependencies and time estimates
+*Outcome*: Systematic implementation plan with quality gates
+
+```bash
+# Phase 3: Implementation (Orchestration Mode)
+/sc:implement "user authentication with social login"
+```
+*Experience*: Magic (UI) + Context7 (auth patterns) + Security specialist coordination
+*Outcome*: Complete auth system with tests and documentation
+
+---
+
+**Scenario 2: Authentication Debugging**
+
+```bash
+# Step 1: Problem Analysis (Introspection Mode)
+/sc:troubleshoot "users getting 401 errors intermittently"
+```
+*Experience*: 
+```
+🤔 Reasoning: Why intermittent? Session timing vs token expiry
+🔍 Investigation: Check auth middleware, session storage, token validation
+🎯 Hypothesis: Race condition in token refresh
+📊 Evidence: Log patterns show timing correlation
+💡 Solution: Implement token refresh queue
+```
+
+```bash
+# Step 2: Systematic Fix (Task Management Mode)
+/sc:implement "token refresh queue with retry logic"
+```
+*Experience*: Phase coordination across middleware, frontend, and testing
+*Outcome*: Robust authentication flow with comprehensive error handling
+
+---
+
+**Scenario 3: Large Codebase Refactoring**
+
+```bash
+# Phase 1: Assessment (Token Efficiency + Introspection)
+/sc:analyze legacy-codebase/ --focus maintainability --uc
+```
+*Experience*:
+```
+🔍 Analysis:
+  auth.js:142 → 🛡️ sec vuln (hardcoded keys)
+  ui-comp/ → 🎨 inconsistent patterns
+  api/ → ⚡ perf bottlenecks (N+1 queries)
+📊 Debt: 847 lines need refactoring
+💡 Priority: sec → perf → patterns
+```
+
+```bash
+# Phase 2: Planning (Task Management + Orchestration)  
+/sc:improve legacy-codebase/ --task-manage --orchestrate
+```
+*Experience*: Multi-phase plan with Morphllm (patterns) + Sequential (analysis) + Serena (context)
+*Outcome*: Systematic refactoring with progress tracking and rollback safety
+
+```bash
+# Phase 3: Quality Validation (Introspection)
+/sc:reflect "refactoring impact assessment"
+```
+*Experience*: Transparent analysis of improvements, remaining debt, and success metrics
+*Outcome*: Evidence-based completion assessment with next steps
+
+---
+
+**Scenario 4: Performance Optimization**
+
+```bash
+# Discovery (Brainstorming Mode for unclear performance issues)
+/sc:brainstorm "app feels slow but unclear where"
+```
+*Experience*: Questions about user workflows, data volumes, environment differences
+*Outcome*: Focused performance investigation scope
+
+```bash
+# Systematic Analysis (Task Management + Token Efficiency)
+/sc:analyze --focus performance --task-manage --uc
+```
+*Experience*:
+```
+Phase 1: Frontend metrics → ⚡ bundle size 2.4MB
+Phase 2: API latency → 📊 db queries avg 1.2s  
+Phase 3: Infrastructure → 🔧 memory usage 85%
+Priority: db opt → bundle split → memory tuning
+```
+
+```bash
+# Coordinated Fixes (Orchestration Mode)
+/sc:improve --focus performance --orchestrate
+```
+*Experience*: Sequential (analysis) + Morphllm (code patterns) + Context7 (optimization patterns)
+*Outcome*: 60% performance improvement with systematic validation
+
+---
+
+## FAQ 🙋
+
+**Q: How do I know which mode is active?**
+A: Modes work transparently, but you can identify them by communication patterns:
+- 🤔 Questions and discovery → Brainstorming
+- 🧠 🎯 Reasoning markers → Introspection  
+- Phase breakdowns → Task Management
+- Tool coordination mentions → Orchestration
+- Symbol-compressed output → Token Efficiency
+
+**Q: Can I disable modes?**
+A: Modes enhance rather than restrict. For minimal behavior, avoid complexity triggers:
+- Simple, single-task requests
+- Specific file operations
+- Clear, unambiguous instructions
+
+**Q: Do modes affect performance?**
+A: Modes optimize performance:
+- **Token Efficiency**: 30-50% reduction in context usage
+- **Orchestration**: Parallel processing and optimal tool selection
+- **Task Management**: Systematic execution prevents rework
+
+**Q: Can modes conflict with each other?**
+A: Modes are designed to work together:
+- **Hierarchical**: Task Management coordinates other modes
+- **Contextual**: Token Efficiency activates under resource pressure
+- **Complementary**: Introspection provides transparency for any mode
+
+**Q: How do modes relate to agents and commands?**
+A: Integrated coordination:
+- **Commands** trigger appropriate modes automatically
+- **Agents** work within mode communication patterns
+- **MCP servers** are selected by Orchestration mode logic
+
+**Q: What if automatic detection is wrong?**
+A: Manual override available:
+```bash
+/sc:command --brainstorm      # Force discovery approach
+/sc:command --no-introspect   # Suppress reasoning markers
+/sc:command --uc              # Force compression
+```
+
+---
+
+## Technical Reference 🔧
+
+**Mode Activation Triggers:**
+
+| Mode | Automatic Triggers | Manual Flags |
+|------|-------------------|--------------|
+| **Brainstorming** | "brainstorm", "explore", "maybe", "not sure" | `--brainstorm`, `--bs` |
+| **Introspection** | Error recovery, self-analysis requests | `--introspect` |
+| **Task Management** | >3 steps, >2 directories, >3 files | `--task-manage`, `--delegate` |
+| **Orchestration** | Multi-tool ops, >75% resources, >3 files | `--orchestrate` |
+| **Token Efficiency** | >75% context, large ops, resource pressure | `--uc`, `--ultracompressed` |
+| **Standard** | Simple tasks, no complexity triggers | Default |
+
+**Flag Reference:**
+
+**Mode Control Flags:**
+- `--brainstorm` / `--bs`: Force collaborative discovery
+- `--introspect`: Enable reasoning transparency
+- `--task-manage`: Activate hierarchical coordination
+- `--orchestrate`: Optimize tool selection and parallelization
+- `--token-efficient` / `--uc`: Enable symbol compression
+
+**Mode Integration Flags:**
+- `--think`: Enable Sequential MCP (moderate analysis)
+- `--think-hard`: Deep analysis with Sequential + Context7
+- `--ultrathink`: Maximum analysis with all MCP servers
+- `--safe-mode`: Conservative execution with validation
+
+**Mode Interaction with Framework Components:**
+
+**Agent Coordination:**
+- Modes influence agent communication patterns
+- Task Management coordinates multi-agent workflows
+- Orchestration optimizes agent-tool combinations
+- Token Efficiency compresses agent outputs
+
+**Command Integration:**
+- Commands auto-select appropriate modes
+- Mode flags override automatic selection
+- Complex commands activate Task Management
+- Analysis commands trigger Introspection
+
+**MCP Server Selection:**
+- Orchestration mode optimizes MCP coordination
+- Token Efficiency mode minimizes MCP overhead  
+- Task Management preserves MCP context across phases
+- Brainstorming leverages Sequential for structured thinking
+
+**Performance Metrics:**
+
+| Mode | Token Reduction | Processing Speed | Quality Impact |
+|------|----------------|------------------|----------------|
+| **Brainstorming** | 0% | Standard | +Requirements clarity |
+| **Introspection** | -10% (detail) | -15% (analysis) | +Learning, +Debugging |
+| **Task Management** | +20% (structure) | +30% (parallel) | +Completeness |
+| **Orchestration** | +15% (efficiency) | +45% (parallel) | +Tool optimization |
+| **Token Efficiency** | +30-50% | +25% (less context) | Maintained (95%+) |
+| **Standard** | Baseline | Baseline | Baseline |
+
+---
+
+## The Magic of Intelligent Adaptation ✨
+
+SuperClaude's behavioral modes represent a breakthrough in AI framework design: **intelligence that adapts to you, not the other way around**. The system observes your context, analyzes task complexity, and seamlessly adjusts its communication style, tool selection, and workflow approach.
+
+**You Don't Need to Think About Modes** - they work transparently in the background, enhancing your experience without adding complexity. Start a vague project idea and watch Brainstorming mode guide discovery. Tackle complex refactoring and see Task Management coordinate phases. Work under resource pressure and observe Token Efficiency compress communication while preserving clarity.
+
+**The Result**: Claude Code transforms from a capable assistant into an **intelligent partner** that matches your needs at every step of the development journey.
+
+---
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - Experience modes naturally
+- [Commands Reference](commands.md) - Commands automatically activate modes
+- [Installation Guide](../Getting-Started/installation.md) - Set up behavioral modes
+
+**🌿 Intermediate (Week 2-3)**  
+- [Agents Guide](agents.md) - How modes coordinate with specialists
+- [Flags Guide](flags.md) - Manual mode control and optimization
+- [Examples Cookbook](../Reference/examples-cookbook.md) - Mode patterns in practice
+
+**🌲 Advanced (Month 2+)**
+- [MCP Servers](mcp-servers.md) - Mode integration with enhanced capabilities
+- [Session Management](session-management.md) - Task Management mode workflows  
+- [Best Practices](../Reference/best-practices.md) - Mode optimization strategies
+
+**🔧 Expert**
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Mode implementation details
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Extend mode capabilities
+
+**Mode-Specific Guides:**
+- **Brainstorming**: [Requirements Discovery Patterns](../Reference/examples-cookbook.md#requirements)
+- **Task Management**: [Session Management Guide](session-management.md)
+- **Orchestration**: [MCP Servers Guide](mcp-servers.md)
+- **Token Efficiency**: [Performance Optimization](../Reference/best-practices.md#efficiency)

User-Guide/session-management.md

@@ -0,0 +1,827 @@
+# SuperClaude Session Management Guide 🧠
+
+## Introduction
+
+SuperClaude transforms Claude Code from a stateless assistant into a **persistent development partner** through intelligent session management. Sessions preserve project context, accumulated insights, and development progress across interruptions, creating continuity that builds expertise over time.
+
+**Persistent Intelligence**: Load project context with `/sc:load`, work naturally with accumulated understanding, save progress with `/sc:save`, and resume exactly where you left off. SuperClaude remembers your codebase structure, decisions made, patterns discovered, and project goals.
+
+**Cross-Session Learning**: Each session builds on previous understanding, creating a development partner that becomes more effective with your specific project over time.
+
+## Session Fundamentals
+
+**What is a SuperClaude Session?**
+A session is a persistent development context that includes:
+- **Project Understanding**: Codebase structure, architecture patterns, dependencies
+- **Development History**: Decisions made, problems solved, patterns applied
+- **Current State**: Active tasks, progress tracking, next steps
+- **Learned Insights**: Code conventions, team preferences, domain knowledge
+
+**Session Intelligence vs Standard Claude:**
+- **Standard Claude**: Each conversation starts fresh, no project memory
+- **SuperClaude Sessions**: Cumulative understanding that builds over time
+
+**Session Types:**
+
+**Project Sessions**: Long-term development context for specific codebases
+- Persistent across weeks/months of development
+- Accumulates architectural understanding
+- Remembers team conventions and decisions
+
+**Task Sessions**: Focused context for specific features or problems  
+- Short to medium-term (hours to days)
+- Maintains task-specific context and progress
+- Integrates with project sessions for broader context
+
+**Learning Sessions**: Educational context for understanding complex systems
+- Preserves learning progress and insights
+- Builds conceptual understanding over time
+- Connects theoretical knowledge with practical application
+
+**Session Persistence Powered by Serena MCP:**
+- Semantic code understanding with symbol-level navigation
+- Project memory that survives Claude Code restarts
+- Intelligent context loading based on current work
+- Cross-session insight accumulation and pattern recognition
+
+## Session Commands
+
+### /sc:load - Session Initialization
+
+**Purpose**: Load project context and initialize persistent development session
+
+**Usage Patterns:**
+```bash
+# Load existing project context
+/sc:load src/
+
+# Load with specific focus
+/sc:load --focus architecture existing-project/
+
+# Load previous session by name
+/sc:load "payment-integration-session"
+
+# Load with fresh analysis
+/sc:load --refresh large-codebase/
+```
+
+**What Happens During Load:**
+1. **Project Structure Analysis**: Serena MCP scans codebase organization
+2. **Context Restoration**: Previous session memory and insights loaded
+3. **Pattern Recognition**: Code conventions and architecture patterns identified
+4. **Dependency Mapping**: Component relationships and data flow understood
+5. **Session Initialization**: Persistent context established for continued work
+
+**Load Modes:**
+
+**Smart Load (Default):**
+```bash
+/sc:load project-directory/
+```
+- Automatically detects project type and structure
+- Loads relevant previous session context
+- Optimizes analysis based on project size and complexity
+
+**Focused Load:**
+```bash
+/sc:load --focus security payment-system/
+/sc:load --focus performance api-endpoints/
+/sc:load --focus architecture microservices/
+```
+- Specialized analysis for specific concerns
+- Activates domain experts and relevant tools
+- Loads context specific to focus area
+
+**Fresh Load:**
+```bash
+/sc:load --refresh --comprehensive legacy-system/
+```
+- Re-analyzes project from scratch
+- Updates understanding with latest changes
+- Comprehensive re-indexing of codebase
+
+**Example Load Experience:**
+```bash
+/sc:load e-commerce-platform/
+
+→ 🔍 Analyzing project structure...
+→ 📂 Detected: React frontend + Node.js API + PostgreSQL
+→ 🧠 Loading previous session: "checkout-optimization-work"
+→ 📝 Restored context: 847 files analyzed, 23 patterns identified
+→ ✅ Session ready: Continue checkout flow optimization
+→ 💡 Next: Complete payment validation implementation
+```
+
+### /sc:save - Session Persistence
+
+**Purpose**: Preserve session context and development progress for future continuation
+
+**Usage Patterns:**
+```bash
+# Save current session with automatic naming
+/sc:save
+
+# Save with descriptive name
+/sc:save "authentication-module-complete"
+
+# Save checkpoint during long work
+/sc:save --checkpoint "api-endpoints-analysis-done"
+
+# Save with summary
+/sc:save --description "Completed user registration flow, ready for testing"
+```
+
+**What Gets Saved:**
+- **Project Understanding**: Current codebase analysis and insights
+- **Work Progress**: Completed tasks, current focus, next steps
+- **Decision History**: Architectural choices, patterns applied, trade-offs made
+- **Code Context**: Modified files, dependencies, integration points
+- **Learning Insights**: Discovered patterns, conventions, best practices
+
+**Save Types:**
+
+**Milestone Save:**
+```bash
+/sc:save "payment-integration-complete"
+```
+- Major feature completion or phase end
+- Comprehensive context preservation
+- Clear handoff point for future sessions
+
+**Checkpoint Save:**
+```bash
+/sc:save --checkpoint "database-schema-analysis"
+```
+- Periodic progress preservation
+- Intermediate work state capture
+- Recovery point for complex work
+
+**Automatic Save:**
+```bash
+# Triggered automatically during:
+- Long-running tasks (every 30 minutes)
+- Before risky operations
+- Session interruption detection
+- Context limit approaching
+```
+
+**Save Output Example:**
+```bash
+/sc:save "user-dashboard-feature-complete"
+
+→ 💾 Saving session context...
+→ 📊 Progress summary:
+  ✅ 3 components implemented
+  ✅ 12 tests passing
+  ✅ API integration complete
+  📝 Documentation updated
+→ 🧠 Context preserved:
+  - 247 files in working memory
+  - 15 architectural patterns identified
+  - 8 integration points mapped
+→ ✅ Session saved: "user-dashboard-feature-complete"
+→ 🔄 Ready for future continuation
+```
+
+### /sc:reflect - Session Validation
+
+**Purpose**: Analyze session progress, validate task completion, and assess development quality
+
+**Usage Patterns:**
+```bash
+# General session reflection
+/sc:reflect
+
+# Specific task validation
+/sc:reflect "payment-processing-implementation"
+
+# Quality assessment
+/sc:reflect --type quality-review
+
+# Completion verification
+/sc:reflect --type completion-check
+```
+
+**Reflection Types:**
+
+**Progress Analysis:**
+```bash
+/sc:reflect --type progress
+```
+- Current task status and completion percentage
+- Blockers and dependencies identified
+- Next steps and priority recommendations
+- Timeline and effort assessment
+
+**Quality Review:**
+```bash
+/sc:reflect --type quality
+```
+- Code quality assessment and improvements needed
+- Test coverage and validation gaps
+- Security and performance considerations
+- Documentation and maintainability review
+
+**Completion Verification:**
+```bash
+/sc:reflect --type completion
+```
+- Task completion criteria assessment
+- Integration and testing verification
+- Deployment readiness evaluation
+- Handoff preparation and next steps
+
+**Learning Assessment:**
+```bash
+/sc:reflect --type learning
+```
+- Insights gained and patterns discovered
+- Decision rationale and trade-offs made
+- Knowledge gaps and learning opportunities
+- Best practices and conventions established
+
+**Example Reflection Output:**
+```bash
+/sc:reflect --type completion "user-authentication-system"
+
+→ 🎯 Task Completion Analysis:
+  ✅ JWT authentication implemented
+  ✅ Password hashing and validation  
+  ✅ Session management
+  ⚠️  Email verification pending
+  ❌ OAuth integration incomplete
+
+→ 📊 Quality Assessment:
+  ✅ Security best practices followed
+  ✅ 89% test coverage achieved
+  ⚠️  Performance testing needed
+  ✅ Documentation complete
+
+→ 🔄 Next Steps:
+  1. Complete email verification flow
+  2. Implement OAuth providers
+  3. Performance optimization
+  4. Production deployment preparation
+
+→ 💡 Session Status: 75% complete, 2-3 days remaining
+```
+
+## Session Lifecycle Management
+
+**Complete Session Workflow:**
+
+### Phase 1: Session Initialization
+```bash
+# 1. Project Discovery and Loading
+/sc:load new-project/
+→ Project analysis and context establishment
+
+# 2. Goal Setting and Planning  
+/sc:brainstorm "improve user onboarding experience"
+→ Requirements discovery and strategic planning
+
+# 3. Initial Analysis
+/sc:analyze --focus user-experience --think-hard
+→ Comprehensive system understanding
+```
+
+### Phase 2: Active Development
+```bash
+# 4. Implementation Planning
+/sc:workflow "streamlined-onboarding-flow"
+→ Systematic implementation strategy
+
+# 5. Feature Development (Iterative)
+/sc:implement "progressive-user-registration"
+→ Coordinated development with automatic progress tracking
+
+# 6. Regular Checkpoints
+/sc:save --checkpoint "registration-flow-complete"
+→ Periodic progress preservation
+```
+
+### Phase 3: Validation and Quality
+```bash
+# 7. Progress Review
+/sc:reflect --type progress
+→ Status assessment and next steps
+
+# 8. Quality Assurance
+/sc:test --comprehensive user-onboarding/
+→ Testing and validation workflows
+
+# 9. Quality Review
+/sc:reflect --type quality
+→ Code review and improvement identification
+```
+
+### Phase 4: Completion and Handoff
+```bash
+# 10. Completion Verification
+/sc:reflect --type completion
+→ Task completion criteria validation
+
+# 11. Final Documentation
+/sc:document --type user-guide onboarding-system/
+→ Documentation and knowledge transfer
+
+# 12. Session Archive
+/sc:save "onboarding-improvement-complete"
+→ Final context preservation and handoff preparation
+```
+
+**Session State Transitions:**
+
+**Active Session States:**
+- **Discovery**: Requirements exploration and goal setting
+- **Analysis**: System understanding and strategy development  
+- **Implementation**: Active development and feature creation
+- **Validation**: Testing, review, and quality assurance
+- **Completion**: Final verification and handoff preparation
+
+**Session Continuity Patterns:**
+- **Daily Sessions**: Load → Work → Checkpoint → Save
+- **Weekly Sprints**: Load → Sprint planning → Daily work → Sprint review → Save
+- **Feature Cycles**: Load → Analysis → Implementation → Testing → Completion → Save
+
+## Memory and Context
+
+**Serena MCP-Powered Memory System:**
+
+**Project Memory Components:**
+- **Structural Memory**: Codebase organization, file relationships, dependencies
+- **Semantic Memory**: Code meaning, business logic, domain concepts
+- **Historical Memory**: Development decisions, evolution patterns, change history
+- **Contextual Memory**: Working sessions, current focus, progress state
+
+**Memory Operations:**
+
+**Memory Accumulation:**
+```bash
+# As you work, memory automatically builds:
+/sc:analyze user-service/
+→ Records: Service patterns, data flows, API contracts
+
+/sc:implement "user-preferences"  
+→ Records: Implementation patterns, coding conventions, integration points
+
+/sc:troubleshoot "performance-issue"
+→ Records: Problem patterns, solution strategies, optimization techniques
+```
+
+**Memory Recall:**
+```bash
+# Previous insights automatically inform current work:
+/sc:implement "user-notifications"
+→ Recalls: User service patterns, preference storage, communication flows
+→ Applies: Established conventions, tested patterns, integration strategies
+```
+
+**Memory Types:**
+
+**Architectural Memory:**
+```json
+{
+  "patterns": ["MVC", "Repository Pattern", "Dependency Injection"],
+  "conventions": ["camelCase variables", "async/await preferred"],
+  "decisions": ["PostgreSQL for persistence", "JWT for authentication"],
+  "integrations": ["Stripe API", "SendGrid", "Redis cache"]
+}
+```
+
+**Development Memory:**
+```json
+{
+  "workflows": ["TDD approach", "Feature branch strategy"],
+  "quality_gates": ["ESLint rules", "Test coverage >80%"],
+  "preferences": ["Functional components", "Hooks over classes"],
+  "tooling": ["Jest testing", "Prettier formatting"]
+}
+```
+
+**Context Preservation:**
+```json
+{
+  "current_task": "implement-user-dashboard",
+  "progress": "components-complete-api-pending",
+  "next_steps": ["API integration", "state management", "testing"],
+  "blockers": ["API rate limiting", "design system tokens"]
+}
+```
+
+**Memory Intelligence:**
+
+**Smart Context Loading:**
+- Loads relevant memory based on current work
+- Prioritizes recent and frequently accessed patterns
+- Connects related concepts and components
+
+**Pattern Recognition:**
+- Identifies recurring code patterns and conventions
+- Suggests consistent approaches based on project history
+- Detects deviations from established patterns
+
+**Predictive Context:**
+- Anticipates needed information based on current task
+- Pre-loads related components and dependencies
+- Suggests next steps based on similar previous work
+
+## Session Workflows
+
+**Common Session Patterns:**
+
+### Daily Development Session
+```bash
+# Morning: Resume previous work
+/sc:load project/
+→ Context restoration and progress review
+
+# Planning: Review and plan day's work
+/sc:reflect --type progress
+→ Status assessment and priority setting
+
+# Work: Active development with periodic saves
+/sc:implement "current-feature"
+/sc:save --checkpoint "feature-milestone"
+
+# Evening: End-of-day preservation
+/sc:reflect --type completion
+/sc:save "end-of-day-progress"
+```
+
+### Feature Development Cycle
+```bash
+# Discovery Phase
+/sc:load project/
+/sc:brainstorm "new-feature-requirements"
+/sc:save --checkpoint "requirements-complete"
+
+# Planning Phase  
+/sc:workflow "feature-implementation-plan"
+/sc:design "feature-architecture"
+/sc:save --checkpoint "planning-complete"
+
+# Implementation Phase
+/sc:implement "feature-core-functionality"
+/sc:save --checkpoint "core-complete"
+
+/sc:implement "feature-integration"
+/sc:save --checkpoint "integration-complete"
+
+# Validation Phase
+/sc:test --comprehensive feature/
+/sc:reflect --type quality
+/sc:save "feature-complete"
+```
+
+### Bug Investigation Session
+```bash
+# Load with focus on problem area
+/sc:load --focus debugging problematic-module/
+
+# Systematic investigation
+/sc:troubleshoot "specific-bug-description"
+/sc:analyze --focus root-cause affected-components/
+
+# Solution implementation
+/sc:implement "bug-fix-solution"
+/sc:test --focus regression bug-area/
+
+# Validation and documentation
+/sc:reflect --type completion
+/sc:document --type bug-report "issue-resolution"
+/sc:save "bug-fix-complete"
+```
+
+### Learning and Exploration Session
+```bash
+# Focused learning context
+/sc:load --focus architecture new-codebase/
+
+# Systematic exploration
+/sc:analyze --introspect --think-hard codebase-structure/
+/sc:explain "complex-architectural-patterns"
+
+# Knowledge consolidation
+/sc:reflect --type learning
+/sc:document --type architecture-notes findings/
+/sc:save "architecture-understanding-session"
+```
+
+### Code Review Session
+```bash
+# Load changes context
+/sc:load --focus quality pending-changes/
+
+# Comprehensive review
+/sc:analyze --focus quality --think-hard changes/
+/sc:test --focus regression change-areas/
+
+# Quality assessment
+/sc:reflect --type quality
+/sc:document --type review-notes quality-assessment/
+/sc:save "code-review-complete"
+```
+
+**Session Optimization Patterns:**
+
+**Short Sessions (1-2 hours):**
+- Quick load with specific focus
+- Targeted work on single component
+- Checkpoint saves for continuity
+
+**Medium Sessions (Half-day):**
+- Comprehensive load and planning
+- Multi-component development
+- Regular checkpoints and quality reviews
+
+**Long Sessions (Full-day):**
+- Full context loading and analysis
+- Complex feature development cycles
+- Multiple validation and reflection points
+
+## Multi-Session Projects
+
+**Long-Term Project Management:**
+
+### Project Session Architecture
+```bash
+# Master Project Session
+/sc:load enterprise-platform/
+→ Maintains overall project context and architecture understanding
+
+# Feature Branch Sessions  
+/sc:load --branch feature/user-management user-service/
+/sc:load --branch feature/payment-integration payment-service/
+→ Focused context for specific feature development
+
+# Integration Sessions
+/sc:load --integration-focus platform-services/
+→ Cross-service integration and system-level concerns
+```
+
+### Session Hierarchy Management
+
+**Project Level (Months):**
+- Overall architecture and system understanding
+- Cross-cutting concerns and integration patterns
+- Long-term technical decisions and evolution
+
+**Epic Level (Weeks):**
+- Feature set implementation and integration
+- Domain-specific patterns and conventions
+- Epic-level progress and quality tracking
+
+**Story Level (Days):**
+- Individual feature implementation
+- Component-level development and testing
+- Story completion and handoff
+
+**Session Coordination Patterns:**
+
+**Team Coordination:**
+```bash
+# Shared Project Context
+/sc:load --shared team-project/
+→ Common understanding accessible to all team members
+
+# Individual Developer Sessions
+/sc:load --developer alice team-project/user-auth/
+/sc:load --developer bob team-project/payment-system/
+→ Personal development context within shared project
+
+# Integration Sessions
+/sc:load --integration team-project/
+→ Cross-developer integration and system-level work
+```
+
+**Cross-Session Continuity:**
+
+**Session Handoff:**
+```bash
+# End of developer session
+/sc:save --handoff "alice-user-auth-complete" --next-developer bob
+
+# New developer pickup
+/sc:load --handoff "alice-user-auth-complete"
+→ Complete context transfer with work continuation
+```
+
+**Progress Synchronization:**
+```bash
+# Daily standup preparation
+/sc:reflect --type team-progress
+→ Team-level progress summary and coordination
+
+# Sprint planning context
+/sc:load --sprint-context team-project/
+→ Sprint-level understanding and planning context
+```
+
+**Long-Term Memory Evolution:**
+
+**Memory Consolidation:**
+- Weekly: Consolidate daily insights into persistent patterns
+- Monthly: Archive completed features, preserve key learnings  
+- Quarterly: Architectural review and pattern evolution
+
+**Memory Inheritance:**
+- New features inherit patterns from completed work
+- Team members inherit shared conventions and decisions
+- Project evolution builds on accumulated architectural understanding
+
+## Session Troubleshooting
+
+**Common Session Issues:**
+
+### Session Context Lost
+**Problem**: `/sc:load` doesn't restore expected context
+```bash
+# Symptoms
+/sc:load project/
+→ "No previous session found" or minimal context restored
+```
+
+**Solutions:**
+```bash
+# 1. Check available sessions
+/sc:load --list-sessions
+
+# 2. Load by specific session name
+/sc:load "session-name"
+
+# 3. Fresh analysis if needed
+/sc:load --refresh --comprehensive project/
+
+# 4. Check Serena MCP status
+SuperClaude status --mcp serena
+```
+
+### Memory Fragmentation
+**Problem**: Session memory becomes inconsistent or incomplete
+```bash
+# Symptoms
+- Conflicting pattern suggestions
+- Missing context for recent work
+- Inconsistent architectural understanding
+```
+
+**Solutions:**
+```bash
+# 1. Memory consolidation
+/sc:reflect --type memory-health
+/sc:save --consolidate "clean-session-state"
+
+# 2. Selective memory refresh
+/sc:load --refresh-memory specific-area/
+
+# 3. Clean session restart
+/sc:save --archive "old-session"
+/sc:load --fresh project/
+```
+
+### Session Performance Issues
+**Problem**: Slow session loading or excessive memory usage
+```bash
+# Symptoms
+- Long load times (>30 seconds)
+- Memory warnings during operation
+- Reduced response quality
+```
+
+**Solutions:**
+```bash
+# 1. Optimize session scope
+/sc:load --scope module target-area/
+
+# 2. Use focused loading
+/sc:load --focus performance specific-concern/
+
+# 3. Memory cleanup
+/sc:save --cleanup "optimized-session"
+
+# 4. Check system resources
+SuperClaude diagnose --memory
+```
+
+### Integration Conflicts
+**Problem**: Multi-session project coordination issues
+```bash
+# Symptoms
+- Conflicting architectural decisions
+- Integration pattern mismatches
+- Cross-team context confusion
+```
+
+**Solutions:**
+```bash
+# 1. Sync with master session
+/sc:load --sync-master project/
+
+# 2. Resolve conflicts explicitly
+/sc:reflect --type integration-conflicts
+/sc:resolve-conflicts --strategy team-lead-wins
+
+# 3. Re-establish shared context
+/sc:load --shared-refresh team-project/
+```
+
+**Session Recovery Procedures:**
+
+### Emergency Session Recovery
+```bash
+# 1. Check session backups
+/sc:load --list-backups
+
+# 2. Restore from backup
+/sc:load --restore-backup "backup-timestamp"
+
+# 3. Partial recovery if needed
+/sc:load --partial-restore specific-components/
+
+# 4. Rebuild from artifacts
+/sc:load --rebuild-from git-history project/
+```
+
+### Session Health Monitoring
+```bash
+# Regular health checks
+/sc:reflect --type session-health
+→ Memory consistency, context completeness, performance metrics
+
+# Memory optimization
+/sc:save --optimize "clean-session"
+→ Consolidate insights, remove redundant context
+
+# Performance tuning
+/sc:load --performance-mode project/
+→ Optimized loading for resource-constrained environments
+```
+
+**Best Practices for Session Reliability:**
+
+1. **Regular Saves**: Save at natural breakpoints and end of work
+2. **Descriptive Names**: Use clear, descriptive session names
+3. **Health Monitoring**: Regular reflection and health checks
+4. **Backup Strategy**: Multiple checkpoint saves during long work
+5. **Scope Management**: Load only necessary context for current work
+6. **Memory Hygiene**: Periodic consolidation and cleanup
+
+## Related Guides
+
+**Learning Progression:**
+
+**🌱 Essential (Week 1)**
+- [Quick Start Guide](../Getting-Started/quick-start.md) - First session experience
+- [Commands Reference](commands.md) - Session commands (/sc:load, /sc:save, /sc:reflect)
+- [Installation Guide](../Getting-Started/installation.md) - Serena MCP setup for sessions
+
+**🌿 Intermediate (Week 2-3)**
+- [MCP Servers Guide](mcp-servers.md) - Serena MCP for persistent memory
+- [Behavioral Modes](modes.md) - Task Management mode for session coordination
+- [Agents Guide](agents.md) - Agent persistence across sessions
+
+**🌲 Advanced (Month 2+)**
+- [Best Practices](../Reference/best-practices.md) - Session optimization strategies
+- [Examples Cookbook](../Reference/examples-cookbook.md) - Multi-session project patterns
+- [Flags Guide](flags.md) - Session control flags and optimization
+
+**🔧 Expert**
+- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Session implementation details
+- [Contributing Code](../Developer-Guide/contributing-code.md) - Extending session capabilities
+
+**Session-Specific Learning:**
+
+**🎯 Session Command Mastery:**
+- **Load Patterns**: `/sc:load` variations for different contexts
+- **Save Strategies**: Checkpoint vs milestone vs completion saves
+- **Reflection Types**: Progress, quality, completion, learning assessments
+
+**🧠 Memory Management:**
+- **Context Building**: How memory accumulates and evolves
+- **Pattern Recognition**: Understanding session intelligence
+- **Memory Optimization**: Efficient context management
+
+**👥 Team Coordination:**
+- **Shared Sessions**: Multi-developer session coordination
+- **Handoff Patterns**: Session transfer and continuity
+- **Integration Sessions**: Cross-team collaboration
+
+**🔄 Project Lifecycle:**
+- **Daily Workflows**: Effective day-to-day session patterns
+- **Feature Cycles**: Multi-session feature development
+- **Long-term Projects**: Enterprise-scale session management
+
+**💡 Session Mastery Tips:**
+- **Start Small**: Begin with simple load-work-save patterns
+- **Build Habits**: Regular reflection and checkpoint saves
+- **Learn Memory**: Understand how context builds over time
+- **Optimize Gradually**: Advanced patterns as projects grow
+- **Monitor Health**: Regular session health and performance checks
+
+**Common Session Workflows:**
+- **New Project**: Load → Analyze → Plan → Save
+- **Daily Work**: Load → Progress check → Work → Checkpoint → Save
+- **Feature Development**: Load → Brainstorm → Implement → Test → Reflect → Save
+- **Bug Investigation**: Load focused → Troubleshoot → Fix → Validate → Save
+- **Code Review**: Load changes → Analyze quality → Review → Document → Save