agent-incident-responder
A configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.
Open source Repository Open in the app JSON README (API)
About
A configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.
Details
- Kind
- Agent skills
- Topic
- Cloud & DevOps
- Publisher
- tony363
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 13
- Forks
- 2
- Open pull requests
- 7
- Last push
- 2026-06-29T09:15:00Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-02 18:10:01
- Updated
- 2026-09-02 18:10:01
- Origin id
tony363/superclaude/.claude/skills/DEPRECATED/agent-incident-responder@main
README
# SuperClaude Framework
<p align="center">
<img src="https://img.shields.io/badge/version-7.0.0-blue" alt="Version">
<img src="https://img.shields.io/badge/agents-19-orange" alt="Agents">
<img src="https://img.shields.io/badge/skills-43-green" alt="Skills">
<img src="https://img.shields.io/badge/commands-27-purple" alt="Commands">
<img src="https://img.shields.io/badge/modes-6-teal" alt="Modes">
<img src="https://img.shields.io/badge/python_core-2800_lines-red" alt="Core">
<img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="License">
<a href="https://sonarcloud.io/summary/new_code?id=tony363_superclaude"><img src="https://sonarcloud.io/api/project_badges/measure?project=tony363_superclaude&metric=alert_status" alt="Quality Gate"></a>
<a href="https://sonarcloud.io/summary/new_code?id=tony363_superclaude"><img src="https://sonarcloud.io/api/project_badges/measure?project=tony363_superclaude&metric=coverage" alt="Coverage"></a>
</p>
**A config-first meta-framework for Claude Code that provides 19 specialized agent personas (5 core + 7 traits + 7 extensions), 27 structured commands, 43 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](#overview)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Core Orchestration Layer](#core-orchestration-layer)
- [Core API Reference](#core-api-reference)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Dashboard](#dashboard)
- [Agent System](#agent-system)
- [Command System](#command-system)
- [Loop Orchestration](#loop-orchestration)
- [MCP Integrations](#mcp-integrations)
- [Skills System](#skills-system)
- [Quality System](#quality-system)
- [Quality Gates](#quality-gates)
- [Metrics System](#metrics-system)
- [Type System](#type-system)
- [Configuration](#configuration)
- [Directory Structure](#directory-structure)
- [Creating Custom Agents](#creating-custom-agents)
- [Contributing](#contributing)
---
## Overview
SuperClaude is a meta-prompt framework that enhances Claude Code with:
- **19 Specialized Agents**: 5 core + 7 composable traits + 7 domain extensions (tiered architecture)
- **43 Active Skills**: 8 agent personas + 26 command workflows + 6 GitNexus code intelligence + 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
19 agents organized in a tiered system for composable expertise:
| Tier | Count | Purpose | Examples |
|------|-------|---------|----------|
| **Core** | 5 | High-priority generalists | architect, developer, optimizer, guardian, communicator |
| **Traits** | 7 | Composable modifiers | security-first, performance-first, test-driven, minimal-changes, principles-enforced, mcp-pal-enabled, mcp-rube-enabled |
| **Extensions** | 7 | Domain specialists | typescript-react-expert, python-expert, golang-expert, rust-expert, 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., `@architect +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
```mermaid
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/>5 core + 7 traits + 7 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:
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** - 5 core agent persona prompts
4. **agents/traits/*.md** - 7 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** - 16 command templates
8. **config/*.yaml** - 6 configuration files
9. **core/*.py** - Python orchestration modules
10. **mcp/*.md** - MCP integration guides
11. **.claude/skills/** - 43 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:
```mermaid
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: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:
```python
# 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
```python
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.
```python
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:**
```python
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.
```python
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.
```python
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
```python
# 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
```bash
git clone https://github.com/Tony363/SuperClaude.git
cd SuperClaude
```
### Option 2: Add as Git Submodule
```bash
git submodule add https://github.com/Tony363/SuperClaude.git SuperClaude
```
### Setup Claude Code
Add to your project's `.claude/settings.json`:
```json
{
"systemPromptFiles": ["SuperClaude/CLAUDE.md"]
}
```
Or copy `CLAUDE.md` to your project root.
### Optional: Python Dependencies
For advanced workflows using the core orchestration layer:
```bash
pip install -e .
```
### Security Layer: Sondera Integration
SuperClaude supports optional integration with **Sondera**, a security harness that validates Claude Code tool executions using LLM-powered policy enforcement and Cedar policy language.
**Important:** Sondera is **not bundled by default**. The standard installation (above) does not include it. Sondera must be explicitly installed when needed for production or compliance requirements.
📖 **[Full integration guide and architecture →](SONDERA_INTEGRATION.md)**
#### Default Install (Development)
The standard installation provides full SuperClaude functionality without security restrictions. This is ideal for:
- Local development and experimentation
- Trusted single-user environments
- Research and learning
- Scenarios where performance is critical
#### Production Setup (With Sondera)
For production deployments or high-security environments, install with Sondera:
```bash
./install-with-sondera.sh
```
**What Sondera provides:**
- Pre-execution validation of core Claude Code tools (Read, Write, Edit, Bash, etc.)
- LLM-powered intent analysis (ministral-3:14b-cloud)
- Safety validation (gpt-oss-safeguard:20b)
- Cedar policy enforcement engine
- Audit logging of all validated operations
**Prerequisites:**
- Rust toolchain (`cargo`)
- Ollama with models: `ministral-3:14b-cloud`, `gpt-oss-safeguard:20b` (~30GB)
- Cedar policy engine (embedded in harness)
- Unix socket support (Linux/macOS only; **Windows not supported**)
**Testing the integration:**
```bash
./test-sondera-integration.sh
```
**Tradeoffs:**
| Aspect | Without Sondera | With Sondera |
|--------|----------------|--------------|
| **Installation** | Simple (git clone) | Complex (Rust, Ollama, models) |
| **Performance** | Fast | Slower (LLM validation overhead) |
| **Security** | Trust-based | Policy-enforced |
| **Use Case** | Development, research | Production, compliance |
| **Maintenance** | Low | Higher (harness service) |
| **Platform** | Cross-platform | Linux/macOS only |
**Disabling Sondera:**
```bash
# Remove hook configuration
rm .claude/settings.local.json
# Stop harness service
# If using systemd (Linux):
systemctl --user stop sondera-harness
# If launched manually:
pkill -f sondera-harness
```
**Failure Mode:** When the harness service is unavailable, tool calls fail-closed (blocked by default) for safety. Configure fail-open mode in the harness settings if needed.
---
## Quick Start
### 1. Natural Language
```
User: Help me debug this authentication issue
Claude: [Selects communicator 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 19 agents, 24 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
```bash
# 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
```bash
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](crates/dashboard/README.md) for detailed usage guide.
---
## Agent System
### Core Agents (5)
High-priority generalists for common tasks:
| Agent | Triggers | Purpose |
|-------|----------|---------|
| architect | architecture, design, system, backend, frontend, api, database, infrastructure, ci/cd, deploy, fullstack | System design spanning architecture, infrastructure, backend, frontend, and deployment |
| developer | implement, create, build, develop, task, general, requirement, spec | Versatile implementation and multi-domain coordination |
| optimizer | optimize, performance, slow, refactor, improve, clean | Performance optimization and code quality improvement |
| guardian | security, vulnerability, test, validate, quality, qa | Security analysis and comprehensive testing |
| communicator | document, docs, explain, learn, tutorial, debug, investigate | Documentation, teaching, and debugging explanations |
### Traits (7)
Composable behavior modifiers that can be combined with any agent:
| Trait | Purpose | Example Usage |
|-------|---------|---------------|
| security-first | Prioritize security considerations | `@architect +security-first` |
| performance-first | Focus on optimization | `@optimizer +performance-first` |
| test-driven | Enforce TDD practices | `@developer +test-driven` |
| minimal-changes | Reduce change scope | `@optimizer +minimal-changes` |
| principles-enforced | Enforce SOLID, Let It Crash, KISS, Pure Functions | `@architect +principles-enforced` |
| mcp-pal-enabled | Enables PAL MCP tools (consensus, debug, codereview) | `@guardian +mcp-pal-enabled` |
| mcp-rube-enabled | Enables Rube MCP tools (500+ app integrations) | `@architect +mcp-rube-enabled` |
### Extensions (7)
Domain-specialist agents for deep expertise:
| Extension | Triggers | Specialty |
|-----------|----------|-----------|
| typescript-react-expert | typescript, ts, node, react, hooks, nextjs | TypeScript and React with strong typing |
| python-expert | python, django, fastapi, pytest | Python development with modern patterns |
| golang-expert | go, golang, goroutine | Go development with idiomatic patterns |
| rust-expert | rust, cargo, ownership | Rust with ownership patterns |
| kubernetes-specialist | kubernetes, k8s, helm, pod | Kubernetes orchestration |
| data-engineer | data, pipeline, etl, spark, kafka | Data engineering and pipelines |
| ml-engineer | ml, machine learning, pytorch, tensorflow | Machine learning systems |
### Agent Selection Algorithm
Agents are selected using weighted semantic matching:
```mermaid
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/>(5 available)"]
CORE -->|"No"| USE_EXT["Load Trait/Extension<br/>(14 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`):**
```yaml
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:
```markdown
---
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
```mermaid
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
```mermaid
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:
1. **Review Signal** - Within-loop review for quality improvement
2. **Final Validation Signal** - After successful completion (score >= 70)
---
## MCP Integrations
SuperClaude integrates with powerful MCP servers for enhanced capabilities:
```mermaid
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:
```mermaid
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 43 active Claude Code skills in `.claude/skills/`:
```mermaid
flowchart TB
subgraph Skills[".claude/skills/ (43 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 (26)"]
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-estimate"]
C10["sc-evaluate"]
C11["sc-explain"]
C12["sc-git"]
C13["sc-implement"]
C14["sc-improve"]
C15["sc-log-fix"]
C16["sc-mcp"]
C17["sc-pr-check"]
C18["sc-pr-fix"]
C19["sc-principles"]
C20["sc-push"]
C21["sc-readme"]
C22["sc-research"]
C23["sc-tdd"]
C24["sc-test"]
C25["sc-workflow"]
C26["sc-worktree"]
end
subgraph GitNexus["GitNexus Skills (6)"]
G1["gitnexus-cli"]
G2["gitnexus-exploring"]
G3["gitnexus-guide"]
G4["gitnexus-impact-analysis"]
G5["gitnexus-debugging"]
G6["gitnexus-refactoring"]
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 (226 lines)<br/>Loop orchestration"]
end
```
### Skill Types
| Type | Pattern | Count | Purpose |
|------|---------|-------|---------|
| Agent Skills | `agent-*` | 8 | Specialized personas for domains |
| Command Skills | `sc-*` | 26 | Structured workflow implementations |
| GitNexus Skills | `gitnexus-*` | 6 | Code intelligence, impact analysis, refactoring |
| 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:
1. **Semantic selection** - Claude automatically selects based on task context
2. **Direct reference** - `@agent-security-engineer` or `/sc-implement`
3. **Skill tool** - `Skill("agent-security-engineer")` for explicit invocation
---
## Quality System
SuperClaude uses a 9-dimension quality scoring system with automated actions:
```mermaid
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
python .claude/skills/sc-principles/scripts/validate_crash.py --scope-root . --json
```
### Pre-commit Integration
Add to `.pre-commit-config.yaml`:
```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
```python
@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:
```python
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:**
```python
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:**
```python
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
```python
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
```python
@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
```python
@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
```python
@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
```python
@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:
```yaml
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:
communicator: [debug, error, broken, "not working", explain]
optimizer: [refactor, "improve code", "clean up", optimize]
workflows:
default_workflow: [analyze, plan, implement, test, document]
debug_workflow: [reproduce, analyze, isolate, fix, verify]
```
Quality dimensions, model routing, and consensus policies are configured at runtime:
- Quality dimensions and weights are in `config/superclaud.yaml` (quality section)
- Model routing is handled by PAL MCP (`mcp__pal__listmodels` at runtime)
- Agent selection is filesystem-based (`agents/core/`, `agents/traits/`, `agents/extensions/`)
---
## Directory Structure
```
SuperClaude/
├── CLAUDE.md # Master system prompt
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version history
├── SONDERA_INTEGRATION.md # Sondera security layer integration guide
├── pyproject.toml # Python project config
├── install-with-sondera.sh # Automated Sondera installer
├── test-sondera-integration.sh # Sondera integration verification
│
├── .claude/
│ └── skills/ # 43 Claude Code skills
│ ├── agent-*/ # 8 agent persona skills
│ │ └── SKILL.md
│ ├── sc-*/ # 26 command skills
│ │ ├── SKILL.md
│ │ └── scripts/ # Optional tool implementations
│ ├── gitnexus/ # 6 GitNexus code intelligence skills
│ │ ├── gitnexus-cli/
│ │ ├── gitnexus-exploring/
│ │ ├── gitnexus-guide/
│ │ ├── gitnexus-impact-analysis/
│ │ ├── gitnexus-debugging/
│ │ └── gitnexus-refactoring/
│ ├── ask/ # Single-select questions
│ ├── ask-multi/ # Multi-select questions
│ └── learned/ # Auto-learned skills
│
├── agents/
│ ├── index.yaml # Agent registry
│ ├── core/ # 5 core agent prompts
│ │ ├── architect.md
│ │ ├── developer.md
│ │ ├── optimizer.md
│ │ ├── guardian.md
│ │ └── communicator.md
│ ├── traits/ # 7 composable trait prompts
│ │ ├── security-first.md
│ │ ├── performance-first.md
│ │ ├── test-driven.md
│ │ ├── minimal-changes.md
│ │ ├── principles-enforced.md
│ │ ├── mcp-pal-enabled.md
│ │ └── mcp-rube-enabled.md
│ ├── extensions/ # 7 domain specialist prompts
│ │ ├── typescript-react-expert.md
│ │ ├── python-expert.md
│ │ ├── golang-expert.md
│ │ ├── rust-expert.md
│ │ ├── kubernetes-specialist.md
│ │ ├── data-engineer.md
│ │ └── ml-engineer.md
│ └── DEPRECATED/ # Archived agents from previous versions (25 files)
│
├── commands/
│ ├── index.yaml # Command registry
│ ├── index.md # Command reference
│ ├── analyze.md
│ ├── implement.md
│ ├── test.md
│ └── ... # 16 command templates
│
├── config/
│ ├── superclaud.yaml # Main framework config (read by Rust crates)
│ └── schemas/ # JSON schemas for validation
│
├── 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/
│