237 lines
7.6 KiB
Markdown
237 lines
7.6 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Quick Reference
|
||
|
|
|
||
|
|
### Common Commands
|
||
|
|
|
||
|
|
**Installation & Setup:**
|
||
|
|
```bash
|
||
|
|
# Install in development mode
|
||
|
|
uv sync
|
||
|
|
|
||
|
|
# Run the installer (various options)
|
||
|
|
SuperClaude install # Quick setup (recommended)
|
||
|
|
SuperClaude install --interactive # Interactive component selection
|
||
|
|
SuperClaude install --minimal # Minimal installation
|
||
|
|
SuperClaude install --profile developer # Full developer setup
|
||
|
|
SuperClaude install --dry-run # Preview changes without applying
|
||
|
|
|
||
|
|
# Alternative installation methods
|
||
|
|
python3 -m SuperClaude install
|
||
|
|
SuperClaude update --verbose
|
||
|
|
SuperClaude backup --create
|
||
|
|
SuperClaude uninstall --yes
|
||
|
|
```
|
||
|
|
|
||
|
|
**Package Management:**
|
||
|
|
```bash
|
||
|
|
# From PyPI (recommended)
|
||
|
|
uv add SuperClaude
|
||
|
|
|
||
|
|
# From source
|
||
|
|
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||
|
|
cd SuperClaude_Framework
|
||
|
|
uv sync
|
||
|
|
```
|
||
|
|
|
||
|
|
**Testing (Limited):**
|
||
|
|
```bash
|
||
|
|
# Note: No formal test suite exists yet
|
||
|
|
# Referenced in docs but not implemented:
|
||
|
|
python Tests/comprehensive_test.py
|
||
|
|
python Tests/task_management_test.py
|
||
|
|
python Tests/performance_test_suite.py
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture Overview
|
||
|
|
|
||
|
|
SuperClaude Framework v3.0 is a **Python-based enhancement system for Claude Code** that extends AI-assisted development through specialized commands, personas, and MCP server integration.
|
||
|
|
|
||
|
|
### Core Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
SuperClaude_Framework/
|
||
|
|
├── SuperClaude/ # Framework files (installed to ~/.claude/)
|
||
|
|
│ ├── Core/ # 9 documentation files defining behavior
|
||
|
|
│ │ ├── CLAUDE.md # Main entry point
|
||
|
|
│ │ ├── COMMANDS.md # Command execution framework
|
||
|
|
│ │ ├── FLAGS.md # Flag reference
|
||
|
|
│ │ ├── PERSONAS.md # 11 specialized personas
|
||
|
|
│ │ ├── MCP.md # MCP server integration
|
||
|
|
│ │ ├── ORCHESTRATOR.md # Intelligent routing system
|
||
|
|
│ │ PRINCIPLES.md # Core principles
|
||
|
|
│ │ RULES.md # Operational rules
|
||
|
|
│ │ MODES.md # Operational modes
|
||
|
|
│ ├── Commands/ # 16 markdown-based slash commands
|
||
|
|
│ │ ├── analyze.md
|
||
|
|
│ │ ├── build.md
|
||
|
|
│ │ ├── implement.md # NEW in v3 (replaces v2 /build for features)
|
||
|
|
│ │ └── ...
|
||
|
|
│ └── Hooks/ # Removed in v3, returning in v4
|
||
|
|
│
|
||
|
|
├── setup/ # Installation system
|
||
|
|
│ ├── base/ # Core installer infrastructure
|
||
|
|
│ ├── components/ # Component installers
|
||
|
|
│ ├── core/ # Registry and validation
|
||
|
|
│ ├── managers/ # Config, file, settings managers
|
||
|
|
│ ├── operations/ # Install, update, uninstall, backup
|
||
|
|
│ └── utils/ # UI, logging, security utilities
|
||
|
|
│
|
||
|
|
├── config/ # Configuration
|
||
|
|
│ ├── features.json # Feature definitions
|
||
|
|
│ └── requirements.json # System requirements
|
||
|
|
│
|
||
|
|
├── profiles/ # Installation profiles
|
||
|
|
│ ├── quick.json # Quick setup
|
||
|
|
│ ├── minimal.json # Minimal installation
|
||
|
|
│ └── developer.json # Full developer setup
|
||
|
|
│
|
||
|
|
├── Docs/ # User documentation (5 guides)
|
||
|
|
└── SuperClaude/__main__.py # Unified CLI entry point
|
||
|
|
```
|
||
|
|
|
||
|
|
### Key Components
|
||
|
|
|
||
|
|
**1. Installation System (`setup/` module)**
|
||
|
|
- Modular installer with component-based installation
|
||
|
|
- Entry point: `SuperClaude/__main__.py` (254 lines)
|
||
|
|
- Operations: install, update, uninstall, backup
|
||
|
|
- Profiles: quick, minimal, developer
|
||
|
|
|
||
|
|
**2. Framework Files (`SuperClaude/` directory)**
|
||
|
|
- 9 core documentation files guide Claude's behavior
|
||
|
|
- 16 slash command definitions in markdown
|
||
|
|
- Installed to `~/.claude/` for Claude Code integration
|
||
|
|
|
||
|
|
**3. MCP Integration**
|
||
|
|
- Context7: Documentation lookup
|
||
|
|
- Sequential: Complex analysis
|
||
|
|
- Magic: UI component generation
|
||
|
|
- Playwright: Browser automation
|
||
|
|
|
||
|
|
**4. Personas System**
|
||
|
|
- 11 specialized AI personas: architect, frontend, backend, analyzer, security, scribe, and 5 others
|
||
|
|
- Smart routing attempts to pick the right expert
|
||
|
|
|
||
|
|
## Development Workflow
|
||
|
|
|
||
|
|
### Development Setup
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Clone and setup
|
||
|
|
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
|
||
|
|
cd SuperClaude_Framework
|
||
|
|
uv sync
|
||
|
|
|
||
|
|
# Install in development mode
|
||
|
|
SuperClaude install --profile developer
|
||
|
|
```
|
||
|
|
|
||
|
|
### Key Development Areas
|
||
|
|
|
||
|
|
**Framework Files** - Modify `SuperClaude/Core/` and `SuperClaude/Commands/` for:
|
||
|
|
- Documentation and behavior changes
|
||
|
|
- Command definitions and updates
|
||
|
|
- Persona configurations
|
||
|
|
|
||
|
|
**Installation System** - Work in `setup/` module for:
|
||
|
|
- Installer improvements
|
||
|
|
- Component management
|
||
|
|
- Profile adjustments
|
||
|
|
|
||
|
|
**Configuration** - Update files in:
|
||
|
|
- `config/requirements.json` - System requirements
|
||
|
|
- `config/features.json` - Feature definitions
|
||
|
|
- `profiles/*.json` - Installation profiles
|
||
|
|
|
||
|
|
### Code Organization Patterns
|
||
|
|
|
||
|
|
- **Modular Architecture:** Separate concerns across modules
|
||
|
|
- **Documentation-Driven:** Markdown files define behavior
|
||
|
|
- **Component-Based:** Installation broken into discrete components
|
||
|
|
- **Profile-Driven:** Multiple installation profiles for different use cases
|
||
|
|
- **Error Handling:** Comprehensive error handling with fallbacks
|
||
|
|
|
||
|
|
## Important Notes
|
||
|
|
|
||
|
|
### v2 to v3 Migration
|
||
|
|
|
||
|
|
**Breaking Change:** The `/build` command changed!
|
||
|
|
- v2: `/build myFeature` = feature implementation
|
||
|
|
- v3: `/sc:build` = compilation/packaging only
|
||
|
|
- v3: `/sc:implement` = feature implementation (NEW!)
|
||
|
|
|
||
|
|
**Migration:** Replace `v2 /build myFeature` with `v3 /sc:implement myFeature`
|
||
|
|
|
||
|
|
### Known Issues
|
||
|
|
|
||
|
|
- This is an initial v3.0 release - expect bugs
|
||
|
|
- Hooks system removed (returning in v4)
|
||
|
|
- No formal test suite exists (referenced in docs but not implemented)
|
||
|
|
- No linting/formatting configuration
|
||
|
|
- MCP integration partially working
|
||
|
|
|
||
|
|
### Build System
|
||
|
|
|
||
|
|
- **Build Backend:** Hatchling (via pyproject.toml)
|
||
|
|
- **Package Manager:** uv (modern Python package manager)
|
||
|
|
- **Dependencies:** Minimal (only `setuptools>=45.0.0`)
|
||
|
|
- **Language:** Python 3.8+ (standard library focused)
|
||
|
|
|
||
|
|
## Important Documentation
|
||
|
|
|
||
|
|
- **README.md** (342 lines) - Main project documentation, installation guide
|
||
|
|
- **CONTRIBUTING.md** - Contribution guidelines, code standards
|
||
|
|
- **Docs/superclaude-user-guide.md** - Complete user overview
|
||
|
|
- **Docs/commands-guide.md** - All 16 slash commands explained
|
||
|
|
- **Docs/flags-guide.md** - Command flags and options
|
||
|
|
- **Docs/installation-guide.md** - Detailed installation instructions
|
||
|
|
|
||
|
|
## Daily Development Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Quick installation test
|
||
|
|
SuperClaude install --dry-run
|
||
|
|
|
||
|
|
# Update installation
|
||
|
|
SuperClaude update --verbose
|
||
|
|
|
||
|
|
# Create backup before changes
|
||
|
|
SuperClaude backup --create
|
||
|
|
|
||
|
|
# View all installation options
|
||
|
|
SuperClaude install --help
|
||
|
|
|
||
|
|
# Run installer with specific profile
|
||
|
|
SuperClaude install --profile developer
|
||
|
|
```
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
After installation, users can customize via:
|
||
|
|
- `~/.claude/settings.json` - Main configuration
|
||
|
|
- `~/.claude/*.md` - Framework behavior files
|
||
|
|
|
||
|
|
## Future Roadmap (v4)
|
||
|
|
|
||
|
|
- Hooks system redesign and return
|
||
|
|
- Enhanced MCP suite
|
||
|
|
- Performance improvements
|
||
|
|
- Additional personas
|
||
|
|
- Cross-CLI support
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
**Installation Issues:**
|
||
|
|
- Check Python 3.8+ is installed
|
||
|
|
- Ensure `~/.claude/` directory permissions
|
||
|
|
- Run with `--verbose` flag for detailed output
|
||
|
|
- Backup and clean install if upgrading from v2
|
||
|
|
|
||
|
|
**Development Issues:**
|
||
|
|
- Framework files are in `SuperClaude/` (installed to `~/.claude/`)
|
||
|
|
- Installation system is in `setup/` module
|
||
|
|
- Entry point is `SuperClaude/__main__.py`
|