mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: PEP8 compliance - directory rename and code formatting (#425)
* fix(orchestration): add WebFetch auto-trigger for infrastructure configuration Problem: Infrastructure configuration changes (e.g., Traefik port settings) were being made based on assumptions without consulting official documentation, violating the 'Evidence > assumptions' principle in PRINCIPLES.md. Solution: - Added Infrastructure Configuration Validation section to MODE_Orchestration.md - Auto-triggers WebFetch for infrastructure tools (Traefik, nginx, Docker, etc.) - Enforces MODE_DeepResearch activation for investigation - BLOCKS assumption-based configuration changes Testing: Verified WebFetch successfully retrieves Traefik official docs (port 80 default) This prevents production outages from infrastructure misconfiguration by ensuring all technical recommendations are backed by official documentation. * feat: Add PM Agent (Project Manager Agent) for seamless orchestration Introduces PM Agent as the default orchestration layer that coordinates all sub-agents and manages workflows automatically. Key Features: - Default orchestration: All user interactions handled by PM Agent - Auto-delegation: Intelligent sub-agent selection based on task analysis - Docker Gateway integration: Zero-token baseline with dynamic MCP loading - Self-improvement loop: Automatic documentation of patterns and mistakes - Optional override: Users can specify sub-agents explicitly if desired Architecture: - Agent spec: SuperClaude/Agents/pm-agent.md - Command: SuperClaude/Commands/pm.md - Updated docs: README.md (15→16 agents), agents.md (new Orchestration category) User Experience: - Default: PM Agent handles everything (seamless, no manual routing) - Optional: Explicit --agent flag for direct sub-agent access - Both modes available simultaneously (no user downside) Implementation Status: - ✅ Specification complete - ✅ Documentation complete - ⏳ Prototype implementation needed - ⏳ Docker Gateway integration needed - ⏳ Testing and validation needed Refs: kazukinakai/docker-mcp-gateway (IRIS MCP Gateway integration) * feat: Add Agent Orchestration rules for PM Agent default activation Implements PM Agent as the default orchestration layer in RULES.md. Key Changes: - New 'Agent Orchestration' section (CRITICAL priority) - PM Agent receives ALL user requests by default - Manual override with @agent-[name] bypasses PM Agent - Agent Selection Priority clearly defined: 1. Manual override → Direct routing 2. Default → PM Agent → Auto-delegation 3. Delegation based on keywords, file types, complexity, context User Experience: - Default: PM Agent handles everything (seamless) - Override: @agent-[name] for direct specialist access - Transparent: PM Agent reports delegation decisions This establishes PM Agent as the orchestration layer while respecting existing auto-activation patterns and manual overrides. Next Steps: - Local testing in agiletec project - Iteration based on actual behavior - Documentation updates as needed * refactor(pm-agent): redesign as self-improvement meta-layer Problem Resolution: PM Agent's initial design competed with existing auto-activation for task routing, creating confusion about orchestration responsibilities and adding unnecessary complexity. Design Change: Redefined PM Agent as a meta-layer agent that operates AFTER specialist agents complete tasks, focusing on: - Post-implementation documentation and pattern recording - Immediate mistake analysis with prevention checklists - Monthly documentation maintenance and noise reduction - Pattern extraction and knowledge synthesis Two-Layer Orchestration System: 1. Task Execution Layer: Existing auto-activation handles task routing (unchanged) 2. Self-Improvement Layer: PM Agent meta-layer handles documentation (new) Files Modified: - SuperClaude/Agents/pm-agent.md: Complete rewrite with meta-layer design - Category: orchestration → meta - Triggers: All user interactions → Post-implementation, mistakes, monthly - Behavioral Mindset: Continuous learning system - Self-Improvement Workflow: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE - SuperClaude/Core/RULES.md: Agent Orchestration section updated - Split into Task Execution Layer + Self-Improvement Layer - Added orchestration flow diagram - Clarified PM Agent activates AFTER task completion - README.md: Updated PM Agent description - "orchestrates all interactions" → "ensures continuous learning" - Docs/User-Guide/agents.md: PM Agent section rewritten - Section: Orchestration Agent → Meta-Layer Agent - Expertise: Project orchestration → Self-improvement workflow executor - Examples: Task coordination → Post-implementation documentation - PR_DOCUMENTATION.md: Comprehensive PR documentation added - Summary, motivation, changes, testing, breaking changes - Two-layer orchestration system diagram - Verification checklist Integration Validated: Tested with agiletec project's self-improvement-workflow.md: ✅ PM Agent aligns with existing BEFORE/DURING/AFTER/MISTAKE RECOVERY phases ✅ Complements (not competes with) existing workflow ✅ agiletec workflow defines WHAT, PM Agent defines WHO executes it Breaking Changes: None - Existing auto-activation continues unchanged - Specialist agents unaffected - User workflows remain the same - New capability: Automatic documentation and knowledge maintenance Value Proposition: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Claude Code conversation history management research Research covering .jsonl file structure, performance impact, and retention policies. Content: - Claude Code .jsonl file format and message types - Performance issues from GitHub (memory leaks, conversation compaction) - Retention policies (consumer vs enterprise) - Rotation recommendations based on actual data - File history snapshot tracking mechanics Source: Moved from agiletec project (research applicable to all Claude Code projects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add Development documentation structure Phase 1: Documentation Structure complete - Add Docs/Development/ directory for development documentation - Add ARCHITECTURE.md - System architecture with PM Agent meta-layer - Add ROADMAP.md - 5-phase development plan with checkboxes - Add TASKS.md - Daily task tracking with progress indicators - Add PROJECT_STATUS.md - Current status dashboard and metrics - Add pm-agent-integration.md - Implementation guide for PM Agent mode This establishes comprehensive documentation foundation for: - System architecture understanding - Development planning and tracking - Implementation guidance - Progress visibility Related: #pm-agent-mode #documentation #phase-1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: PM Agent session lifecycle and PDCA implementation Phase 2: PM Agent Mode Integration (Design Phase) Commands/pm.md updates: - Add "Always-Active Foundation Layer" concept - Add Session Lifecycle (Session Start/During Work/Session End) - Add PDCA Cycle (Plan/Do/Check/Act) automation - Add Serena MCP Memory Integration (list/read/write_memory) - Document auto-activation triggers Agents/pm-agent.md updates: - Add Session Start Protocol (MANDATORY auto-activation) - Add During Work PDCA Cycle with example workflows - Add Session End Protocol with state preservation - Add PDCA Self-Evaluation Pattern - Add Documentation Strategy (temp → patterns/mistakes) - Add Memory Operations Reference Key Features: - Session start auto-activation for context restoration - 30-minute checkpoint saves during work - Self-evaluation with think_about_* operations - Systematic documentation lifecycle - Knowledge evolution to CLAUDE.md Implementation Status: - ✅ Design complete (Commands/pm.md, Agents/pm-agent.md) - ⏳ Implementation pending (Core components) - ⏳ Serena MCP integration pending Salvaged from mistaken development in ~/.claude directory Related: #pm-agent-mode #session-lifecycle #pdca-cycle #phase-2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: disable Serena MCP auto-browser launch Disable web dashboard and GUI log window auto-launch in Serena MCP server to prevent intrusive browser popups on startup. Users can still manually access the dashboard at http://localhost:24282/dashboard/ if needed. Changes: - Add CLI flags to Serena run command: - --enable-web-dashboard false - --enable-gui-log-window false - Ensures Git-tracked configuration (no reliance on ~/.serena/serena_config.yml) - Aligns with AIRIS MCP Gateway integration approach 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename directories to lowercase for PEP8 compliance - Rename superclaude/Agents -> superclaude/agents - Rename superclaude/Commands -> superclaude/commands - Rename superclaude/Core -> superclaude/core - Rename superclaude/Examples -> superclaude/examples - Rename superclaude/MCP -> superclaude/mcp - Rename superclaude/Modes -> superclaude/modes This change follows Python PEP8 naming conventions for package directories. * style: fix PEP8 violations and update package name to lowercase Changes: - Format all Python files with black (43 files reformatted) - Update package name from 'SuperClaude' to 'superclaude' in pyproject.toml - Fix import statements to use lowercase package name - Add missing imports (timedelta, __version__) - Remove old SuperClaude.egg-info directory PEP8 violations reduced from 2672 to 701 (mostly E501 line length due to black's 88 char vs flake8's 79 char limit). * docs: add PM Agent development documentation Add comprehensive PM Agent development documentation: - PM Agent ideal workflow (7-phase autonomous cycle) - Project structure understanding (Git vs installed environment) - Installation flow understanding (CommandsComponent behavior) - Task management system (current-tasks.md) Purpose: Eliminate repeated explanations and enable autonomous PDCA cycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(pm-agent): add self-correcting execution and warning investigation culture ## Changes ### superclaude/commands/pm.md - Add "Self-Correcting Execution" section with root cause analysis protocol - Add "Warning/Error Investigation Culture" section enforcing zero-tolerance for dismissal - Define error detection protocol: STOP → Investigate → Hypothesis → Different Solution → Execute - Document anti-patterns (retry without understanding) and correct patterns (research-first) ### docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md - Add PDCA workflow hypothesis document for PM Agent autonomous enhancement ## Rationale PM Agent must never retry failed operations without understanding root causes. All warnings and errors require investigation via context7/WebFetch/documentation to ensure production-quality code and prevent technical debt accumulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(installer): add airis-mcp-gateway MCP server option ## Changes - Add airis-mcp-gateway to MCP server options in installer - Configuration: GitHub-based installation via uvx - Repository: https://github.com/oraios/airis-mcp-gateway - Purpose: Dynamic MCP Gateway for zero-token baseline and on-demand tool loading ## Implementation Added to setup/components/mcp.py self.mcp_servers dictionary with: - install_method: github - install_command: uvx test installation - run_command: uvx runtime execution - required: False (optional server) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki nakai
514
docs/Getting-Started/installation.md
Normal file
514
docs/Getting-Started/installation.md
Normal file
@@ -0,0 +1,514 @@
|
||||
<div align="center">
|
||||
|
||||
# 📦 SuperClaude Installation Guide
|
||||
|
||||
### **Transform Claude Code with 21 Commands, 14 Agents & 6 MCP Servers**
|
||||
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/badge/version-4.1.5-blue?style=for-the-badge" alt="Version">
|
||||
<img src="https://img.shields.io/badge/Python-3.8+-green?style=for-the-badge" alt="Python">
|
||||
<img src="https://img.shields.io/badge/Platform-Linux%20|%20macOS%20|%20Windows-orange?style=for-the-badge" alt="Platform">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="#-quick-installation">Quick Install</a> •
|
||||
<a href="#-requirements">Requirements</a> •
|
||||
<a href="#-installation-methods">Methods</a> •
|
||||
<a href="#-verification">Verify</a> •
|
||||
<a href="#-troubleshooting">Troubleshoot</a>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ⚡ **Quick Installation**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Choose Your Preferred Method**
|
||||
|
||||
| Method | Command | Platform | Best For |
|
||||
|:------:|---------|:--------:|----------|
|
||||
| **🐍 pipx** | `pipx install SuperClaude && SuperClaude install` | Linux/macOS | **✅ Recommended** - Isolated environment |
|
||||
| **📦 pip** | `pip install SuperClaude && SuperClaude install` | All | Traditional Python setups |
|
||||
| **🌐 npm** | `npm install -g @bifrost_inc/superclaude && superclaude install` | All | Node.js developers |
|
||||
| **🔧 Dev** | `git clone ... && pip install -e ".[dev]"` | All | Contributors & developers |
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Requirements**
|
||||
|
||||
<div align="center">
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
|
||||
### ✅ **Required**
|
||||
|
||||
| Component | Version | Check Command |
|
||||
|-----------|---------|---------------|
|
||||
| **Python** | 3.8+ | `python3 --version` |
|
||||
| **pip** | Latest | `pip --version` |
|
||||
| **Claude Code** | Latest | `claude --version` |
|
||||
| **Disk Space** | 50MB | `df -h` |
|
||||
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
|
||||
### 💡 **Optional**
|
||||
|
||||
| Component | Purpose | Check Command |
|
||||
|-----------|---------|---------------|
|
||||
| **Node.js** | MCP Servers | `node --version` |
|
||||
| **Git** | Version Control | `git --version` |
|
||||
| **pipx** | Isolated Install | `pipx --version` |
|
||||
| **RAM** | Performance | 1GB recommended |
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
<details>
|
||||
<summary><b>🔍 Quick System Check</b></summary>
|
||||
|
||||
```bash
|
||||
# Run this to check all requirements at once
|
||||
python3 --version && echo "✅ Python OK" || echo "❌ Python missing"
|
||||
claude --version && echo "✅ Claude Code OK" || echo "❌ Claude Code missing"
|
||||
node --version 2>/dev/null && echo "✅ Node.js OK (optional)" || echo "⚠️ Node.js missing (optional)"
|
||||
git --version 2>/dev/null && echo "✅ Git OK (optional)" || echo "⚠️ Git missing (optional)"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Installation Methods**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Detailed Installation Instructions**
|
||||
|
||||
</div>
|
||||
|
||||
### **Method 1: pipx (Recommended)**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="60%">
|
||||
|
||||
```bash
|
||||
# Install pipx if not present
|
||||
python3 -m pip install --user pipx
|
||||
python3 -m pipx ensurepath
|
||||
|
||||
# Install SuperClaude
|
||||
pipx install SuperClaude
|
||||
|
||||
# Run the installer
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
</td>
|
||||
<td width="40%">
|
||||
|
||||
**✅ Advantages:**
|
||||
- Isolated environment
|
||||
- No dependency conflicts
|
||||
- Clean uninstall
|
||||
- Automatic PATH setup
|
||||
|
||||
**📍 Best for:**
|
||||
- Linux/macOS users
|
||||
- Clean system installs
|
||||
- Multiple Python projects
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### **Method 2: pip (Traditional)**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="60%">
|
||||
|
||||
```bash
|
||||
# Standard installation
|
||||
pip install SuperClaude
|
||||
|
||||
# Or user installation
|
||||
pip install --user SuperClaude
|
||||
|
||||
# Run the installer
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
</td>
|
||||
<td width="40%">
|
||||
|
||||
**✅ Advantages:**
|
||||
- Works everywhere
|
||||
- Familiar to Python users
|
||||
- Direct installation
|
||||
|
||||
**📍 Best for:**
|
||||
- Windows users
|
||||
- Virtual environments
|
||||
- Quick setup
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### **Method 3: npm (Cross-platform)**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="60%">
|
||||
|
||||
```bash
|
||||
# Global installation
|
||||
npm install -g @bifrost_inc/superclaude
|
||||
|
||||
# Run the installer
|
||||
superclaude install
|
||||
```
|
||||
|
||||
</td>
|
||||
<td width="40%">
|
||||
|
||||
**✅ Advantages:**
|
||||
- Cross-platform
|
||||
- NPM ecosystem
|
||||
- JavaScript familiar
|
||||
|
||||
**📍 Best for:**
|
||||
- Node.js developers
|
||||
- NPM users
|
||||
- Cross-platform needs
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### **Method 4: Development Installation**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="60%">
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||||
cd SuperClaude_Framework
|
||||
|
||||
# Install in development mode
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Test installation
|
||||
SuperClaude install --dry-run
|
||||
```
|
||||
|
||||
</td>
|
||||
<td width="40%">
|
||||
|
||||
**✅ Advantages:**
|
||||
- Latest features
|
||||
- Contribute to project
|
||||
- Full source access
|
||||
|
||||
**📍 Best for:**
|
||||
- Contributors
|
||||
- Custom modifications
|
||||
- Testing new features
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## 🎛️ **Installation Options**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Customize Your Installation**
|
||||
|
||||
| Option | Command | Description |
|
||||
|--------|---------|-------------|
|
||||
| **Interactive** | `SuperClaude install` | Guided setup with prompts |
|
||||
| **Specific Components** | `SuperClaude install --components core mcp modes` | Install only what you need |
|
||||
| **Preview Mode** | `SuperClaude install --dry-run` | See what will be installed |
|
||||
| **Force Install** | `SuperClaude install --force --yes` | Skip all confirmations |
|
||||
| **List Components** | `SuperClaude install --list-components` | View available components |
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Verification**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Confirm Successful Installation**
|
||||
|
||||
</div>
|
||||
|
||||
### **Step 1: Check Installation**
|
||||
|
||||
```bash
|
||||
# Verify SuperClaude version
|
||||
python3 -m SuperClaude --version
|
||||
# Expected: SuperClaude 4.1.5
|
||||
|
||||
# List installed components
|
||||
SuperClaude install --list-components
|
||||
# Expected: List of available components
|
||||
```
|
||||
|
||||
### **Step 2: Test in Claude Code**
|
||||
|
||||
```bash
|
||||
# Open Claude Code and try these commands:
|
||||
/sc:brainstorm "test project" # Should trigger discovery questions
|
||||
/sc:analyze README.md # Should provide structured analysis
|
||||
@agent-security "review code" # Should activate security specialist
|
||||
```
|
||||
|
||||
### **Step 3: What's Installed**
|
||||
|
||||
<div align="center">
|
||||
|
||||
| Location | Contents | Size |
|
||||
|----------|----------|------|
|
||||
| `~/.claude/` | Framework files | ~50MB |
|
||||
| `~/.claude/CLAUDE.md` | Main entry point | ~2KB |
|
||||
| `~/.claude/*.md` | Behavioral instructions | ~200KB |
|
||||
| `~/.claude/claude-code-settings.json` | MCP configurations | ~5KB |
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ **Management**
|
||||
|
||||
<div align="center">
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>📦 Update</th>
|
||||
<th>💾 Backup</th>
|
||||
<th>🗑️ Uninstall</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```bash
|
||||
# Update to latest
|
||||
pip install --upgrade SuperClaude
|
||||
SuperClaude update
|
||||
```
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
```bash
|
||||
# Create backup
|
||||
SuperClaude backup --create
|
||||
|
||||
# Restore backup
|
||||
SuperClaude backup --restore [file]
|
||||
```
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
```bash
|
||||
# Remove framework
|
||||
SuperClaude uninstall
|
||||
|
||||
# Uninstall package
|
||||
pip uninstall SuperClaude
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Troubleshooting**
|
||||
|
||||
<details>
|
||||
<summary><b>❌ PEP 668 Error (Python Package Management)</b></summary>
|
||||
|
||||
This error occurs on systems with externally managed Python environments.
|
||||
|
||||
**Solutions (in order of preference):**
|
||||
|
||||
```bash
|
||||
# Option 1: Use pipx (Recommended)
|
||||
pipx install SuperClaude
|
||||
|
||||
# Option 2: User installation
|
||||
pip install --user SuperClaude
|
||||
|
||||
# Option 3: Virtual environment
|
||||
python3 -m venv superclaude-env
|
||||
source superclaude-env/bin/activate # Linux/macOS
|
||||
# or
|
||||
superclaude-env\Scripts\activate # Windows
|
||||
pip install SuperClaude
|
||||
|
||||
# Option 4: Force (use with caution)
|
||||
pip install --break-system-packages SuperClaude
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>❌ Command Not Found</b></summary>
|
||||
|
||||
If `SuperClaude` command is not found after installation:
|
||||
|
||||
```bash
|
||||
# Check if package is installed
|
||||
python3 -m pip show SuperClaude
|
||||
|
||||
# Run using Python module
|
||||
python3 -m SuperClaude install
|
||||
|
||||
# Add to PATH (if using --user)
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # Linux
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # macOS
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>❌ Claude Code Not Found</b></summary>
|
||||
|
||||
If Claude Code is not installed or not in PATH:
|
||||
|
||||
1. Download from [https://claude.ai/code](https://claude.ai/code)
|
||||
2. Install following platform instructions
|
||||
3. Verify with: `claude --version`
|
||||
4. Restart terminal after installation
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>❌ Permission Denied</b></summary>
|
||||
|
||||
For permission errors during installation:
|
||||
|
||||
```bash
|
||||
# Use user installation
|
||||
pip install --user SuperClaude
|
||||
|
||||
# Or use sudo (not recommended)
|
||||
sudo pip install SuperClaude
|
||||
|
||||
# Better: use pipx
|
||||
pipx install SuperClaude
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>❌ Missing Python or pip</b></summary>
|
||||
|
||||
**Linux (Ubuntu/Debian):**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install python3 python3-pip python3-venv
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
# Install Homebrew first if needed
|
||||
brew install python3
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
- Download from [python.org](https://python.org)
|
||||
- Check "Add Python to PATH" during installation
|
||||
- Restart terminal after installation
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 📚 **Next Steps**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Your Learning Journey**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>🌱 Start Here</th>
|
||||
<th>🌿 Expand Skills</th>
|
||||
<th>🌲 Master Framework</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">
|
||||
|
||||
**First Week:**
|
||||
- [Quick Start Guide](quick-start.md)
|
||||
- [Commands Reference](../User-Guide/commands.md)
|
||||
- Try `/sc:brainstorm`
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
**Week 2-3:**
|
||||
- [Behavioral Modes](../User-Guide/modes.md)
|
||||
- [Agents Guide](../User-Guide/agents.md)
|
||||
- [Examples Cookbook](../Reference/examples-cookbook.md)
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
**Advanced:**
|
||||
- [MCP Servers](../User-Guide/mcp-servers.md)
|
||||
- [Technical Architecture](../Developer-Guide/technical-architecture.md)
|
||||
- [Contributing Code](../Developer-Guide/contributing-code.md)
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **🎉 Installation Complete!**
|
||||
|
||||
You now have access to:
|
||||
|
||||
<p align="center">
|
||||
<b>21 Commands</b> • <b>14 AI Agents</b> • <b>6 Behavioral Modes</b> • <b>6 MCP Servers</b>
|
||||
</p>
|
||||
|
||||
**Ready to start?** Try `/sc:brainstorm` in Claude Code for your first SuperClaude experience!
|
||||
|
||||
<p align="center">
|
||||
<a href="quick-start.md">
|
||||
<img src="https://img.shields.io/badge/📖_Continue_to-Quick_Start_Guide-blue?style=for-the-badge" alt="Quick Start">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
492
docs/Getting-Started/quick-start.md
Normal file
492
docs/Getting-Started/quick-start.md
Normal file
@@ -0,0 +1,492 @@
|
||||
<div align="center">
|
||||
|
||||
# 🚀 SuperClaude Quick Start Guide
|
||||
|
||||
### **Context Engineering Framework for Claude Code**
|
||||
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/badge/Framework-Context_Engineering-purple?style=for-the-badge" alt="Framework">
|
||||
<img src="https://img.shields.io/badge/Version-4.1.5-blue?style=for-the-badge" alt="Version">
|
||||
<img src="https://img.shields.io/badge/Time_to_Start-5_Minutes-green?style=for-the-badge" alt="Quick Start">
|
||||
</p>
|
||||
|
||||
> **💡 Key Insight**: SuperClaude doesn't replace Claude Code - it **configures and enhances** it through behavioral context injection
|
||||
|
||||
<p align="center">
|
||||
<a href="#-how-it-works">How It Works</a> •
|
||||
<a href="#-instant-start">Instant Start</a> •
|
||||
<a href="#-core-components">Components</a> •
|
||||
<a href="#-workflow-patterns">Workflows</a> •
|
||||
<a href="#-when-to-use">When to Use</a>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## 📊 **Framework Capabilities**
|
||||
|
||||
| **Commands** | **AI Agents** | **Behavioral Modes** | **MCP Servers** |
|
||||
|:------------:|:-------------:|:-------------------:|:---------------:|
|
||||
| **21** | **14** | **6** | **6** |
|
||||
| `/sc:` triggers | Domain specialists | Context adaptation | Tool integration |
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **How It Works**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Framework Architecture Flow**
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ User Input │────>│ Claude Code │────>│ Context Files │
|
||||
│ /sc:command │ │ Reads Context │ │ (.md behaviors)│
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Enhanced │<─────│ Behavioral │<────│ MCP Servers │
|
||||
│ Response │ │ Activation │ │ (if configured) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**The Magic**: When you type `/sc:brainstorm`, Claude reads behavioral instructions from installed `.md` files and responds with enhanced capabilities
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ⚡ **Instant Start**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **5-Minute Journey from Installation to First Command**
|
||||
|
||||
</div>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th width="50%">📦 Step 1: Install (Terminal)</th>
|
||||
<th width="50%">💬 Step 2: Use (Claude Code)</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">
|
||||
|
||||
```bash
|
||||
# Quick install with pipx
|
||||
pipx install SuperClaude && SuperClaude install
|
||||
|
||||
# Or traditional pip
|
||||
pip install SuperClaude && SuperClaude install
|
||||
|
||||
# Or via npm
|
||||
npm install -g @bifrost_inc/superclaude && superclaude install
|
||||
```
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
```text
|
||||
# Interactive discovery
|
||||
/sc:brainstorm "web app for task management"
|
||||
|
||||
# Analyze existing code
|
||||
/sc:analyze src/
|
||||
|
||||
# Generate implementation
|
||||
/sc:implement "user authentication"
|
||||
|
||||
# Activate specialist
|
||||
@agent-security "review auth flow"
|
||||
```
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<details>
|
||||
<summary><b>🎥 What Happens Behind the Scenes</b></summary>
|
||||
|
||||
1. **Context Loading**: Claude Code imports behavioral `.md` files via `CLAUDE.md`
|
||||
2. **Pattern Recognition**: Recognizes `/sc:` and `@agent-` trigger patterns
|
||||
3. **Behavioral Activation**: Applies corresponding instructions from context files
|
||||
4. **MCP Integration**: Uses configured external tools when available
|
||||
5. **Response Enhancement**: Follows framework patterns for comprehensive responses
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Core Components**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Four Pillars of SuperClaude**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="25%">
|
||||
|
||||
### 📝 **Commands**
|
||||
<h2>21</h2>
|
||||
|
||||
**Slash Commands**
|
||||
|
||||
`/sc:brainstorm`
|
||||
`/sc:implement`
|
||||
`/sc:analyze`
|
||||
`/sc:workflow`
|
||||
|
||||
*Workflow automation*
|
||||
|
||||
</td>
|
||||
<td align="center" width="25%">
|
||||
|
||||
### 🤖 **Agents**
|
||||
<h2>14</h2>
|
||||
|
||||
**AI Specialists**
|
||||
|
||||
`@agent-architect`
|
||||
`@agent-security`
|
||||
`@agent-frontend`
|
||||
`@agent-backend`
|
||||
|
||||
*Domain expertise*
|
||||
|
||||
</td>
|
||||
<td align="center" width="25%">
|
||||
|
||||
### 🎯 **Modes**
|
||||
<h2>6</h2>
|
||||
|
||||
**Behavioral Modes**
|
||||
|
||||
Brainstorming
|
||||
Introspection
|
||||
Orchestration
|
||||
Task Management
|
||||
|
||||
*Context adaptation*
|
||||
|
||||
</td>
|
||||
<td align="center" width="25%">
|
||||
|
||||
### 🔌 **MCP**
|
||||
<h2>6</h2>
|
||||
|
||||
**Server Integration**
|
||||
|
||||
Context7 (docs)
|
||||
Sequential (analysis)
|
||||
Magic (UI)
|
||||
Playwright (testing)
|
||||
|
||||
*Enhanced tools*
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📚 **Workflow Patterns**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Complete Development Lifecycle**
|
||||
|
||||
</div>
|
||||
|
||||
### **🌟 First Project Session**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Step</th>
|
||||
<th>Command</th>
|
||||
<th>What Happens</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>1. Discovery</b></td>
|
||||
<td><code>/sc:brainstorm "e-commerce app"</code></td>
|
||||
<td>Interactive requirements exploration</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>2. Load Context</b></td>
|
||||
<td><code>/sc:load src/</code></td>
|
||||
<td>Import existing project structure</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>3. Analysis</b></td>
|
||||
<td><code>/sc:analyze --focus architecture</code></td>
|
||||
<td>Deep architectural review</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>4. Planning</b></td>
|
||||
<td><code>/sc:workflow "payment integration"</code></td>
|
||||
<td>Generate implementation roadmap</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>5. Implementation</b></td>
|
||||
<td><code>/sc:implement "Stripe checkout"</code></td>
|
||||
<td>Build with best practices</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>6. Validation</b></td>
|
||||
<td><code>/sc:test --coverage</code></td>
|
||||
<td>Comprehensive testing</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>7. Save Session</b></td>
|
||||
<td><code>/sc:save "payment-complete"</code></td>
|
||||
<td>Persist for next session</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### **🎨 Domain-Specific Workflows**
|
||||
|
||||
<div align="center">
|
||||
|
||||
| Domain | Trigger | Specialist Activation | MCP Server |
|
||||
|--------|---------|----------------------|------------|
|
||||
| **Frontend** | UI component request | `@agent-frontend` | Magic |
|
||||
| **Backend** | API endpoint creation | `@agent-backend` | Sequential |
|
||||
| **Security** | Auth implementation | `@agent-security` | Context7 |
|
||||
| **Testing** | E2E test scenarios | `@agent-qa` | Playwright |
|
||||
| **DevOps** | Deployment setup | `@agent-devops` | Morphllm |
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **When to Use**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **SuperClaude vs Standard Claude Code**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th width="50%">✅ Use SuperClaude</th>
|
||||
<th width="50%">💭 Use Standard Claude</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">
|
||||
|
||||
**Perfect for:**
|
||||
- 🏗️ Building complete software projects
|
||||
- 📊 Systematic workflows with quality gates
|
||||
- 🔄 Complex, multi-component systems
|
||||
- 💾 Long-term projects needing persistence
|
||||
- 👥 Team collaboration with standards
|
||||
- 🎯 Domain-specific expertise needs
|
||||
|
||||
**Examples:**
|
||||
- "Build a full-stack application"
|
||||
- "Implement secure authentication"
|
||||
- "Refactor legacy codebase"
|
||||
- "Create comprehensive test suite"
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
**Better for:**
|
||||
- 💡 Simple questions or explanations
|
||||
- ⚡ One-off coding tasks
|
||||
- 📚 Learning programming concepts
|
||||
- 🧪 Quick prototypes or experiments
|
||||
- 🔍 Code snippet generation
|
||||
- ❓ General programming help
|
||||
|
||||
**Examples:**
|
||||
- "Explain how async/await works"
|
||||
- "Write a sorting function"
|
||||
- "Debug this error message"
|
||||
- "Convert this loop to functional"
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🎓 **Learning Path**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Your 4-Week Journey to Mastery**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Week</th>
|
||||
<th>Focus</th>
|
||||
<th>Skills</th>
|
||||
<th>Milestone</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><b>1</b><br/>🌱</td>
|
||||
<td><b>Core Commands</b></td>
|
||||
<td>
|
||||
• <code>/sc:brainstorm</code><br/>
|
||||
• <code>/sc:analyze</code><br/>
|
||||
• <code>/sc:implement</code>
|
||||
</td>
|
||||
<td>Complete first project</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><b>2</b><br/>🌿</td>
|
||||
<td><b>Behavioral Modes</b></td>
|
||||
<td>
|
||||
• Mode combinations<br/>
|
||||
• Flag usage<br/>
|
||||
• Context optimization
|
||||
</td>
|
||||
<td>Optimize workflows</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><b>3</b><br/>🌿</td>
|
||||
<td><b>MCP Servers</b></td>
|
||||
<td>
|
||||
• Server configuration<br/>
|
||||
• Tool integration<br/>
|
||||
• Enhanced capabilities
|
||||
</td>
|
||||
<td>Full tool utilization</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><b>4</b><br/>🌲</td>
|
||||
<td><b>Advanced Patterns</b></td>
|
||||
<td>
|
||||
• Custom workflows<br/>
|
||||
• Session management<br/>
|
||||
• Team patterns
|
||||
</td>
|
||||
<td>Framework mastery</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 💡 **Key Insights**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Understanding SuperClaude's Value**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="33%" align="center">
|
||||
|
||||
### 🧠 **Not Software**
|
||||
**It's a Framework**
|
||||
|
||||
SuperClaude is behavioral configuration, not standalone software. Everything runs through Claude Code.
|
||||
|
||||
</td>
|
||||
<td width="33%" align="center">
|
||||
|
||||
### 🔄 **Systematic**
|
||||
**Not Ad-hoc**
|
||||
|
||||
Transforms random requests into structured workflows with quality gates and validation.
|
||||
|
||||
</td>
|
||||
<td width="33%" align="center">
|
||||
|
||||
### 🚀 **Progressive**
|
||||
**Not Complex**
|
||||
|
||||
Start simple with basic commands. Complexity emerges naturally as needed.
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📖 **Next Steps**
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **Continue Your Learning Journey**
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>🌱 Beginner</th>
|
||||
<th>🌿 Intermediate</th>
|
||||
<th>🌲 Advanced</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">
|
||||
|
||||
**First Week:**
|
||||
- [Installation Guide](installation.md)
|
||||
- [Commands Reference](../User-Guide/commands.md)
|
||||
- [Examples Cookbook](../Reference/examples-cookbook.md)
|
||||
|
||||
Start with `/sc:brainstorm`
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
**Growing Skills:**
|
||||
- [Behavioral Modes](../User-Guide/modes.md)
|
||||
- [Agents Guide](../User-Guide/agents.md)
|
||||
- [Session Management](../User-Guide/session-management.md)
|
||||
|
||||
Explore mode combinations
|
||||
|
||||
</td>
|
||||
<td valign="top">
|
||||
|
||||
**Expert Usage:**
|
||||
- [MCP Servers](../User-Guide/mcp-servers.md)
|
||||
- [Technical Architecture](../Developer-Guide/technical-architecture.md)
|
||||
- [Contributing](../Developer-Guide/contributing-code.md)
|
||||
|
||||
Create custom workflows
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p align="center">
|
||||
<a href="../User-Guide/commands.md">
|
||||
<img src="https://img.shields.io/badge/📚_Explore-All_21_Commands-blue?style=for-the-badge" alt="Commands">
|
||||
</a>
|
||||
<a href="../Reference/examples-cookbook.md">
|
||||
<img src="https://img.shields.io/badge/🍳_Try-Real_Examples-green?style=for-the-badge" alt="Examples">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
### **🎉 Ready to Transform Your Development Workflow?**
|
||||
|
||||
<p align="center">
|
||||
<b>Start now with</b> <code>/sc:brainstorm</code> <b>in Claude Code!</b>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<sub>SuperClaude v4.1.5 - Context Engineering for Claude Code</sub>
|
||||
</p>
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user