SuperClaude Framework

A config-first meta-framework for Claude Code that provides 35 specialized agent personas (16 core + 12 traits + 7 extensions), 14 structured commands, 30 skills, and comprehensive MCP integration with quality-driven iterative workflows.

SuperClaude transforms Claude Code into a powerful development platform with specialized agent prompts, signal-based loop orchestration, and multi-model consensus capabilities. The core interface is markdown and YAML configuration files, with a Python orchestration layer for advanced workflows including quality gates, termination detection, and PAL MCP integration.

---

Table of Contents

• Overview
• Key Features
• Architecture
• Core Orchestration Layer
• Core API Reference
• Installation
• Quick Start
• Agent System
• Command System
• Loop Orchestration
• MCP Integrations
• Skills System
• Quality System
• Quality Gates
• Metrics System
• Type System
• Configuration
• Directory Structure
• Creating Custom Agents
• Contributing

---

Overview

SuperClaude is a meta-prompt framework that enhances Claude Code with:

• 35 Specialized Agents: 16 core + 12 composable traits + 7 domain extensions (tiered architecture)
• 30 Active Skills: 8 agent personas + 19 command workflows + 3 utility skills (plus 106 deprecated)
• 14 Structured Commands: analyze, implement, test, design, document, and more
• 6 Framework Modes: normal, brainstorming, introspection, task_management, token_efficiency, orchestration
• MCP Integration: PAL (11 tools), Rube (500+ apps via Composio, including web search)
• Quality Gates: KISS validator, Purity validator, and iterative quality loop
• Core Orchestration: ~3,200 lines Python for loop management, PAL integration, and skill learning
• Signal-Based Architecture: Structured communication between components
• Metrics System: Callback-based operational metrics with Prometheus/StatsD integration

---

Key Features

Config-First Hybrid Architecture

SuperClaude v7.0.0 is a config-first hybrid framework:

• Markdown Agent Personas: Each agent is a self-contained markdown file with YAML frontmatter
• YAML Configuration: 6 configuration files for agents, commands, quality, models, MCP, and framework settings
• Python Orchestration: Loop orchestrator, quality assessment, PAL integration, and skill learning
• Portable: Works with any Claude Code instance
• Extensible: Add agents by creating markdown files

Why Config-First Hybrid?

| Benefit | Description | |---------|-------------| | Simplicity | Core interface is markdown/YAML files | | Portability | Works with any Claude Code instance | | Extensibility | Add agents by creating markdown files | | Maintainability | Prompts are easy to refine and version | | Version Control | Easy to diff and review prompt changes | | Advanced Workflows | Python orchestration for quality gates and loop control | | Safety | Hard limits on iterations, termination detection |

Tiered Agent Architecture

35 agents organized in a tiered system for composable expertise:

| Tier | Count | Purpose | Examples | |------|-------|---------|----------| | Core | 16 | High-priority generalists | general-purpose, root-cause-analyst, refactoring-expert, security-engineer | | Traits | 12 | Composable modifiers | security-first, performance-first, test-driven, minimal-changes, solid-aligned, crash-resilient, mcp-pal-enabled, mcp-rube-enabled | | Extensions | 7 | Domain specialists | typescript-expert, golang-expert, rust-expert, react-specialist, kubernetes-specialist, data-engineer, ml-engineer |

Why Tiered? The v7 architecture provides a lean, composable system. Core agents handle most tasks, traits modify behavior (e.g., @security-engineer +security-first), and extensions provide deep domain expertise when needed.

Command System

14 structured commands with consistent patterns:

/sc:analyze    - Static analysis, security review, performance bottlenecks
/sc:implement  - Feature implementation with quality gates and loop support
/sc:test       - Test generation, coverage analysis, quality reporting
/sc:design     - Architecture and system design with ADRs
/sc:document   - Documentation generation and maintenance
/sc:brainstorm - Creative ideation and exploration
/sc:explain    - Educational explanations and learning
/sc:improve    - Code improvement, refactoring, optimization
/sc:build      - Build system and compilation workflows
/sc:git        - Git operations, smart commits, branch management
/sc:workflow   - Multi-step task orchestration
/sc:estimate   - Effort estimation and planning
/sc:cicd-setup - CI/CD workflow and pre-commit generation
/sc:pr-fix     - PR fix workflow and issue resolution

---

Architecture

How SuperClaude Works

