# 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`