SuperClaude Framework

A config-first meta-framework for Claude Code that provides 31 specialized agent personas (11 core + 12 traits + 8 extensions), 27 structured commands, 38 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.

Overview
Key Features
Architecture
Core Orchestration Layer
Core API Reference
Installation
Quick Start
Dashboard
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:

31 Specialized Agents: 11 core + 12 composable traits + 8 domain extensions (tiered architecture)
38 Active Skills: 8 agent personas + 27 command workflows + 3 utility skills
27 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, Purity, SOLID, and Let It Crash validators with iterative quality loop
Core Orchestration: ~2,800 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

31 agents organized in a tiered system for composable expertise:

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

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

27 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 execution, coverage analysis, and test generation
/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:readme       - Auto-update README.md from git diff with PAL consensus
/sc:pr-fix       - Create PR and iteratively fix CI failures
/sc:pr-check     - Pre-PR local CI validation with auto-fix
/sc:log-fix      - Log analysis and iterative bug fixing
/sc:e2e          - E2E testing (Playwright, Cypress, Selenium)
/sc:tdd          - Test-driven development with Red-Green-Refactor
/sc:principles   - KISS, Purity, SOLID, Let It Crash validation
/sc:worktree     - Git worktree management for parallel development
/sc:mcp          - MCP orchestration hub (PAL + Rube)
/sc:code-review  - Multi-model consensus code review
/sc:research     - Deep research with web search + consensus
/sc:eda          - Exploratory data analysis and visualization
/sc:evaluate     - LLM pipeline evaluation with judge scoring
/sc:push         - Multi-remote git push with selective filtering

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/>11 core + 12 traits + 8 ext")]
        COMMANDS[("commands/<br/>16 templates")]
        SKILLS[(".claude/skills/<br/>38 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/>5 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:

CLAUDE.md - Master system prompt loaded by Claude Code
agents/index.yaml - Agent registry with triggers, categories, and selection weights
agents/core/*.md - 11 core agent persona prompts
agents/traits/*.md - 12 composable behavior modifier prompts
agents/extensions/*.md - 8 domain specialist prompts
commands/index.yaml - Command registry with flags and aliases
commands/*.md - 16 command templates
config/*.yaml - 6 configuration files
core/*.py - Python orchestration modules
mcp/*.md - MCP integration guides
.claude/skills/ - 38 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`	~410	Manages iterative improvement with quality gates
`quality_assessment.py`	~265	9-dimension quality scoring with evidence collection
`pal_integration.py`	~175	PAL MCP signal generation (review, debug, validation)
`types.py`	~150	Core type definitions (TerminationReason, LoopConfig, etc.)
`metrics.py`	~225	Callback-based metrics protocol and emitters
`skill_learning_integration.py`	~550	Skill extraction from successful executions
`skill_persistence.py`	~980	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 --> MaxIterations: iteration >= max
        CheckTermination --> Timeout: wall-clock exceeded
        CheckTermination --> Error: skill execution failure
        CheckTermination --> Continue: OK to iterate

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

    Initialize --> Loop

    Success --> FinalValidation: PAL final signal
    MaxIterations --> [*]
    Timeout --> [*]
    Error --> [*]
    FinalValidation --> [*]

    note right of Initialize
        Triggered by /sc&#58;implement --loop
    end note

Key Features:

Safety: Hard maximum of 5 iterations (cannot be overridden via hard_max_iterations)
Quality-Driven: Stops when score >= 70 (configurable threshold)
PAL Integration: Generates review signals within loop for external validation
Signal-Based: Communicates with Claude Code via structured signals
Evidence Collection: Tracks changes, tests, lint results, and file modifications

Signal Architecture

The orchestrator uses structured signals for component communication:

# Skill invocation signal
{
    "action": "execute_skill",
    "skill": "sc-implement",
    "parameters": {
        "task": "description",
        "improvements_needed": [...],
        "iteration": 2,
        "focus": "remediation"  # "implementation" for iter 0
    },
    "collect": ["changes", "tests", "lint", "changed_files"],
    "context": {...}
}

Core API Reference

Complete API documentation for the SuperClaude Python orchestration layer (core/ module).

Module Exports

from core import (
    # Types
    TerminationReason,      # Enum: 5 loop termination conditions
    LoopConfig,             # Dataclass: Loop configuration
    LoopResult,             # Dataclass: Final loop result
    IterationResult,        # Dataclass: Single iteration result
    QualityAssessment,      # Dataclass: Quality score + improvements
    # Classes
    QualityAssessor,        # Quality scoring wrapper
    PALReviewSignal,        # PAL MCP signal generator
    LoopOrchestrator,       # Main loop controller
)

LoopOrchestrator

The main controller for --loop functionality.

class LoopOrchestrator:
    """
    Lightweight agentic loop orchestrator.

    Thread Safety: NOT thread-safe. Create new instance per task/thread.
    """

    def __init__(
        self,
        config: Optional[LoopConfig] = None,
        logger: Optional[logging.Logger] = None,
        metrics_emitter: Optional[MetricsEmitter] = None,
    ) -> None:
        """
        Initialize the loop orchestrator.

        Args:
            config: Loop configuration (defaults to LoopConfig())
            logger: Logger instance for structured logging
            metrics_emitter: Callback for operational metrics
        """

    def run(
        self,
        initial_context: dict[str, Any],
        skill_invoker: Callable[[dict[str, Any]], dict[str, Any]],
    ) -> LoopResult:
        """
        Execute the agentic loop.

        Args:
            initial_context: Task context with:
                - task: Description of what to implement
                - improvements_needed: Initial improvements (optional)
                - changed_files: Already modified files (optional)
            skill_invoker: Function that invokes Skills via Claude Code
                Should return dict with: changes, tests, lint, changed_files

        Returns:
            LoopResult with final output, assessment, and history
        """

Usage Example:

from core import LoopOrchestrator, LoopConfig

config = LoopConfig(
    max_iterations=3,
    quality_threshold=70.0,
    pal_review_enabled=True,
)

orchestrator = LoopOrchestrator(config)

def my_skill_invoker(context):
    return {
        "changes": [...],
        "tests": {"ran": True, "passed": 10, "failed": 0},
        "lint": {"ran": True, "errors": 0},
        "changed_files": ["src/module.py"],
    }

result = orchestrator.run(
    initial_context={"task": "Implement user authentication"},
    skill_invoker=my_skill_invoker,
)

print(f"Final score: {result.final_assessment.overall_score}")
print(f"Termination: {result.termination_reason.value}")

QualityAssessor

Wraps evidence_gate.py for quality scoring.

class QualityAssessor:
    def __init__(self, threshold: float = 70.0) -> None
    def assess(self, context: dict[str, Any]) -> QualityAssessment

Scoring Breakdown (Fallback Mode):

Component	Points	Condition
File changes	30	Any changes detected
Tests executed	25	Tests ran
Tests passing	20	All tests pass
Lint clean	15	No lint errors
Coverage	10	80%+ coverage

PALReviewSignal

Generates signals for PAL MCP invocation.

class PALReviewSignal:
    TOOL_CODEREVIEW = "mcp__pal__codereview"
    TOOL_DEBUG = "mcp__pal__debug"
    TOOL_THINKDEEP = "mcp__pal__thinkdeep"
    TOOL_CONSENSUS = "mcp__pal__consensus"

    @staticmethod
    def generate_review_signal(
        iteration: int,
        changed_files: list[str],
        quality_assessment: QualityAssessment,
        model: str = "gpt-5",
        review_type: str = "auto",  # auto/quick/full
    ) -> dict[str, Any]

    @staticmethod
    def generate_debug_signal(
        iteration: int,
        termination_reason: str,
        score_history: list[float],
        model: str = "gpt-5",
    ) -> dict[str, Any]

    @staticmethod
    def generate_final_validation_signal(
        changed_files: list[str],
        quality_assessment: QualityAssessment,
        iteration_count: int,
        model: str = "gpt-5",
    ) -> dict[str, Any]

Helper Functions

# Create skill invocation signal
def create_skill_invoker_signal(context: dict[str, Any]) -> dict[str, Any]

# Merge PAL feedback into context
def incorporate_pal_feedback(
    context: dict[str, Any],
    pal_result: dict[str, Any],
) -> dict[str, Any]

# Convenience function for quality assessment
def assess_quality(
    context: dict[str, Any],
    threshold: float = 70.0
) -> QualityAssessment

Installation

Option 1: Clone Repository

git clone https://github.com/Tony363/SuperClaude.git
cd SuperClaude

Option 2: Add as Git Submodule

git submodule add https://github.com/Tony363/SuperClaude.git SuperClaude

Setup Claude Code

Add to your project's .claude/settings.json:

{
  "systemPromptFiles": ["SuperClaude/CLAUDE.md"]
}

Or copy CLAUDE.md to your project root.

Optional: Python Dependencies

For advanced workflows using the core orchestration layer:

pip install -e .

Quick Start

1. Basic Usage

Once configured, Claude Code automatically loads SuperClaude capabilities:

User: Help me debug this authentication issue
Claude: [Selects root-cause-analyst agent, applies debugging methodology]

2. Using Commands

User: /sc:analyze src/auth/
Claude: [Runs comprehensive static analysis, security review, quality assessment]

3. Specifying Agents

User: @python-expert Review this Flask application
Claude: [Uses Python expert persona with framework-specific knowledge]

4. Iterative Improvement

User: /sc:implement new user registration --loop
Claude: [Implements with quality gates, iterates until score >= 70 or max 5 iterations]

5. Using MCP Tools

With PAL MCP configured:

User: Use PAL to review this code
Claude: [Invokes mcp__pal__codereview for multi-model code review]

Dashboard

SuperClaude includes a native desktop dashboard for visualizing and controlling the agentic framework.

Features

Feature Inventory - Browse all 31 agents, 27 commands, 38 skills, and 6 behavioral modes
Live Monitor - Real-time execution tracking with event streaming, heartbeat indicator, and quality score visualization
Execution Control - Start, stop, pause, and resume executions with configurable parameters; expandable detail panel with 5 tabs (Run Instructions, Execution Log, Files Changed, Quality Breakdown, Execution Tree)
Execution Tree - Visual tree of iterations, tool calls, and subagent spawns built from streaming events
Diff Viewer - Inline diff display for Edit/Write tool invocations showing before/after changes
Historical Metrics - View past session data, event timelines, and performance trends

Quick Start

# Terminal 1: Start the daemon
cargo run -p superclaude-daemon

# Terminal 2: Launch the dashboard
cd crates/dashboard
cargo tauri dev

The dashboard window will open showing the Feature Inventory page. Navigate using the sidebar to access Monitor, Control, and History views.

Building for Production

cd crates/dashboard
cargo tauri build

# Output packages:
# - Debian/Ubuntu: target/release/bundle/deb/superclaude-dashboard_*.deb
# - Universal Linux: target/release/bundle/appimage/superclaude-dashboard_*.AppImage

System Requirements

OS: Linux (tested on Manjaro/Arch, Ubuntu 22.04+)
Dependencies: webkit2gtk-4.1, libappindicator-gtk3, librsvg
Runtime: SuperClaude daemon running on port 50051

See Dashboard README for detailed usage guide.

Agent System

Core Agents (11)

High-priority generalists for common tasks:

Agent	Triggers	Purpose
general-purpose	help, assist, general, requirement, spec	Versatile task handling, requirements analysis
root-cause-analyst	debug, bug, error, crash, broken, not working	Deep debugging and investigation
refactoring-expert	refactor, clean, improve, technical debt	Code quality improvement
technical-writer	document, docs, readme	Documentation generation
security-engineer	security, auth, vulnerability, authorization	Security analysis and hardening
performance-engineer	performance, optimize, slow, bottleneck	Performance optimization
quality-engineer	test, qa, coverage	Testing and quality assurance
software-architect	architecture, design, api, database, frontend, ui	System, backend, and frontend architecture
devops-architect	devops, ci/cd, kubernetes	Infrastructure automation
fullstack-developer	fullstack, end-to-end	Full-stack coordination
educator	learn, teach, tutorial, mentor, explain	Teaching, tutorials, and guided learning

Traits (12)

Composable behavior modifiers that can be combined with any agent:

Trait	Purpose	Example Usage
security-first	Prioritize security considerations	`@software-architect +security-first`
performance-first	Focus on optimization	`@python-expert +performance-first`
pedagogy-first	Include educational explanations	`@educator +pedagogy-first`
test-driven	Enforce TDD practices	`@fullstack-developer +test-driven`
minimal-changes	Reduce change scope	`@refactoring-expert +minimal-changes`
legacy-friendly	Support older systems	`@devops-architect +legacy-friendly`
cloud-native	Modern cloud patterns	`@software-architect +cloud-native`
rapid-prototype	Fast iteration	`@software-architect +rapid-prototype`
solid-aligned	Enforce SOLID design principles (SRP, OCP, LSP, ISP, DIP)	`@software-architect +solid-aligned`
crash-resilient	Enforce "Let It Crash" error handling philosophy	`@software-architect +crash-resilient`
mcp-pal-enabled	Enables PAL MCP tools (consensus, debug, codereview)	`@security-engineer +mcp-pal-enabled`
mcp-rube-enabled	Enables Rube MCP tools (500+ app integrations)	`@devops-architect +mcp-rube-enabled`

Extensions (8)

Domain-specialist agents for deep expertise:

Extension	Triggers	Specialty
typescript-expert	typescript, ts, angular	TypeScript ecosystem
golang-expert	go, golang	Go development
rust-expert	rust, cargo, wasm	Rust development
react-specialist	react, nextjs, hooks	React ecosystem
kubernetes-specialist	kubernetes, k8s, helm	Kubernetes orchestration
data-engineer	data, pipeline, etl	Data engineering
ml-engineer	ml, machine learning, model	Machine learning
python-expert	python, django, fastapi	Python development

Agent Selection Algorithm

Agents are selected using weighted semantic matching:

flowchart TD
    START["User Request"] --> PARSE["Parse Keywords & Context"]

    PARSE --> TRIGGER{"Exact Trigger<br/>Match?"}
    TRIGGER -->|"Yes (0.35)"| CORE{"Core<br/>Agent?"}
    TRIGGER -->|"No"| CATEGORY{"Category<br/>Match?"}

    CORE -->|"Yes"| USE_CORE["Load Core Agent<br/>(11 available)"]
    CORE -->|"No"| USE_EXT["Load Trait/Extension<br/>(20 available)"]

    CATEGORY -->|"Yes (0.25)"| CAT_SELECT["Select from Category"]
    CATEGORY -->|"No"| DESC{"Description<br/>Match?"}

    DESC -->|"Yes (0.20)"| DESC_SELECT["Score by Description"]
    DESC -->|"No"| TOOL{"Tool<br/>Match?"}

    TOOL -->|"Yes (0.20)"| TOOL_SELECT["Match Required Tools"]
    TOOL -->|"No"| FILE{"File<br/>Context?"}

    FILE -->|".py files"| PYTHON["Python Expert"]
    FILE -->|".ts/.js"| TS["TypeScript Pro"]
    FILE -->|".go files"| GO["Golang Pro"]
    FILE -->|".rs files"| RUST["Rust Engineer"]
    FILE -->|"Other"| GENERAL["General Purpose"]

    USE_CORE --> EXEC["Execute Task"]
    USE_EXT --> EXEC
    CAT_SELECT --> EXEC
    DESC_SELECT --> EXEC
    TOOL_SELECT --> EXEC
    PYTHON --> EXEC
    TS --> EXEC
    GO --> EXEC
    RUST --> EXEC
    GENERAL --> EXEC

    style START fill:#4caf50,color:#fff
    style EXEC fill:#2196f3,color:#fff

Selection Weights (from select_agent.py):

selection:
  weights:
    keyword_match: 0.35      # Keyword/trigger matching (highest priority)
    category_match: 0.25     # Domain/category alignment
    task_match: 0.20         # Task text matching
    file_patterns: 0.10      # File pattern matching
    priority_bonus: 0.10     # Tier priority bonus

  thresholds:
    minimum_score: 0.3       # Minimum match score
    confidence_levels:
      excellent: 0.7         # >= 0.7 score
      high: 0.5              # >= 0.5 score
      medium: 0.3            # >= 0.3 score

Command System

Commands provide structured execution patterns with optional quality gates.

Command Format

Each command is a markdown file with YAML frontmatter:

---
name: implement
description: Feature implementation with quality gates
aliases: [build, create, develop]
flags: [--loop, --tests, --docs, --pal-review, --consensus]
evidence_required: true
---

# Implement Command

[Structured implementation methodology...]

Command Execution Flow

sequenceDiagram
    participant U as User
    participant C as Claude Code
    participant CMD as Command Template
    participant A as Agent Persona
    participant O as LoopOrchestrator
    participant Q as QualityAssessor
    participant P as PAL MCP

    U->>C: /sc:implement feature --loop
    C->>CMD: Load implement.md template
    CMD->>A: Activate relevant personas
    C->>O: Initialize loop (max 5 iter)

    rect rgb(230, 245, 255)
        note over O,P: Iterative Improvement Loop
        loop Iteration 0..N (max 5)
            O->>A: Execute with context
            A-->>O: Return evidence
            O->>Q: Assess quality
            Q-->>O: Score + improvements

            alt Score >= 70
                O-->>C: QUALITY_MET
            else Oscillation/Stagnation
                O->>P: Generate debug signal
                O-->>C: Terminate
            else Continue
                O->>P: Generate review signal
                P-->>O: PAL feedback
                O->>A: Next iteration
            end
        end
    end

    O->>P: Final validation signal
    P-->>O: Validation result
    O-->>C: LoopResult
    C->>U: Implementation + quality report

Available Commands

Command	Aliases	Evidence	Key Flags
analyze	analyse, check, inspect	No	--security, --deep, --performance
implement	build, create, develop	Yes	--loop, --pal-review, --consensus, --tests
test	verify, check	Yes	--coverage, --unit, --integration
design	architect, plan	No	--adr, --diagram, --review
document	docs, readme	No	--api, --readme, --changelog
brainstorm	ideate, explore	No	--divergent, --constraints
explain	teach, learn, understand	No	--verbose, --simple, --diagram
improve	refactor, enhance, optimize	Yes	--performance, --readability, --security
build	compile, package	No	--watch, --production, --docker
git	commit, branch	No	--commit, --pr, --branch
workflow	pipeline, sequence	No	--spec, --parallel
estimate	scope, size	No	--breakdown, --risks
cicd-setup	cicd-init, pipeline-setup	No	--lang, --minimal, --full
readme	readme-sync, doc-sync	No	--base, --preview, --consensus
pr-fix	prfix, cifix, fix-pr	Yes	--branch, --auto-fix, --max-fix-attempts
pr-check	preflight, prepr	No	--fix, --strict
log-fix	logfix, debug-logs	No	--source, --pattern
e2e	e2e-test, browser-test	Yes	--browser, --headed, --trace
tdd	test-driven	Yes	--cycle, --framework
principles	validate-principles	No	--kiss, --solid, --purity, --crash
worktree	git-worktree	No	--name, --branch
mcp	mcp-orchestrate	No	--pal, --rube, --consensus
code-review	review, cr	No	--models, --consensus
research	deep-research	No	--depth, --sources
eda	data-analysis	No	--format, --output
evaluate	eval, judge	No	--dataset, --judge-model
push	git-push	No	--remotes, --exclude

Loop Orchestration

The loop orchestration system manages iterative improvement workflows with safety guarantees.

Termination Conditions

flowchart TD
    START["Start Loop Iteration 0"] --> EXEC["Execute Skill"]
    EXEC --> EVIDENCE["Collect Evidence"]
    EVIDENCE --> ASSESS["Assess Quality"]
    ASSESS --> SCORE{"Score >= 70?"}

    SCORE -->|"Yes"| QUALITY_MET["QUALITY_MET"]
    SCORE -->|"No"| MAX{"Iteration >= max?"}

    MAX -->|"Yes"| MAX_ITER["MAX_ITERATIONS"]
    MAX -->|"No"| TMOUT{"Timeout?"}

    TMOUT -->|"Yes"| TIMEOUT_TERM["TIMEOUT"]
    TMOUT -->|"No"| PAL["Generate PAL Review Signal"]
    PAL --> FEEDBACK["Incorporate Feedback"]
    FEEDBACK --> NEXT["Prepare Next Context"]
    NEXT --> EXEC

    QUALITY_MET --> FINAL["Final PAL Validation Signal"]

    FINAL --> DONE["Return LoopResult"]
    MAX_ITER --> DONE
    TIMEOUT_TERM --> DONE

    style QUALITY_MET fill:#4caf50,color:#fff
    style MAX_ITER fill:#ff9800,color:#fff
    style TIMEOUT_TERM fill:#f44336,color:#fff

All 5 Termination Reasons

Reason	Trigger	PAL Signal
`QUALITY_MET`	Score >= threshold (70)	Final validation
`MAX_ITERATIONS`	Iteration >= 5 (hard cap)	None
`ERROR`	Skill execution failure	None
`HUMAN_ESCALATION`	Requires human review	None
`TIMEOUT`	Wall-clock time exceeded	None

PAL Signal Types

The loop orchestrator generates two types of PAL signals:

Review Signal - Within-loop review for quality improvement
Final Validation Signal - After successful completion (score >= 70)

MCP Integrations

SuperClaude integrates with powerful MCP servers for enhanced capabilities:

flowchart TB
    subgraph PAL["PAL MCP - 11 Collaborative Tools"]
        P1["chat"] & P2["thinkdeep"] & P3["debug"]
        P4["planner"] & P5["precommit"]
        P6["codereview"] & P7["consensus"] & P8["challenge"]
        P9["apilookup"] & P10["listmodels"] & P11["clink"]
    end

    subgraph Rube["Rube MCP - 500+ App Integrations (11 tools)"]
        R1["SEARCH_TOOLS"] & R2["GET_TOOL_SCHEMAS"] & R3["MULTI_EXECUTE_TOOL"]
        R4["REMOTE_BASH_TOOL"] & R5["REMOTE_WORKBENCH"]
        R6["FIND_RECIPE"] & R7["EXECUTE_RECIPE"] & R8["GET_RECIPE_DETAILS"]
        R9["CREATE_UPDATE_RECIPE"] & R10["MANAGE_CONNECTIONS"] & R11["MANAGE_RECIPE_SCHEDULE"]
    end

    TASK["SuperClaude Task"] --> PAL
    TASK --> Rube

    style PAL fill:#e3f2fd
    style Rube fill:#fce4ec

PAL MCP (11 Tools)

Collaborative intelligence for code review, debugging, and multi-model consensus:

Tool	Purpose	Use Case
`mcp__pal__chat`	General collaborative thinking	Brainstorming, second opinions
`mcp__pal__thinkdeep`	Multi-stage investigation	Complex problem analysis
`mcp__pal__planner`	Interactive sequential planning	Project planning with revision
`mcp__pal__consensus`	Multi-model decision making	Architecture decisions, evaluations
`mcp__pal__codereview`	Systematic code review	Quality assessment, security review
`mcp__pal__precommit`	Git change validation	Pre-commit checks, change impact
`mcp__pal__debug`	Root cause analysis	Complex debugging, issue diagnosis
`mcp__pal__challenge`	Critical thinking	Push back on assumptions
`mcp__pal__apilookup`	API documentation lookup	Current SDK/API information
`mcp__pal__listmodels`	List available models	Model selection and capabilities
`mcp__pal__clink`	External AI CLI linking	Connect to Gemini, Codex, etc.

Rube MCP (Composio)

Session-based workflow automation with 500+ app integrations:

sequenceDiagram
    participant C as Claude Code
    participant R as Rube MCP
    participant A as External App (Slack, GitHub, etc.)

    C->>R: RUBE_SEARCH_TOOLS<br/>{session: {generate_id: true}, queries: [...]}
    R-->>C: session_id + available tools + execution plan

    C->>R: RUBE_MULTI_EXECUTE_TOOL<br/>{session_id, tools: [...], memory: {...}}
    R->>A: Execute tool (e.g., SLACK_SEND_MESSAGE)
    A-->>R: Tool result
    R-->>C: Results + updated memory

    opt Complex Workflow
        C->>R: RUBE_CREATE_PLAN<br/>{session_id, use_case, difficulty}
        R-->>C: Detailed execution plan
    end

    opt Recipe Execution
        C->>R: RUBE_FIND_RECIPE<br/>{query: "..."}
        R-->>C: Matching recipes with recipe_id
        C->>R: RUBE_EXECUTE_RECIPE<br/>{recipe_id, input_data}
        R-->>C: Recipe execution result
    end

Connected Services:

Category	Examples
Development	GitHub, GitLab, Bitbucket, Linear, Jira
Communication	Slack, Discord, Teams, Email
Productivity	Notion, Asana, Trello, Airtable
Google Workspace	Gmail, Calendar, Drive, Sheets, Docs
Microsoft	Outlook, Teams, OneDrive, SharePoint
Social	X (Twitter), LinkedIn, Meta apps
AI Tools	Various AI services and APIs

Web Search (via Rube MCP)

Web search capabilities are available through Rube MCP's LINKUP_SEARCH tool:

Deep or standard search depth
Sourced answers with citations and URLs
Accessed via LINKUP_SEARCH tool in RUBE_MULTI_EXECUTE_TOOL

Skills System

SuperClaude includes 38 active Claude Code skills in .claude/skills/:

flowchart TB
    subgraph Skills[".claude/skills/ (38 active)"]
        subgraph Agent["Agent Skills (8)"]
            A1["agent-data-engineer"]
            A2["agent-fullstack-developer"]
            A3["agent-kubernetes-specialist"]
            A4["agent-ml-engineer"]
            A5["agent-performance-engineer"]
            A6["agent-react-specialist"]
            A7["agent-security-engineer"]
            A8["agent-technical-writer"]
        end

        subgraph Command["Command Skills (27)"]
            C1["sc-analyze"]
            C2["sc-brainstorm"]
            C3["sc-build"]
            C4["sc-cicd-setup"]
            C5["sc-code-review"]
            C6["sc-design"]
            C7["sc-document"]
            C8["sc-e2e"]
            C9["sc-eda"]
            C10["sc-estimate"]
            C11["sc-evaluate"]
            C12["sc-explain"]
            C13["sc-git"]
            C14["sc-implement"]
            C15["sc-improve"]
            C16["sc-log-fix"]
            C17["sc-mcp"]
            C18["sc-pr-check"]
            C19["sc-pr-fix"]
            C20["sc-principles"]
            C21["sc-push"]
            C22["sc-readme"]
            C23["sc-research"]
            C24["sc-tdd"]
            C25["sc-test"]
            C26["sc-workflow"]
            C27["sc-worktree"]
        end

        subgraph Utility["Utility Skills (3)"]
            U1["ask<br/>(single-select)"]
            U2["ask-multi<br/>(multi-select)"]
            U3["learned<br/>(auto-learned)"]
        end
    end

    subgraph Structure["Skill File Structure"]
        direction LR
        SKILL["SKILL.md<br/>(AI-facing interface)"]
        SCRIPTS["scripts/<br/>(Tool implementations)"]
    end

    Skills --> Structure

    subgraph ScriptDetail["sc-implement/scripts/ (5 tools)"]
        S1["select_agent.py (551 lines)<br/>Weighted agent selection"]
        S2["run_tests.py (344 lines)<br/>Test framework detection"]
        S3["evidence_gate.py (256 lines)<br/>Quality validation"]
        S4["skill_learn.py (466 lines)<br/>Skill extraction"]
        S5["loop_entry.py (229 lines)<br/>Loop orchestration"]
    end

Skill Types

Type	Pattern	Count	Purpose
Agent Skills	`agent-*`	8	Specialized personas for domains
Command Skills	`sc-*`	27	Structured workflow implementations
Utility Skills	`ask`, `ask-multi`, `learned`	3	User interaction and learning

Skill Architecture

Each skill follows a standard structure:

.claude/skills/agent-security-engineer/
└── SKILL.md                 # AI-facing interface (what Claude reads)

.claude/skills/sc-implement/
├── SKILL.md                 # Command interface
└── scripts/                 # Optional tool implementations
    ├── select_agent.py      # Weighted agent selection algorithm
    ├── run_tests.py         # Test framework detection and execution
    ├── evidence_gate.py     # Quality validation (production_ready/acceptable/needs_review)
    ├── skill_learn.py       # Skill extraction from successful executions
    └── loop_entry.py        # Loop orchestration entry point

Important Distinction:

SKILL.md = The interface Claude reads to understand when/how to invoke
scripts/*.py = Backend implementations executed by the host system

This follows standard agentic patterns: config-first architecture means the AI-facing interface is pure configuration, while Python handles orchestration.

Skill Learning System

The learned/ skill directory stores patterns extracted from successful executions:

Extraction: skill_learn.py extracts patterns from successful --loop executions
Promotion: Skills promoted when quality score >= 85.0 and success rate >= 70%
Retrieval: Auto-retrieved based on task keywords, file types, domain context
Metadata: Tracks provenance (session ID, timestamp, quality progression)

Using Skills

Skills are invoked via:

Semantic selection - Claude automatically selects based on task context
Direct reference - @agent-security-engineer or /sc-implement
Skill tool - Skill("agent-security-engineer") for explicit invocation

Quality System

SuperClaude uses a 9-dimension quality scoring system with automated actions:

flowchart LR
    subgraph Dimensions["9 Quality Dimensions"]
        C["Correctness<br/>25%"]
        CO["Completeness<br/>20%"]
        P["Performance<br/>10%"]
        M["Maintainability<br/>10%"]
        S["Security<br/>10%"]
        SC["Scalability<br/>10%"]
        T["Testability<br/>10%"]
        U["Usability<br/>5%"]
        PAL["PAL Review<br/>0%*"]
    end

    subgraph Bands["Quality Bands"]
        E["90+ Excellent"]
        G["70-89 Good"]
        A["50-69 Acceptable"]
        P2["30-49 Poor"]
        F["0-29 Failing"]
    end

    subgraph Actions["Auto-Actions"]
        FT["Fast-track<br/>Skip review"]
        AP["Approve<br/>Complete task"]
        IT["Iterate<br/>Loop continues"]
        ES["Escalate<br/>Human review"]
        BL["Block<br/>Reject output"]
    end

    Dimensions -->|"Weighted<br/>Average"| Bands
    E --> FT
    G --> AP
    A --> IT
    P2 --> ES
    F --> BL

    style E fill:#4caf50,color:#fff
    style G fill:#8bc34a
    style A fill:#ffeb3b
    style P2 fill:#ff9800,color:#fff
    style F fill:#f44336,color:#fff

*PAL Review: Dynamic weight when --pal-review enabled

Quality Dimensions

Dimension	Weight	Indicators
Correctness	25%	Tests pass, no runtime errors, output validation
Completeness	20%	Feature coverage, edge cases, documentation
Performance	10%	Time/space complexity, resource usage
Maintainability	10%	Readability, modularity, naming conventions
Security	10%	Input validation, authentication, data protection
Scalability	10%	Architecture patterns, database design, caching
Testability	10%	Unit tests, integration tests, test quality
Usability	5%	UI consistency, error messages, accessibility
PAL Review	0%*	External code review score (dynamic weight)

Evidence Requirements

Requires Evidence	Does Not Require Evidence
`sc-implement` - File diffs, test results	`sc-analyze` - Analysis output
`sc-improve` - Before/after, metrics	`sc-design` - Specifications, diagrams
`sc-test` - Test output, coverage	`sc-document` - Documentation files
	`sc-git` - Git history (self-documenting)
	`sc-explain` - Learning materials

Quality Thresholds (from `evidence_gate.py`)

Status	Score	Action
Production Ready	90.0+	Fast-track, skip additional review
Acceptable	70.0-89.9	Approve, task complete
Needs Review	50.0-69.9	Iterate or escalate
Below Threshold	< 50.0	Block, requires significant rework

Quality Gates

SuperClaude enforces code quality through automated validators integrated into the development workflow via the /sc:principles command.

KISS Validator

Enforces code simplicity via AST analysis. Located at .claude/skills/sc-principles/scripts/validate_kiss.py.

Metric	Threshold	Severity	Description
Cyclomatic Complexity	> 10	error	Number of independent paths through code
Cyclomatic Complexity	> 7	warning	Early warning for growing complexity
Cognitive Complexity	> 15	error	Weighted complexity (nested structures count more)
Function Length	> 50 lines	error	Lines of code per function
Nesting Depth	> 4 levels	error	If/for/while/with/try nesting
Parameter Count	> 5	warning	Function parameters

Usage:

python .claude/skills/sc-principles/scripts/validate_kiss.py --scope-root . --json

Cognitive vs Cyclomatic Complexity:

Cyclomatic counts decision points (branches)
Cognitive weights nested structures more heavily: 1 + nesting_depth per control structure
Example: if (if (if ...)) has low cyclomatic but high cognitive (hard to read)

Purity Validator

Enforces "Functional Core, Imperative Shell" architectural pattern. Located at .claude/skills/sc-principles/scripts/validate_purity.py.

Layer	Path Patterns	I/O Allowed	Severity
Core (purity required)	`/domain/`, `/logic/`, `/services/`, `/utils/`, `/core/`	NO	error
Shell (I/O allowed)	`/handlers/`, `/adapters/`, `/api/`, `/cli/`, `/scripts/`, `/tests/`	YES	warning

Detected I/O Patterns:

Category	Examples
File I/O	`open()`, `read()`, `write()`, `Path.read_text()`
Network	`requests.get()`, `httpx`, `urllib`, `socket`
Database	`execute()`, `query()`, `session.add()`, `cursor`
Subprocess	`subprocess.run()`, `os.system()`, `Popen`
Global State	`global`, `nonlocal` keywords
Side Effects	`print()`, `logging.`, `logger.`
Async I/O	`async def`, `await`, `async for`, `async with`

Usage:

python .claude/skills/sc-principles/scripts/validate_purity.py --scope-root . --json

SOLID Validator

Enforces SOLID design principles via AST analysis. Located at .claude/skills/sc-principles/scripts/validate_solid.py.

Principle	Check	Threshold	Severity
SRP (Single Responsibility)	File length	> 300 lines	error
SRP (Single Responsibility)	Class public methods	> 5	error
OCP (Open/Closed)	isinstance cascades	> 2 chained	error
LSP (Liskov Substitution)	NotImplementedError in overrides	Any	error
ISP (Interface Segregation)	Fat interfaces/protocols	> 7 methods	error
DIP (Dependency Inversion)	Direct instantiation in business logic	Any	warning

Usage:

python .claude/skills/sc-principles/scripts/validate_solid.py --scope-root . --json

Let It Crash Validator

Enforces the "Let It Crash" error handling philosophy by detecting anti-patterns. Located at .claude/skills/sc-principles/scripts/validate_crash.py.

Anti-Pattern	Description	Severity
Bare `except:`	Catches all exceptions without specificity	error
`except Exception` without re-raise	Swallows exceptions silently	error
`except: pass`	Silent failure hiding bugs	error
Nested try/except cascades	Deeply nested error handling (> 2 levels)	error

Usage:

python .claude/skills/sc-principles/scripts/validate_crash.py --scope-root . --json

Pre-commit Integration

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: kiss-check
        name: KISS Validation
        entry: python .claude/skills/sc-principles/scripts/validate_kiss.py --scope-root . --json
        language: python
        types: [python]
        pass_filenames: false

      - id: purity-check
        name: Purity Validation
        entry: python .claude/skills/sc-principles/scripts/validate_purity.py --scope-root . --json
        language: python
        types: [python]
        pass_filenames: false

      - id: solid-check
        name: SOLID Validation
        entry: python .claude/skills/sc-principles/scripts/validate_solid.py --scope-root . --json
        language: python
        types: [python]
        pass_filenames: false

      - id: crash-check
        name: Let It Crash Validation
        entry: python .claude/skills/sc-principles/scripts/validate_crash.py --scope-root . --json
        language: python
        types: [python]
        pass_filenames: false

Exit Codes

Code	Meaning	Action
0	Validation passed	Proceed
2	Violations detected	Blocked - refactor required
3	Validation error	Manual intervention needed

Refactoring Guidance

When violations are detected:

For Complexity Violations:

Extract Method - Split large functions into smaller, named pieces
Guard Clauses - Replace nested if/else with early returns
Strategy Pattern - Replace complex switch/if-else with polymorphism
Decompose Conditional - Name complex conditions as explaining variables

For Purity Violations:

Dependency Injection - Pass dependencies as arguments
Repository Pattern - Isolate database operations
Adapter Pattern - Wrap external APIs
Return Don't Print - Return values, let callers handle output

Metrics System

SuperClaude includes a callback-based metrics system (core/metrics.py) that decouples the orchestrator from specific metrics backends.

MetricsEmitter Protocol

@runtime_checkable
class MetricsEmitter(Protocol):
    """Protocol defining the interface for metrics emission."""

    def __call__(
        self,
        metric_name: str,
        value: Any,
        tags: Optional[Dict[str, str]] = None,
    ) -> None: ...

Available Emitters

Emitter	Purpose	Use Case
`noop_emitter`	Does nothing	Default when no emitter configured
`InMemoryMetricsCollector`	Collects to list	Testing and debugging
`LoggingMetricsEmitter`	Logs via Python logging	Simple production logging

InMemoryMetricsCollector

Testing utility for collecting and querying metrics:

from core.metrics import InMemoryMetricsCollector

collector = InMemoryMetricsCollector()
orchestrator = LoopOrchestrator(config, metrics_emitter=collector)
result = orchestrator.run(context, invoker)

# Query collected metrics
assert collector.get("loop.completed.count") == 1
assert collector.get("loop.duration.seconds") > 0
assert collector.count("loop.iteration.quality_score.gauge") == 3

# Filter by tags
error_metrics = collector.filter_by_tags(
    "loop.errors.count",
    {"reason": "skill_invocation"}
)

Emitted Metrics

Loop Orchestrator Metrics:

Metric	Type	Description
`loop.started.count`	counter	Loop initiated
`loop.completed.count`	counter	Loop finished (tags: termination_reason)
`loop.duration.seconds`	timing	Total loop time
`loop.iterations.total.gauge`	gauge	Iterations executed
`loop.quality_score.final.gauge`	gauge	Final quality score
`loop.errors.count`	counter	Errors (tags: reason)
`loop.iteration.duration.seconds`	timing	Per-iteration timing
`loop.iteration.quality_score.gauge`	gauge	Per-iteration quality
`loop.iteration.quality_delta.gauge`	gauge	Quality change per iteration

Skill Learning Metrics:

Metric	Type	Description
`learning.skills.applied.count`	counter	Skills injected at start
`learning.skills.extracted.count`	counter	Skills learned (tags: domain, success)
`learning.skills.promoted.count`	counter	Skills auto-promoted (tags: reason)

Naming Convention

<component>.<subject>.<unit>

Suffix	Type	Use Case
`.count`	counter	Events (incremental)
`.gauge`	gauge	Current state (point-in-time)
`.seconds`	timing	Duration measurement

Integration Examples

Prometheus:

from prometheus_client import Counter, Gauge

counters, gauges = {}, {}

def prometheus_emitter(name, value, tags=None):
    labels = tags or {}
    if name.endswith('.count'):
        if name not in counters:
            counters[name] = Counter(name.replace('.', '_'), '', list(labels.keys()))
        counters[name].labels(**labels).inc(value)
    elif name.endswith('.gauge'):
        if name not in gauges:
            gauges[name] = Gauge(name.replace('.', '_'), '', list(labels.keys()))
        gauges[name].labels(**labels).set(value)

StatsD:

import statsd
client = statsd.StatsClient()

def statsd_emitter(name, value, tags=None):
    if name.endswith('.count'):
        client.incr(name, value)
    elif name.endswith('.gauge'):
        client.gauge(name, value)
    elif name.endswith('.seconds'):
        client.timing(name, value * 1000)  # Convert to ms

Type System

Core types defined in core/types.py:

TerminationReason

class TerminationReason(Enum):
    """Reasons for loop termination."""
    QUALITY_MET = "quality_threshold_met"          # Score >= 70
    MAX_ITERATIONS = "max_iterations_reached"      # Hard cap at 5
    ERROR = "improver_error"                      # Skill execution failure
    HUMAN_ESCALATION = "requires_human_review"    # Needs human input
    TIMEOUT = "timeout"                           # Wall-clock exceeded

LoopConfig

@dataclass
class LoopConfig:
    """Configuration for the agentic loop."""
    max_iterations: int = 3           # Requested max (user-configurable)
    hard_max_iterations: int = 5      # P0 SAFETY: Cannot be overridden
    quality_threshold: float = 70.0   # Target score to meet
    timeout_seconds: Optional[float]  # Wall-clock timeout (optional)
    pal_review_enabled: bool = True   # Enable PAL MCP review within loop
    pal_model: str = "gpt-5"          # Model to use for PAL reviews

QualityAssessment

@dataclass
class QualityAssessment:
    """Result of quality assessment for an iteration."""
    overall_score: float              # Numeric quality score (0-100)
    passed: bool                      # Whether quality threshold was met
    threshold: float = 70.0           # The threshold checked against
    improvements_needed: list[str]    # Specific improvements to make
    metrics: dict[str, float]         # Detailed breakdown by dimension
    band: str = "unknown"             # Quality band (excellent/good/acceptable/poor)
    metadata: dict[str, Any]          # Additional context from evidence

IterationResult

@dataclass
class IterationResult:
    """Result of a single loop iteration."""
    iteration: int                    # Zero-based iteration number
    input_quality: float              # Quality score before this iteration
    output_quality: float             # Quality score after this iteration
    improvements_applied: list[str]   # Improvements that were applied
    time_taken: float = 0.0           # Duration in seconds
    success: bool = False             # Whether iteration improved quality
    termination_reason: str = ""      # If loop terminated, why
    pal_review: Optional[Dict] = None # PAL MCP review results
    changed_files: list[str]          # Files modified in this iteration

LoopResult

@dataclass
class LoopResult:
    """Final result of complete loop execution."""
    final_output: dict[str, Any]              # Final state after all iterations
    final_assessment: QualityAssessment       # Quality assessment of final state
    iteration_history: list[IterationResult]  # All iteration results
    termination_reason: TerminationReason     # Why the loop stopped
    total_iterations: int                     # Number of iterations executed
    total_time: float = 0.0                   # Total wall-clock time

Configuration

SuperClaude uses 6 YAML configuration files:

config/superclaud.yaml

Main framework configuration:

version: 7.0.0
name: SuperClaude Framework

modes:
  default: normal
  available: [normal, brainstorming, introspection, task_management, token_efficiency, orchestration]

agents:
  max_delegation_depth: 5
  circular_detection: true
  parallel_execution: true
  default_timeout: 300

commands:
  prefix: "/sc:"
  discovery_path: SuperClaude/Commands
  cache_ttl: 3600

quality:
  enabled: true
  default_threshold: 70.0
  max_iterations: 5
  dimensions:
    correctness: 0.25
    completeness: 0.20
    performance: 0.10
    maintainability: 0.10
    security: 0.10
    scalability: 0.10
    testability: 0.10
    usability: 0.05
    pal_review: 0.00  # Dynamic when enabled

mcp_servers:
  enabled: true
  timeout: 300
  retry_attempts: 3
  servers:
    pal:
      enabled: true
      models: [gpt-5, claude-opus-4.1, gemini-2.5-pro]

triggers:
  mode_triggers:
    brainstorming: [explore, brainstorm, "figure out", "not sure"]
    introspection: ["analyze my reasoning", reflect, meta-cognitive]
  agent_triggers:
    root-cause-analyst: [debug, error, broken, "not working"]
    refactoring-expert: [refactor, "improve code", "clean up"]

workflows:
  default_workflow: [analyze, plan, implement, test, document]
  debug_workflow: [reproduce, analyze, isolate, fix, verify]

config/quality.yaml

Quality scoring configuration:

dimensions:
  correctness:
    weight: 0.25
    description: Code works as intended, tests pass
  completeness:
    weight: 0.20
    description: All requirements addressed, edge cases handled
  # ... additional dimensions

scoring:
  thresholds:
    excellent: 90
    good: 70
    acceptable: 50
    poor: 30

validation:
  pre_execution: [syntax, dependencies, security]
  post_execution: [tests, performance, coverage]
  continuous: [resources, errors, trends]

config/models.yaml

Model routing configuration:

providers:
  openai:
    models:
      - name: gpt-5
        context: 400000
        priority: 1
      - name: gpt-4.1
        context: 1000000
        priority: 3
  anthropic:
    models:
      - name: claude-opus-4.1
        context: 200000
        priority: 2
  google:
    models:
      - name: gemini-2.5-pro
        context: 2000000
        priority: 1

routing:
  deep_thinking: [gpt-5, gemini-2.5-pro]
  consensus: [gpt-5, claude-opus-4.1, gemini-2.5-pro]
  long_context: [gemini-2.5-pro]
  fast_iteration: [grok-code-fast-1]

config/agents.yaml

Agent selection configuration:

core:
  count: 11
  directory: agents/core
  cache_ttl: 3600

traits:
  count: 12
  directory: agents/traits

extensions:
  count: 8
  directory: agents/extensions

selection:
  algorithm: weighted-match
  weights:
    trigger_match: 0.35
    category_match: 0.25
    description_match: 0.20
    tool_match: 0.20
  thresholds:
    minimum_score: 0.6
    confidence_level: 0.8

config/mcp.yaml

MCP server reference:

servers:
  pal:
    tools: 11
    categories: [analysis, planning, validation, utility]
  rube:
    integrations: 500+
    categories: [development, communication, productivity, google, microsoft]
    # Web search available via LINKUP_SEARCH tool

config/consensus_policies.yaml

Multi-model consensus configuration:

policies:
  quorum:
    min_models: 2
    threshold: 0.7
  voting:
    method: weighted
    tie_breaker: priority

Directory Structure

SuperClaude/
├── CLAUDE.md                    # Master system prompt
├── README.md                    # This file
├── CONTRIBUTING.md              # Contribution guidelines
├── CHANGELOG.md                 # Version history
├── pyproject.toml               # Python project config
│
├── .claude/
│   └── skills/                  # 38 Claude Code skills
│       ├── agent-*/             # 8 agent persona skills
│       │   └── SKILL.md
│       ├── sc-*/                # 27 command skills
│       │   ├── SKILL.md
│       │   └── scripts/         # Optional tool implementations
│       ├── ask/                 # Single-select questions
│       ├── ask-multi/           # Multi-select questions
│       └── learned/             # Auto-learned skills
│
├── agents/
│   ├── index.yaml               # Agent registry
│   ├── core/                    # 11 core agent prompts
│   │   ├── general-purpose.md
│   │   ├── root-cause-analyst.md
│   │   ├── refactoring-expert.md
│   │   └── ...
│   ├── traits/                  # 12 composable trait prompts
│   │   ├── security-first.md
│   │   ├── performance-first.md
│   │   ├── test-driven.md
│   │   ├── mcp-pal-enabled.md
│   │   ├── mcp-rube-enabled.md
│   │   └── ...
│   ├── extensions/              # 8 domain specialist prompts
│   │   ├── typescript-expert.md
│   │   ├── golang-expert.md
│   │   ├── react-specialist.md
│   │   └── ...
│   └── DEPRECATED/              # Archived agents from previous versions
│
├── commands/
│   ├── index.yaml               # Command registry
│   ├── index.md                 # Command reference
│   ├── analyze.md
│   ├── implement.md
│   ├── test.md
│   └── ...                      # 16 command templates
│
├── config/
│   ├── superclaud.yaml          # Main framework config (281 lines)
│   ├── quality.yaml             # Quality scoring config
│   ├── models.yaml              # Model routing config
│   ├── agents.yaml              # Agent selection config
│   ├── mcp.yaml                 # MCP server reference
│   └── consensus_policies.yaml  # Consensus voting config
│
├── core/                        # Python orchestration layer
│   ├── __init__.py
│   ├── loop_orchestrator.py     # Loop management (~410 lines)
│   ├── quality_assessment.py    # Quality scoring
│   ├── pal_integration.py       # PAL MCP signals
│   ├── metrics.py               # Callback-based metrics protocol
│   ├── types.py                 # Core types (150 lines)
│   ├── skill_learning_integration.py
│   └── skill_persistence.py
│
├── SuperClaude/
│   └── Orchestrator/            # SDK-based orchestration
│       ├── __init__.py
│       ├── evidence.py          # Evidence collection
│       ├── events_hooks.py      # Event hook integration
│       ├── hooks.py             # SDK hook integration
│       ├── loop_runner.py       # Agentic loop runner
│       ├── quality.py           # Quality assessment
│       └── obsidian_hooks.py    # Obsidian vault sync hooks
│
├── crates/                         # Rust workspace
│   ├── dashboard/               # Tauri v2 desktop dashboard (Leptos WASM frontend)
│   │   └── frontend/src/
│   │       ├── components/      # UI: sidebar, execution_detail, execution_tree, diff_view, ...
│   │       ├── pages/           # inventory, monitor, control, history
│   │       └── state/           # Reactive signals (AppState, ExecutionTree, DTOs)
│   ├── proto/                   # Protobuf/gRPC service definitions
│   ├── superclaude-core/        # Shared domain types and utilities
│   ├── superclaude-daemon/      # gRPC daemon (port 50051)
│   ├── superclaude-runtime/     # Rust runtime: agent selector, obsidian vault, loop runner, registry
│   ├── hangman-game/            # Hangman game example
│   └── snake-game/              # Snake game example
│
├── setup/                          # Installation and setup system
│   ├── cli/                     # CLI commands (install, update, backup, clean, uninstall)
│   ├── components/              # Component installers (agents, commands, core, mcp, modes)
│   ├── core/                    # Installer base, registry, validator
│   ├── services/                # Service integrations
│   │   ├── obsidian_config.py   # Obsidian config management
│   │   ├── obsidian_vault.py    # Vault reading/scanning
│   │   ├── obsidian_context.py  # Context generation
│   │   ├── obsidian_artifact.py # Decision artifact writing
│   │   └── obsidian_md.py       # CLAUDE.md integration
│   └── utils/                   # Environment, logging, security, UI, updater
│
├── mcp/                         # MCP integration guides
│   ├── MCP_Pal.md               # PAL MCP (11 tools)
│   ├── MCP_Rube.md              # Rube MCP (500+ apps, including web search)
│   └── MCP_Zen.md               # Zen MCP
│
├── tests/                       # Test suite
│   ├── core/                    # Core module tests
│   │   ├── test_loop_orchestrator.py
│   │   ├── test_pal_integration.py
│   │   ├── test_quality_assessment.py
│   │   └── test_types.py
│   └── fixtures/                # Test data
│       └── consensus/
│
├── Docs/                        # Documentation
│   ├── claude-code-reference.md # Claude Code reference guide
│   ├── quality-gates.md
│   └── README.md
│
└── archive/                     # Archived Python SDK (v5)

Creating Custom Agents

Agent Prompt Format

Create a new agent in agents/extensions/:

---
name: my-custom-agent
description: Brief description of the agent's purpose
category: custom
triggers: [keyword1, keyword2, keyword3]
tools: [Read, Write, Edit, Bash, Grep, Glob]
priority: 5
---

# My Custom Agent

You are an expert in [domain] specializing in [specialty].

## Focus Areas

- Area 1: Description
- Area 2: Description
- Area 3: Description

## Approach

1. **Analysis**: Understand the problem thoroughly
2. **Planning**: Design a solution approach
3. **Implementation**: Execute with quality checks
4. **Validation**: Verify results meet requirements

## Best Practices

- Practice 1
- Practice 2
- Practice 3

## Anti-Patterns

- Avoid X because Y
- Don't do Z without W

## Checklist

- [ ] Requirement 1 verified
- [ ] Requirement 2 verified
- [ ] Tests passing
- [ ] Documentation updated

Register the Agent

Add to agents/index.yaml:

extended:
  custom-category:
    description: "Custom agents"
    priority: 6
    agents:
      - name: my-custom-agent
        file: extended/custom-category/my-custom-agent.md
        triggers: [keyword1, keyword2]
        priority: 5

Create Matching Skill

Create .claude/skills/agent-my-custom-agent/SKILL.md:

---
name: agent-my-custom-agent
description: Brief description matching the agent
---

# My Custom Agent Skill

[Content matching the agent definition]

Contributing

Contributions welcome! Key areas:

Priority Areas

New Agents: Add specialized agent personas for underserved domains
Command Templates: Improve command structures and workflows
MCP Guides: Add integration documentation for new MCP servers
Configuration: Tune selection algorithms and quality thresholds
Core Orchestration: Enhance loop mechanics and termination detection
Skill Learning: Improve pattern extraction and skill promotion

Quality Standards

All tests pass before completion
90% test coverage for new features
Python 3.10+ compatibility
Cross-platform support (Linux, macOS, Windows)
Comprehensive error handling and logging
Security best practices for external integrations

Code Style

Python: Follow PEP 8, use type hints
Markdown: Use ATX headers, proper nesting
YAML: 2-space indentation, quotes for strings with special chars

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

Claude Code team at Anthropic
MCP server developers (PAL, Rube/Composio)
All contributors to the SuperClaude framework

SuperClaude v7.0.0 Config-First Meta-Framework for Claude Code 31 Agents (11 Core + 12 Traits + 8 Extensions) | 38 Skills | 27 Commands | 6 Modes | Quality-Driven Loops

Name	agent-task-distributor
Description	Expert task distributor specializing in intelligent work allocation, load balancing, and queue management. Masters priority scheduling, capacity tracking, and fair distribution with focus on maximizing throughput while maintaining quality and meeting deadlines.

agent-task-distributor

SKILL.md

SuperClaude Framework

Table of Contents

Overview

Key Features

Config-First Hybrid Architecture

Why Config-First Hybrid?

Tiered Agent Architecture

Command System

Architecture

How SuperClaude Works

File-Based Configuration

Core Orchestration Layer

Modules

LoopOrchestrator

Signal Architecture

Core API Reference

Module Exports

LoopOrchestrator

QualityAssessor

PALReviewSignal

Helper Functions

Installation

Option 1: Clone Repository

Option 2: Add as Git Submodule

Setup Claude Code

Optional: Python Dependencies

Quick Start

1. Basic Usage

2. Using Commands

3. Specifying Agents

4. Iterative Improvement

5. Using MCP Tools

Dashboard

Features

Quick Start

Building for Production

System Requirements

Agent System

Core Agents (11)

Traits (12)

Extensions (8)

Agent Selection Algorithm

Command System

Command Format

Command Execution Flow

Available Commands

Loop Orchestration

Termination Conditions

All 5 Termination Reasons

PAL Signal Types

MCP Integrations

PAL MCP (11 Tools)

Rube MCP (Composio)

Web Search (via Rube MCP)

Skills System

Skill Types

Skill Architecture

Skill Learning System

Using Skills

Quality System

Quality Dimensions

Evidence Requirements

Quality Thresholds (from evidence_gate.py)

Quality Gates

KISS Validator

Purity Validator

SOLID Validator

Let It Crash Validator

Pre-commit Integration

Exit Codes

Refactoring Guidance

Metrics System

MetricsEmitter Protocol

Available Emitters

InMemoryMetricsCollector

Emitted Metrics

Naming Convention

Integration Examples

Quality Thresholds (from `evidence_gate.py`)