mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
40840dae0b
- Transform 28K+ token superclaude-user-guide.md into 4.5K token overview (84% reduction) - Extract specialized guides: examples-cookbook.md, troubleshooting-guide.md, best-practices.md, session-management.md, technical-architecture.md - Add comprehensive cross-references between all guides for improved navigation - Maintain professional documentation quality with technical-writer agent approach - Remove template files and consolidate agent naming (backend-engineer → backend-architect, etc.) - Update all existing guides with cross-references and related guides sections - Create logical learning paths from beginner to advanced users - Eliminate content duplication while preserving all valuable information 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
416 lines
22 KiB
Markdown
416 lines
22 KiB
Markdown
# SuperClaude v4.0.0 🚀
|
|
[](https://superclaude-org.github.io/SuperClaude_Website/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://pypi.org/project/SuperClaude/)
|
|
[](https://github.com/SuperClaude-Org/SuperClaude_Framework)
|
|
[](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
|
[](https://github.com/SuperClaude-Org/SuperClaude_Framework/blob/master/CONTRIBUTING.md)
|
|
[](https://github.com/SuperClaude-Org/SuperClaude_Framework/graphs/contributors)
|
|
[](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 🤝
|
|
|
|
[](https://ko-fi.com/superclaude)
|
|
[](https://github.com/sponsors/SuperClaude-Org)
|
|
[](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
|
|
|
|
[](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! 🚀*
|
|
|
|
--- |