flowchart TB
    subgraph User["User Layer"]
        REQ["User Request<br/>/sc:implement --loop"]
    end

    subgraph Runtime["Claude Code Runtime"]
        CLAUDE["CLAUDE.md<br/>Master System Prompt"]
        SELECT["Agent Selection<br/>Semantic Matching + Weights"]
        EXEC["Task Execution"]
    end

    subgraph Config["Configuration Layer"]
        AGENTS[("agents/<br/>16 core + 10 traits + 7 ext")]
        COMMANDS[("commands/<br/>14 templates")]
        SKILLS[(".claude/skills/<br/>28 skills")]
        YAML[("config/<br/>6 YAML files")]
    end

    subgraph Core["Core Orchestration (Python)"]
        direction TB
        LOOP["LoopOrchestrator<br/>Max 5 iterations"]
        QUALITY["QualityAssessor<br/>9 dimensions"]
        TERM["Termination Detection<br/>8 conditions"]
        PALINT["PAL Integration<br/>Signal generation"]
        LEARN["Skill Learning<br/>Pattern extraction"]
    end

    subgraph MCP["MCP Integrations"]
        PAL["PAL MCP<br/>11 tools"]
        RUBE["Rube MCP<br/>500+ apps"]
    end

    REQ --> CLAUDE
    CLAUDE --> SELECT
    SELECT --> AGENTS
    SELECT --> COMMANDS
    SELECT --> EXEC
    EXEC --> SKILLS
    EXEC <--> Core
    LOOP --> QUALITY
    QUALITY --> TERM
    TERM --> PALINT
    PALINT <--> PAL
    EXEC <--> RUBE
    Config --> Runtime

    style User fill:#e8f5e9
    style Runtime fill:#e3f2fd
    style Config fill:#fff3e0
    style Core fill:#fce4ec
    style MCP fill:#f3e5f5

File-Based Configuration

SuperClaude uses a layered file-based architecture:

1. CLAUDE.md - Master system prompt loaded by Claude Code
2. agents/index.yaml - Agent registry with triggers, categories, and selection weights
3. agents/core/*.md - 16 core agent persona prompts
4. agents/traits/*.md - 10 composable behavior modifier prompts
5. agents/extensions/*.md - 7 domain specialist prompts
6. commands/index.yaml - Command registry with flags and aliases
7. commands/*.md - 14 command templates
8. config/*.yaml - 6 configuration files
9. core/*.py - Python orchestration modules
10. mcp/*.md - MCP integration guides
11. .claude/skills/ - 28 Claude Code skills

---

Core Orchestration Layer

SuperClaude v7.0.0 includes a Python orchestration layer in core/ for advanced workflows:

Modules

| Module | Lines | Purpose | |--------|-------|---------| | loop_orchestrator.py | ~480 | Manages iterative improvement with quality gates | | quality_assessment.py | ~200 | 9-dimension quality scoring with evidence collection | | pal_integration.py | ~250 | PAL MCP signal generation (review, debug, validation) | | termination.py | ~100 | Termination condition detection (oscillation, stagnation) | | types.py | 159 | Core type definitions (TerminationReason, LoopConfig, etc.) | | skill_learning_integration.py | ~300 | Skill extraction from successful executions | | skill_persistence.py | ~200 | Skill storage, retrieval, and promotion |

LoopOrchestrator

The LoopOrchestrator class manages the --loop flag behavior:

stateDiagram-v2
    [*] --> Initialize

    state "Loop Execution" as Loop {
        [*] --> ExecuteSkill
        ExecuteSkill --> CollectEvidence
        CollectEvidence --> AssessQuality
        AssessQuality --> CheckThreshold

        state CheckThreshold <<choice>>
        CheckThreshold --> Success: score >= 70
        CheckThreshold --> CheckTermination: score < 70

        state CheckTermination <<choice>>
        CheckTermination --> Oscillation: alternating scores
        CheckTermination --> Stagnation: flat scores (var < 2.0)
        CheckTermination --> Insufficient: improvement < 5 pts
        CheckTermination --> MaxIterations: iteration >= 5
        CheckTermination --> Continue: OK to iterate

        Continue --> PALReview: Generate signal
        PALReview --> PrepareNext
        PrepareNext --> ExecuteSkill
    }

    Initialize --> Loop

    Success --> FinalValidation: PAL final signal
    Oscillation --> DebugSignal: PAL debug signal
    Stagnation --> DebugSignal
    Insufficient --> [*]
    MaxIterations --> [*]
    FinalValidation --> [*]
    DebugSignal --> [*]

    no