SuperClaude/README.md

# SuperClaude v4.0.0 🚀
[![Website Preview](https://img.shields.io/badge/Visit-Website-blue?logo=google-chrome)](https://superclaude-org.github.io/SuperClaude_Website/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/SuperClaude.svg)](https://pypi.org/project/SuperClaude/)
[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework)
[![GitHub issues](https://img.shields.io/github/issues/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/CONTRIBUTING.md)
[![Contributors](https://img.shields.io/github/contributors/SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)
[![Website](https://img.shields.io/website?url=https://superclaude-org.github.io/SuperClaude_Website/)](https://superclaude-org.github.io/SuperClaude_Website/)

An intelligent framework that transforms Claude Code into a comprehensive development environment with specialized agents, behavioral modes, and advanced MCP integration.

**📢 Status**: v4.0.0 is here! Major architecture overhaul with new behavioral modes, session lifecycle, and comprehensive agent system.

## What is SuperClaude v4.0.0? 🤔

SuperClaude v4.0.0 represents a complete evolution of the development framework, now featuring:
- 🛠️ **21 specialized commands** for comprehensive development workflows
- 🤖 **13 specialized agents** with domain expertise and intelligent routing
- 🧠 **5 Behavioral Modes** for different types of work (Brainstorming, Introspection, Task Management, Orchestration, Token Efficiency)
- 🔧 **6 MCP servers** including the powerful new Morphllm and Serena agents
- 💾 **Session Lifecycle** with persistent context via /sc:load and /sc:save

This is a complete rethink of how AI-assisted development should work - more intelligent, more capable, and more adaptable to your workflow! 🎯

## Support SuperClaude Development 💎

Help us continue advancing the future of AI-assisted development! SuperClaude v4.0.0 represents a major architectural evolution with significant improvements:

### What Your Support Enables 🚀
- **Framework Evolution** - Continued development of behavioral modes and agent intelligence
- **Claude Code Subscriptions** - Essential API access for framework development and testing
- **Documentation Quality** - Comprehensive guides and technical writing improvements
- **Community Resources** - Better tooling, examples, and educational materials

### Ways to Support 🤝

[![Support on Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Development-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/superclaude)
[![GitHub Sponsors](https://img.shields.io/badge/GitHub-Sponsor-EA4AAA?logo=github-sponsors&logoColor=white)](https://github.com/sponsors/SuperClaude-Org)
[![Support on Patreon](https://img.shields.io/badge/Patreon-Support%20Us-F96854?logo=patreon&logoColor=white)](https://patreon.com/superclaude)

## Current Status 📊

✅ **What's New in v4.0.0:**
- Complete rework of behavioral foundation with 30-50% token efficiency gains
- 13 specialized agents with domain expertise and collaborative coordination  
- Context-aware adaptive behavior with automatic activation
- Persistent development context across sessions with smart checkpointing
- Significant weight reduction while expanding capabilities
- Advanced MCP integration with Morphllm and Serena

✅ **What's Working Well:**
- All 21 commands with enhanced capabilities
- Full MCP server integration suite
- Session lifecycle with /sc:load and /sc:save
- Behavioral modes with automatic activation
- Intelligent agent routing and coordination

✅ **Production Ready:**
- Stable release with comprehensive testing
- Full documentation and user guides
- Performance optimizations implemented

## Key Features ✨

### 21 Specialized Commands 🛠️
Enhanced command suite for comprehensive development workflows:

**Development**: `/sc:implement`, `/sc:build`, `/sc:design`  
**Analysis**: `/sc:analyze`, `/sc:troubleshoot`, `/sc:explain`  
**Quality**: `/sc:improve`, `/sc:test`, `/sc:cleanup`  
**Session**: `/sc:load`, `/sc:save`, `/sc:brainstorm`, `/sc:reflect`  
**Workflow**: `/sc:task`, `/sc:spawn`, `/sc:workflow`, `/sc:select-tool`  
**Others**: `/sc:document`, `/sc:git`, `/sc:estimate`, `/sc:index`

### 13 Specialized Agents 🤖
AI specialists with deep domain expertise and intelligent coordination:
- 🏗️ **system-architect** - System design and architecture
- 🎨 **frontend-architect** - UI/UX and modern frontend development
- ⚙️ **backend-architect** - APIs, infrastructure, and server-side logic
- 🔍 **root-cause-analyst** - Systematic investigation and debugging
- 🛡️ **security-engineer** - Security assessment and vulnerability analysis
- ✍️ **technical-writer** - Technical documentation and writing
- ⚡ **performance-engineer** - Optimization and performance engineering
- 🧪 **quality-engineer** - Quality assurance and testing strategies
- 🐍 **python-expert** - Python development and best practices
- 🤖 **devops-architect** - Infrastructure and deployment automation
- 🔧 **refactoring-expert** - Code refactoring and clean code principles
- 📋 **requirements-analyst** - Requirements discovery and analysis
- 🎯 **learning-guide** - Teaching and educational explanations

*These agents feature intelligent routing, context awareness, and collaborative problem-solving capabilities.*

### 5 Behavioral Modes 🧠
Revolutionary behavioral system that adapts SuperClaude's approach:

#### Brainstorming Mode
- **Purpose**: Interactive requirements discovery and ideation
- **Triggers**: Ambiguous requests, exploration keywords, uncertainty indicators
- **Features**: Socratic dialogue, collaborative discovery, automated brief generation

#### Introspection Mode  
- **Purpose**: Meta-cognitive analysis and framework troubleshooting
- **Triggers**: Self-analysis requests, complex problem solving, error recovery
- **Features**: Reasoning analysis, decision validation, pattern recognition

#### Task Management Mode
- **Purpose**: Multi-layer orchestration and systematic delegation
- **Triggers**: Multi-step operations, complex builds, system-wide changes
- **Features**: Progressive orchestration, sub-agent delegation, performance analytics

#### Orchestration Mode
- **Purpose**: Intelligent tool selection and resource optimization
- **Triggers**: Multi-tool operations, performance constraints, parallel execution
- **Features**: Smart tool selection, parallel thinking, resource management

#### Token Efficiency Mode
- **Purpose**: Intelligent optimization with symbol systems and compression
- **Triggers**: Resource constraints, large contexts, performance needs
- **Features**: 30-50% token reduction, quality preservation, adaptive compression

### 6 MCP Server Integration 🔧
Comprehensive external tool ecosystem:
- **Context7** - Official library documentation and patterns
- **Sequential** - Multi-step analysis and complex reasoning
- **Magic** - Modern UI component generation
- **Playwright** - Browser automation and E2E testing
- **Morphllm** - Intelligent file editing with Fast Apply capability
- **Serena** - Semantic code analysis and project-wide operations

### Session Lifecycle System 💾
Persistent development context with intelligent management:
- **`/sc:load`** - Initialize projects with full context restoration
- **`/sc:save`** - Create checkpoints and preserve session state
- **Automatic Checkpoints** - Task completion, time-based, risk-based triggers
- **Cross-Session Learning** - Accumulated insights and pattern recognition

### Advanced Framework Features
Intelligent architecture with built-in capabilities:
- **Framework Coordinator** - Cross-component orchestration
- **Performance Monitor** - Real-time metrics and optimization
- **Quality Gates** - 8-step validation pipeline
- **Session Lifecycle** - Event-driven session management

## ⚠️ Upgrading from v3? Important!

SuperClaude v4.0.0 is a major architectural upgrade. Clean installation recommended:

1. **Backup Important Data** - Save any custom configurations
2. **Clean Previous Installation**:
   ```bash
   python3 -m SuperClaude uninstall  # If available
   rm -rf ~/.claude/SuperClaude/
   rm -rf ~/.claude/shared/
   ```
3. **Install v4.0.0** - Follow installation instructions below

### 🔄 **Key Changes for v3 Users**
- **New Commands**: `/sc:brainstorm`, `/sc:reflect`, `/sc:save`, `/sc:select-tool`
- **Session Management**: Use `/sc:load` to initialize projects, `/sc:save` for persistence
- **Agent System**: Enhanced from personas to full agent coordination
- **Behavioral Modes**: Automatic activation based on context and needs

## Installation 📦

SuperClaude v4.0.0 installation with enhanced capabilities:

### Step 1: Install the Package

**Option A: From PyPI (Recommended)**
```bash
pip install SuperClaude
```

**Option B: From Source**
```bash
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
pip install -e .
```

---
**Missing Python?** Install Python 3.8+ first:
```bash
# Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip

# macOS  
brew install python3

# Windows
# Download from https://python.org/downloads/
```

### Step 2: Run the v4.0.0 Installer

Enhanced installer with behavioral modes and session lifecycle:

```bash
# v4.0.0 setup (recommended for most users)
python3 -m SuperClaude install

# See all v4.0.0 options
python3 -m SuperClaude install --help
```

### Simple bash Command Usage 
```bash
# v4.0.0 setup
SuperClaude install
```

**That's it! 🎉** The v4.0.0 installer configures everything: behavioral modes, MCP servers, and session lifecycle.

## How v4.0.0 Works 🔄

SuperClaude v4.0.0 transforms Claude Code through intelligent architecture:

1. **Behavioral Modes** - Adaptive behavior based on context and task requirements
2. **Agent Coordination** - 13 specialized agents with intelligent routing and collaboration
3. **Session Lifecycle** - Persistent context with /sc:load and /sc:save commands
4. **MCP Integration** - 6 powerful servers for extended capabilities

The system intelligently adapts to your workflow, automatically activating appropriate modes and agents. 🧠

## v4.0.0 Architecture Highlights 🏗️

### Behavioral Intelligence
- **Automatic Mode Detection** - Context-aware behavioral adaptation
- **Cross-Mode Coordination** - Seamless integration between behavioral patterns
- **Progressive Enhancement** - Capabilities scale with complexity

### Agent Orchestration
- **Intelligent Routing** - Smart agent selection based on domain expertise
- **Collaborative Problem-Solving** - Multi-agent coordination for complex tasks
- **Context Preservation** - Agents maintain awareness across interactions

### Session Management
- **Persistent Context** - Full project state preservation across sessions
- **Intelligent Checkpointing** - Automatic saves based on risk and completion
- **Cross-Session Learning** - Accumulated insights and pattern recognition

## Configuration ⚙️

v4.0.0 configuration with enhanced behavioral controls:
- `~/.claude/*.md` - Behavioral mode configurations
- `~/.claude/agents/` - Agent-specific customizations
- `~/.claude/commands/` - Command definitions and configurations
- `~/.serena/` - Session lifecycle and memory management

Most users can use defaults - v4.0.0 intelligently adapts to your workflow! 🎛️

## Documentation 📖

Comprehensive v4.0.0 guides and documentation:

- 📚 [**v4.0.0 User Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/superclaude-user-guide.md) - Complete v4.0.0 overview and getting started
- 🛠️ [**Commands Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/commands-guide.md) - All 21 commands with v4.0.0 enhancements
- 🧠 [**Behavioral Modes Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/behavioral-modes-guide.md) - Understanding the 5 behavioral modes
- 🤖 [**Agent System Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/agent-system-guide.md) - Working with 13 specialized agents
- 🏳️ [**Flags Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/flags-guide.md) - v4.0.0 command flags and behavioral controls
- 📦 [**Installation Guide**](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/Guides/installation-guide.md) - Detailed v4.0.0 installation and setup

## Contributing 🤝

v4.0.0 opens new contribution opportunities:
- 🐛 **Bug Reports** - Help us improve the stable release
- 📝 **Documentation** - v4.0.0 features need clear explanation
- 🧪 **Testing** - Community participation across different environments
- 🔧 **Framework Development** - Extend the framework capabilities
- 🤖 **Agent Enhancement** - Improve specialized agent capabilities
- 🧠 **Behavioral Modes** - Contribute to mode intelligence

The v4.0.0 architecture is modular - many ways to contribute!

### Documentation & Community 📝
While we strive for accuracy, the rapid v4.0.0 evolution means documentation may contain errors. We rely on our community to:
- **Report Issues** - Help us identify documentation gaps or technical problems
- **Submit Improvements** - PRs for documentation fixes and enhancements are always welcome
- **Share Feedback** - Your experience helps shape future development priorities

*Every contribution, whether code, documentation, or financial support, helps make SuperClaude better for the entire development community! 🌟*

## Project Structure 📁

```
SuperClaude_Framework/
├── 📁 SuperClaude/                     # Core framework documentation & behavioral definitions
│   ├── 🤖 Agents/                      # 13 specialized agents with domain expertise
│   │   ├── backend-architect.md        # API & server-side architecture specialist
│   │   ├── devops-architect.md         # Infrastructure & deployment automation
│   │   ├── frontend-architect.md       # UI/UX & modern frontend development
│   │   ├── learning-guide.md           # Educational explanations & tutorials
│   │   ├── performance-engineer.md     # Optimization & performance engineering
│   │   ├── python-expert.md            # Python development & best practices
│   │   ├── quality-engineer.md         # QA strategies & testing frameworks
│   │   ├── refactoring-expert.md       # Code cleanup & architectural improvements
│   │   ├── requirements-analyst.md     # Requirements discovery & analysis
│   │   ├── root-cause-analyst.md       # Systematic debugging & investigation
│   │   ├── security-engineer.md        # Security assessment & vulnerability analysis
│   │   ├── system-architect.md         # High-level system design & architecture
│   │   └── technical-writer.md         # Technical documentation & communication
│   ├── 🛠️ Commands/                     # 21 specialized slash commands
│   │   ├── analyze.md                  # Code & project analysis
│   │   ├── brainstorm.md              # Interactive requirements discovery
│   │   ├── build.md                   # Smart build with auto-optimization
│   │   ├── cleanup.md                 # Code cleanup & organization
│   │   ├── design.md                  # Architecture & design planning
│   │   ├── document.md                # Technical documentation generation
│   │   ├── estimate.md                # Project estimation & planning
│   │   ├── explain.md                 # Code explanation & education
│   │   ├── git.md                     # Advanced git operations
│   │   ├── implement.md               # Feature implementation & development
│   │   ├── improve.md                 # Code enhancement & optimization
│   │   ├── index.md                   # Command registry & coordination
│   │   ├── load.md                    # Session initialization & context loading
│   │   ├── reflect.md                 # Session reflection & analysis
│   │   ├── save.md                    # Session persistence & context saving
│   │   ├── select-tool.md             # Intelligent tool selection
│   │   ├── spawn.md                   # Agent spawning & coordination
│   │   ├── task.md                    # Task management & orchestration
│   │   ├── test.md                    # Testing strategies & execution
│   │   ├── troubleshoot.md            # Problem diagnosis & resolution
│   │   └── workflow.md                # Workflow automation & management
│   ├── 🧠 Core/                        # Foundational behavioral rules & principles
│   │   ├── FLAGS.md                   # Behavioral flags for execution modes
│   │   ├── PRINCIPLES.md              # Software engineering principles
│   │   └── RULES.md                   # Operational rules & guidelines
│   ├── 🔧 MCP/                         # MCP server integration & configs
│   │   └── configs/                   # MCP server configuration files
│   └── 🎭 Modes/                       # 5 behavioral modes for adaptive behavior
│       ├── MODE_Brainstorming.md      # Interactive discovery & ideation
│       ├── MODE_Introspection.md      # Meta-cognitive analysis & reflection
│       ├── MODE_Orchestration.md      # Intelligent tool selection & coordination
│       ├── MODE_Task_Management.md    # Multi-layer orchestration & delegation
│       └── MODE_Token_Efficiency.md   # Symbol-enhanced compression & optimization
├── 📚 Guides/                          # Comprehensive user documentation
│   └── superclaude-user-guide.md      # Complete usage guide & workflows
├── 🏗️ setup/                           # Modular installation & configuration system
│   ├── cli/                           # Command-line interface & operations
│   │   ├── commands/                  # CLI command implementations
│   │   ├── install.py                 # Installation orchestration
│   │   ├── update.py                  # Update management
│   │   └── uninstall.py               # Clean uninstallation
│   ├── components/                    # Component-based installation modules
│   ├── core/                          # Core installation logic & registry
│   │   ├── installer.py               # Installation orchestration engine
│   │   └── registry.py                # Component discovery & dependency resolution
│   ├── data/                          # Installation data & metadata
│   └── services/                      # Configuration management services
│       ├── claude_md.py               # Dynamic CLAUDE.md generation
│       ├── config.py                  # Configuration management
│       └── file_ops.py                # File operation utilities
├── 🔨 scripts/                         # Build, validation & publishing automation
│   ├── build_and_upload.py           # PyPI package building & publishing
│   ├── publish.sh                     # Production publishing workflow
│   └── validate_pypi_ready.py        # Package validation & compliance
├── 📄 Configuration Files
│   ├── CLAUDE.md                      # Project-specific Claude Code instructions
│   ├── pyproject.toml                 # Python project configuration & dependencies
│   ├── uv.lock                       # Dependency lock file for reproducible builds
│   └── README.md                      # This comprehensive project overview
└── 📋 Documentation
    ├── CHANGELOG.md                   # Version history & release notes
    ├── CONTRIBUTING.md                # Contribution guidelines & development setup
    ├── CODE_OF_CONDUCT.md             # Community standards & expectations
    ├── SECURITY.md                    # Security policies & vulnerability reporting
    └── PUBLISHING.md                  # Publishing guidelines & release procedures
```

## v4.0.0 Architecture Notes 🏗️

The v4.0.0 architecture focuses on:
- **Behavioral Intelligence** - Context-aware adaptive behavior
- **Agent Orchestration** - Sophisticated multi-agent coordination
- **Session Persistence** - Continuous learning and context preservation
- **Performance** - Token efficiency and resource optimization

v4.0.0 represents a fundamental evolution in AI-assisted development frameworks.

## FAQ 🙋

**Q: What's new in v4.0.0 compared to V3?**  
A: Complete architecture overhaul with behavioral modes, session lifecycle, 13 agents, and 6 MCP servers.

**Q: How does the new architecture work?**  
A: Built on behavioral modes, intelligent agents, and session persistence for adaptive development workflows.

**Q: Should I upgrade from V3?**  
A: v4.0.0 offers significant improvements, with clean installation recommended for best experience.

**Q: How stable is v4.0.0?**  
A: Production-ready stable release with comprehensive testing and community validation!

## SuperClaude Contributors

[![Contributors](https://contrib.rocks/image?repo=SuperClaude-Org/SuperClaude_Framework)](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)

## License

MIT - [See LICENSE file for details](https://opensource.org/licenses/MIT)

## Star History

<a href="https://www.star-history.com/#SuperClaude-Org/SuperClaude_Framework&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=SuperClaude-Org/SuperClaude_Framework&type=Date" />
 </picture>
</a>
---

*v4.0.0: The future of AI-assisted development is here. Experience intelligent, adaptive, and powerful development workflows! 🚀*

---