CLAUDE.md · SuperClaude-Org/SuperClaude_Framework

Sections

1. 🐍 Python Environment Rules
2. 📂 Project Structure
3. 🔧 Development Workflow
4. 📦 Core Architecture
5. 🧪 Testing with PM Agent
6. 🌿 Git Workflow
7. 📝 Key Documentation Files
8. 💡 Core Development Principles
9. 🔧 MCP Server Integration
10. 🚀 Development & Installation
11. 📊 Package Information
12. 🔌 Claude Code Native Features (for developers)

First lines (shown under the repo's MIT license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 🐍 Python Environment Rules

**CRITICAL**: This project uses **UV** for all Python operations. Never use `python -m`, `pip install`, or `python script.py` directly.

### Required Commands

```bash
# All Python operations must use UV
uv run pytest                    # Run tests
uv run pytest tests/pm_agent/   # Run specific tests
uv pip install package           # Install dependencies
uv run python script.py          # Execute scripts
```

## 📂 Project Structure

**Current v4.3.0 Architecture**: Python package with 30 commands, 20 agents, 7 modes

```
# Claude Code Configuration (v4.3.0)
# Installed via `superclaude install` to user's home directory
~/.claude/
├── settings.json
├── commands/sc/         # 30 slash commands (/sc:research, /sc:implement, etc.)
│   ├── pm.md
│   ├── research.md
│   ├── implement.md
│   └── ... (30 total)
├── agents/              # 20 domain-specialist agents (@pm-agent, @system-architect, etc.)
│   ├── pm-agent.md
│   ├── system-architect.md
│   └── ... (20 total)
└── skills/              # Skills (confidence-check, etc.)

# Python Package
src/superclaude/
├── __init__.py          # Public API: ConfidenceChecker, SelfCheckProtocol, ReflexionPattern
├── pytest_plugin.py     # Auto-loaded pytest integration (5 fixtures, 9 markers)
├── pm_agent/            # confidence.py, self_check.py, reflexion.py, token_budget.py
├── execution/           # parallel.py, reflection.py, self_correction.py
├── cli/                 # main.py, doctor.py, install_commands.py, install_mcp.py, install_skill.py
├── commands/            # 30 slash command definitions (.md files)
├── agents/              # 20 agent definitions (.md files)
├── modes/               # 7 behavioral modes (.md files)
├── skills/              # Installable skills (confidence-check, etc.)
├── hooks/               # Claude Code hook definitions
├── mcp/                 # MCP server configurations (10 servers)
└── core/                # Core utilities

# Project Files
tests/                   # Python test suite (136 tests)
├── unit/                # Unit tests (auto-marked @pytest.mark.unit)
└── integration/         # Integration tests (auto-marked @pytest.mark.integration)
docs/                    # Documentation
scripts/                 # Analysis tools (workflow metrics, A/B testing)
plugins/                 # Exported plugin artefacts for distribution
PLANNING.md              # Architecture, absolute rules
TASK.md                  # Current tasks
KNOWLEDGE.md             # Accumulated insights
```

### Claude Code Integration Points

SuperClaude integrates with Claude Code through these mechanisms:
- **Slash Commands**: 30 commands installed to `~/.claude/commands/sc/` (e.g., `/sc:pm`, `/sc:research`)
- **Agents**: 20 agents installed to `~/.claude/agents/` (e.g., `@pm-agent`, `@system-architect`)
- **Skills**: Installed to `~/.claude/skills/` (e.g., confidence-check)
- **Hooks**: Session lifecycle hooks in `src/superclaude/hooks/`
- **Settings**: Project settings in `.claude/settings.json`
- **Pytest Plugin**: Auto-loaded via entry point, provides fixtures and markers
- **MCP Servers**: 8+ servers configurable via `superclaude mcp`

## 🔧 Development Workflow

### Essential Commands

```bash
# Setup
make dev              # Install in editable mode with dev dependencies
make verify           # Verify installation (package, plugin, health)

# Testing
make test             # Run full test suite
uv run pytest tests/pm_agent/ -v              # Run specific directory
uv run pytest tests/test_file.py -v           # Run specific file
uv run pytest -m confidence_check             # Run by marker
uv run pytest --cov=superclaude               # With coverage

# Code Quality
make lint             # Run ruff linter
make format           # Format code with ruff
make doctor           # Health check diagnostics

# MCP Servers
superclaude mcp                              # Interactive install (gateway default)
superclaude mcp --list                       # List available servers
superclaude mcp --servers airis-mcp-gateway  # Install AIRIS Gateway (recommended)
superclaude mcp --servers tavily context7    # Install individual servers

# Plugin Packaging
make build-plugin            # Build plugin artefacts into dist/
make sync-plugin-repo        # Sync artefacts into ../SuperClaude_Plugin

# Maintenance
make clean            # Remove build artifacts
```

## 📦 Core Architecture

### Pytest Plugin (Auto-loaded)

Registered via `pyproject.toml` entry point, automatically available after installation.

**Fixtures**: `confidence_checker`, `self_check_protocol`, `reflexion_pattern`, `token_budget`, `pm_context`

**Auto-markers**:
- Tests in `/unit/` → `@pytest.mark.unit`
- Tests in `/integration/` → `@pytest.mark.integration`

**Custom markers**: `@pytest.mark.confidence_check`, `@pytest.mark.self_check`, `@pytest.mark.reflexion`

### PM Agent - Three Core Patterns

**1. ConfidenceChecker** (src/superclaude/pm_agent/confidence.py)
- Pre-execution confidence assessment: ≥90% required, 70-89% present alternatives, <70% ask questions
- Prevents wrong-direction work, ROI: 25-250x token savings

**2. SelfCheckProtocol** (src/superclaude/pm_agent/self_check.py)
- Post-implementation evidence-based validation
- No speculation - verify with tests/docs

**3. ReflexionPattern** (src/superclaude/pm_agent/reflexion.py)
- Error learning and prevention
- Cross-session pattern matching

### Parallel Execution

**Wave → Checkpoint → Wave pattern** (src/superclaude/execution/parallel.py):
- 3.5x faster than sequential execution
- Automatic dependency analysis
- Example: [Read files in parallel] → Analyze → [Edit files in parallel]

### Slash Commands, Agents & Modes (v4.3.0)

- Install via: `pipx install superclaude && superclaude install`
- **30 Commands** installed to `~/.claude/commands/sc/` (e.g., `/sc:pm`, `/sc:research`, `/sc:implement`)
- **20 Agents** installed to `~/.claude/agents/` (e.g., `@pm-agent`, `@system-architect`, `@deep-research`)
- **7 Behavioral Modes**: Brainstorming, Business Panel, Deep Research, Introspection, Orchestration, Task Management, Token Efficiency
- **Skills**: Installable to `~/.claude/skills/` (e.g., confidence-check)

> **Note**: TypeScript plugin system planned for v5.0 ([#419](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues/419))

## 🧪 Testing with PM Agent

### Example Test with Markers