{ "markdown": "# SuperClaude Framework\n\n

\n \"Version\"\n \"Agents\"\n \"Skills\"\n \"Commands\"\n \"Modes\"\n \"Core\"\n \"License\"\n \"Quality\n \"Coverage\"\n

\n\n**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.**\n\nSuperClaude 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.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Architecture](#architecture)\n- [Core Orchestration Layer](#core-orchestration-layer)\n- [Core API Reference](#core-api-reference)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Dashboard](#dashboard)\n- [Agent System](#agent-system)\n- [Command System](#command-system)\n- [Loop Orchestration](#loop-orchestration)\n- [MCP Integrations](#mcp-integrations)\n- [Skills System](#skills-system)\n- [Quality System](#quality-system)\n- [Quality Gates](#quality-gates)\n- [Metrics System](#metrics-system)\n- [Type System](#type-system)\n- [Configuration](#configuration)\n- [Directory Structure](#directory-structure)\n- [Creating Custom Agents](#creating-custom-agents)\n- [Contributing](#contributing)\n\n---\n\n## Overview\n\nSuperClaude is a meta-prompt framework that enhances Claude Code with:\n\n- **19 Specialized Agents**: 5 core + 7 composable traits + 7 domain extensions (tiered architecture)\n- **43 Active Skills**: 8 agent personas + 26 command workflows + 6 GitNexus code intelligence + 3 utility skills\n- **27 Structured Commands**: analyze, implement, test, design, document, and more\n- **6 Framework Modes**: normal, brainstorming, introspection, task_management, token_efficiency, orchestration\n- **MCP Integration**: PAL (11 tools), Rube (500+ apps via Composio, including web search)\n- **Quality Gates**: KISS, Purity, SOLID, and Let It Crash validators with iterative quality loop\n- **Core Orchestration**: ~2,800 lines Python for loop management, PAL integration, and skill learning\n- **Signal-Based Architecture**: Structured communication between components\n- **Metrics System**: Callback-based operational metrics with Prometheus/StatsD integration\n\n---\n\n## Key Features\n\n### Config-First Hybrid Architecture\n\nSuperClaude v7.0.0 is a **config-first hybrid framework**:\n\n- **Markdown Agent Personas**: Each agent is a self-contained markdown file with YAML frontmatter\n- **YAML Configuration**: 6 configuration files for agents, commands, quality, models, MCP, and framework settings\n- **Python Orchestration**: Loop orchestrator, quality assessment, PAL integration, and skill learning\n- **Portable**: Works with any Claude Code instance\n- **Extensible**: Add agents by creating markdown files\n\n### Why Config-First Hybrid?\n\n| Benefit | Description |\n|---------|-------------|\n| **Simplicity** | Core interface is markdown/YAML files |\n| **Portability** | Works with any Claude Code instance |\n| **Extensibility** | Add agents by creating markdown files |\n| **Maintainability** | Prompts are easy to refine and version |\n| **Version Control** | Easy to diff and review prompt changes |\n| **Advanced Workflows** | Python orchestration for quality gates and loop control |\n| **Safety** | Hard limits on iterations, termination detection |\n\n### Tiered Agent Architecture\n\n19 agents organized in a tiered system for composable expertise:\n\n| Tier | Count | Purpose | Examples |\n|------|-------|---------|----------|\n| **Core** | 5 | High-priority generalists | architect, developer, optimizer, guardian, communicator |\n| **Traits** | 7 | Composable modifiers | security-first, performance-first, test-driven, minimal-changes, principles-enforced, mcp-pal-enabled, mcp-rube-enabled |\n| **Extensions** | 7 | Domain specialists | typescript-react-expert, python-expert, golang-expert, rust-expert, kubernetes-specialist, data-engineer, ml-engineer |\n\n**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.\n\n### Command System\n\n27 structured commands with consistent patterns:\n\n```\n/sc:analyze - Static analysis, security review, performance bottlenecks\n/sc:implement - Feature implementation with quality gates and loop support\n/sc:test - Test execution, coverage analysis, and test generation\n/sc:design - Architecture and system design with ADRs\n/sc:document - Documentation generation and maintenance\n/sc:brainstorm - Creative ideation and exploration\n/sc:explain - Educational explanations and learning\n/sc:improve - Code improvement, refactoring, optimization\n/sc:build - Build system and compilation workflows\n/sc:git - Git operations, smart commits, branch management\n/sc:workflow - Multi-step task orchestration\n/sc:estimate - Effort estimation and planning\n/sc:cicd-setup - CI/CD workflow and pre-commit generation\n/sc:readme - Auto-update README.md from git diff with PAL consensus\n/sc:pr-fix - Create PR and iteratively fix CI failures\n/sc:pr-check - Pre-PR local CI validation with auto-fix\n/sc:log-fix - Log analysis and iterative bug fixing\n/sc:e2e - E2E testing (Playwright, Cypress, Selenium)\n/sc:tdd - Test-driven development with Red-Green-Refactor\n/sc:principles - KISS, Purity, SOLID, Let It Crash validation\n/sc:worktree - Git worktree management for parallel development\n/sc:mcp - MCP orchestration hub (PAL + Rube)\n/sc:code-review - Multi-model consensus code review\n/sc:research - Deep research with web search + consensus\n/sc:eda - Exploratory data analysis and visualization\n/sc:evaluate - LLM pipeline evaluation with judge scoring\n/sc:push - Multi-remote git push with selective filtering\n```\n\n---\n\n## Architecture\n\n### How SuperClaude Works\n\n```mermaid\nflowchart TB\n subgraph User[\"User Layer\"]\n REQ[\"User Request
/sc:implement --loop\"]\n end\n\n subgraph Runtime[\"Claude Code Runtime\"]\n CLAUDE[\"CLAUDE.md
Master System Prompt\"]\n SELECT[\"Agent Selection
Semantic Matching + Weights\"]\n EXEC[\"Task Execution\"]\n end\n\n subgraph Config[\"Configuration Layer\"]\n AGENTS[(\"agents/
5 core + 7 traits + 7 ext\")]\n COMMANDS[(\"commands/
16 templates\")]\n SKILLS[(\".claude/skills/
38 skills\")]\n YAML[(\"config/
6 YAML files\")]\n end\n\n subgraph Core[\"Core Orchestration (Python)\"]\n direction TB\n LOOP[\"LoopOrchestrator
Max 5 iterations\"]\n QUALITY[\"QualityAssessor
9 dimensions\"]\n TERM[\"Termination Detection
5 conditions\"]\n PALINT[\"PAL Integration
Signal generation\"]\n LEARN[\"Skill Learning
Pattern extraction\"]\n end\n\n subgraph MCP[\"MCP Integrations\"]\n PAL[\"PAL MCP
11 tools\"]\n RUBE[\"Rube MCP
500+ apps\"]\n end\n\n REQ --> CLAUDE\n CLAUDE --> SELECT\n SELECT --> AGENTS\n SELECT --> COMMANDS\n SELECT --> EXEC\n EXEC --> SKILLS\n EXEC <--> Core\n LOOP --> QUALITY\n QUALITY --> TERM\n TERM --> PALINT\n PALINT <--> PAL\n EXEC <--> RUBE\n Config --> Runtime\n\n style User fill:#e8f5e9\n style Runtime fill:#e3f2fd\n style Config fill:#fff3e0\n style Core fill:#fce4ec\n style MCP fill:#f3e5f5\n```\n\n### File-Based Configuration\n\nSuperClaude uses a layered file-based architecture:\n\n1. **CLAUDE.md** - Master system prompt loaded by Claude Code\n2. **agents/index.yaml** - Agent registry with triggers, categories, and selection weights\n3. **agents/core/*.md** - 5 core agent persona prompts\n4. **agents/traits/*.md** - 7 composable behavior modifier prompts\n5. **agents/extensions/*.md** - 7 domain specialist prompts\n6. **commands/index.yaml** - Command registry with flags and aliases\n7. **commands/*.md** - 16 command templates\n8. **config/*.yaml** - 6 configuration files\n9. **core/*.py** - Python orchestration modules\n10. **mcp/*.md** - MCP integration guides\n11. **.claude/skills/** - 43 Claude Code skills\n\n---\n\n## Core Orchestration Layer\n\nSuperClaude v7.0.0 includes a Python orchestration layer in `core/` for advanced workflows:\n\n### Modules\n\n| Module | Lines | Purpose |\n|--------|-------|---------|\n| `loop_orchestrator.py` | ~410 | Manages iterative improvement with quality gates |\n| `quality_assessment.py` | ~265 | 9-dimension quality scoring with evidence collection |\n| `pal_integration.py` | ~175 | PAL MCP signal generation (review, debug, validation) |\n| `types.py` | ~150 | Core type definitions (TerminationReason, LoopConfig, etc.) |\n| `metrics.py` | ~225 | Callback-based metrics protocol and emitters |\n| `skill_learning_integration.py` | ~550 | Skill extraction from successful executions |\n| `skill_persistence.py` | ~980 | Skill storage, retrieval, and promotion |\n\n### LoopOrchestrator\n\nThe `LoopOrchestrator` class manages the `--loop` flag behavior:\n\n```mermaid\nstateDiagram-v2\n [*] --> Initialize\n\n state \"Loop Execution\" as Loop {\n [*] --> ExecuteSkill\n ExecuteSkill --> CollectEvidence\n CollectEvidence --> AssessQuality\n AssessQuality --> CheckThreshold\n\n state CheckThreshold <>\n CheckThreshold --> Success: score >= 70\n CheckThreshold --> CheckTermination: score < 70\n\n state CheckTermination <>\n CheckTermination --> MaxIterations: iteration >= max\n CheckTermination --> Timeout: wall-clock exceeded\n CheckTermination --> Error: skill execution failure\n CheckTermination --> Continue: OK to iterate\n\n Continue --> PALReview: Generate signal\n PALReview --> PrepareNext\n PrepareNext --> ExecuteSkill\n }\n\n Initialize --> Loop\n\n Success --> FinalValidation: PAL final signal\n MaxIterations --> [*]\n Timeout --> [*]\n Error --> [*]\n FinalValidation --> [*]\n\n note right of Initialize\n Triggered by /sc:implement --loop\n end note\n```\n\n**Key Features:**\n\n- **Safety**: Hard maximum of 5 iterations (cannot be overridden via `hard_max_iterations`)\n- **Quality-Driven**: Stops when score >= 70 (configurable threshold)\n- **PAL Integration**: Generates review signals within loop for external validation\n- **Signal-Based**: Communicates with Claude Code via structured signals\n- **Evidence Collection**: Tracks changes, tests, lint results, and file modifications\n\n### Signal Architecture\n\nThe orchestrator uses structured signals for component communication:\n\n```python\n# Skill invocation signal\n{\n \"action\": \"execute_skill\",\n \"skill\": \"sc-implement\",\n \"parameters\": {\n \"task\": \"description\",\n \"improvements_needed\": [...],\n \"iteration\": 2,\n \"focus\": \"remediation\" # \"implementation\" for iter 0\n },\n \"collect\": [\"changes\", \"tests\", \"lint\", \"changed_files\"],\n \"context\": {...}\n}\n```\n\n---\n\n## Core API Reference\n\nComplete API documentation for the SuperClaude Python orchestration layer (`core/` module).\n\n### Module Exports\n\n```python\nfrom core import (\n # Types\n TerminationReason, # Enum: 5 loop termination conditions\n LoopConfig, # Dataclass: Loop configuration\n LoopResult, # Dataclass: Final loop result\n IterationResult, # Dataclass: Single iteration result\n QualityAssessment, # Dataclass: Quality score + improvements\n # Classes\n QualityAssessor, # Quality scoring wrapper\n PALReviewSignal, # PAL MCP signal generator\n LoopOrchestrator, # Main loop controller\n)\n```\n\n### LoopOrchestrator\n\nThe main controller for `--loop` functionality.\n\n```python\nclass LoopOrchestrator:\n \"\"\"\n Lightweight agentic loop orchestrator.\n\n Thread Safety: NOT thread-safe. Create new instance per task/thread.\n \"\"\"\n\n def __init__(\n self,\n config: Optional[LoopConfig] = None,\n logger: Optional[logging.Logger] = None,\n metrics_emitter: Optional[MetricsEmitter] = None,\n ) -> None:\n \"\"\"\n Initialize the loop orchestrator.\n\n Args:\n config: Loop configuration (defaults to LoopConfig())\n logger: Logger instance for structured logging\n metrics_emitter: Callback for operational metrics\n \"\"\"\n\n def run(\n self,\n initial_context: dict[str, Any],\n skill_invoker: Callable[[dict[str, Any]], dict[str, Any]],\n ) -> LoopResult:\n \"\"\"\n Execute the agentic loop.\n\n Args:\n initial_context: Task context with:\n - task: Description of what to implement\n - improvements_needed: Initial improvements (optional)\n - changed_files: Already modified files (optional)\n skill_invoker: Function that invokes Skills via Claude Code\n Should return dict with: changes, tests, lint, changed_files\n\n Returns:\n LoopResult with final output, assessment, and history\n \"\"\"\n```\n\n**Usage Example:**\n\n```python\nfrom core import LoopOrchestrator, LoopConfig\n\nconfig = LoopConfig(\n max_iterations=3,\n quality_threshold=70.0,\n pal_review_enabled=True,\n)\n\norchestrator = LoopOrchestrator(config)\n\ndef my_skill_invoker(context):\n return {\n \"changes\": [...],\n \"tests\": {\"ran\": True, \"passed\": 10, \"failed\": 0},\n \"lint\": {\"ran\": True, \"errors\": 0},\n \"changed_files\": [\"src/module.py\"],\n }\n\nresult = orchestrator.run(\n initial_context={\"task\": \"Implement user authentication\"},\n skill_invoker=my_skill_invoker,\n)\n\nprint(f\"Final score: {result.final_assessment.overall_score}\")\nprint(f\"Termination: {result.termination_reason.value}\")\n```\n\n### QualityAssessor\n\nWraps `evidence_gate.py` for quality scoring.\n\n```python\nclass QualityAssessor:\n def __init__(self, threshold: float = 70.0) -> None\n def assess(self, context: dict[str, Any]) -> QualityAssessment\n```\n\n**Scoring Breakdown (Fallback Mode):**\n\n| Component | Points | Condition |\n|-----------|--------|-----------|\n| File changes | 30 | Any changes detected |\n| Tests executed | 25 | Tests ran |\n| Tests passing | 20 | All tests pass |\n| Lint clean | 15 | No lint errors |\n| Coverage | 10 | 80%+ coverage |\n\n### PALReviewSignal\n\nGenerates signals for PAL MCP invocation.\n\n```python\nclass PALReviewSignal:\n TOOL_CODEREVIEW = \"mcp__pal__codereview\"\n TOOL_DEBUG = \"mcp__pal__debug\"\n TOOL_THINKDEEP = \"mcp__pal__thinkdeep\"\n TOOL_CONSENSUS = \"mcp__pal__consensus\"\n\n @staticmethod\n def generate_review_signal(\n iteration: int,\n changed_files: list[str],\n quality_assessment: QualityAssessment,\n model: str = \"gpt-5\",\n review_type: str = \"auto\", # auto/quick/full\n ) -> dict[str, Any]\n\n @staticmethod\n def generate_debug_signal(\n iteration: int,\n termination_reason: str,\n score_history: list[float],\n model: str = \"gpt-5\",\n ) -> dict[str, Any]\n\n @staticmethod\n def generate_final_validation_signal(\n changed_files: list[str],\n quality_assessment: QualityAssessment,\n iteration_count: int,\n model: str = \"gpt-5\",\n ) -> dict[str, Any]\n```\n\n### Helper Functions\n\n```python\n# Create skill invocation signal\ndef create_skill_invoker_signal(context: dict[str, Any]) -> dict[str, Any]\n\n# Merge PAL feedback into context\ndef incorporate_pal_feedback(\n context: dict[str, Any],\n pal_result: dict[str, Any],\n) -> dict[str, Any]\n\n# Convenience function for quality assessment\ndef assess_quality(\n context: dict[str, Any],\n threshold: float = 70.0\n) -> QualityAssessment\n```\n\n---\n\n## Installation\n\n### Option 1: Clone Repository\n\n```bash\ngit clone https://github.com/Tony363/SuperClaude.git\ncd SuperClaude\n```\n\n### Option 2: Add as Git Submodule\n\n```bash\ngit submodule add https://github.com/Tony363/SuperClaude.git SuperClaude\n```\n\n### Setup Claude Code\n\nAdd to your project's `.claude/settings.json`:\n\n```json\n{\n \"systemPromptFiles\": [\"SuperClaude/CLAUDE.md\"]\n}\n```\n\nOr copy `CLAUDE.md` to your project root.\n\n### Optional: Python Dependencies\n\nFor advanced workflows using the core orchestration layer:\n\n```bash\npip install -e .\n```\n\n### Security Layer: Sondera Integration\n\nSuperClaude supports optional integration with **Sondera**, a security harness that validates Claude Code tool executions using LLM-powered policy enforcement and Cedar policy language.\n\n**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.\n\nšŸ“– **[Full integration guide and architecture ā†’](SONDERA_INTEGRATION.md)**\n\n#### Default Install (Development)\n\nThe standard installation provides full SuperClaude functionality without security restrictions. This is ideal for:\n- Local development and experimentation\n- Trusted single-user environments\n- Research and learning\n- Scenarios where performance is critical\n\n#### Production Setup (With Sondera)\n\nFor production deployments or high-security environments, install with Sondera:\n\n```bash\n./install-with-sondera.sh\n```\n\n**What Sondera provides:**\n- Pre-execution validation of core Claude Code tools (Read, Write, Edit, Bash, etc.)\n- LLM-powered intent analysis (ministral-3:14b-cloud)\n- Safety validation (gpt-oss-safeguard:20b)\n- Cedar policy enforcement engine\n- Audit logging of all validated operations\n\n**Prerequisites:**\n- Rust toolchain (`cargo`)\n- Ollama with models: `ministral-3:14b-cloud`, `gpt-oss-safeguard:20b` (~30GB)\n- Cedar policy engine (embedded in harness)\n- Unix socket support (Linux/macOS only; **Windows not supported**)\n\n**Testing the integration:**\n\n```bash\n./test-sondera-integration.sh\n```\n\n**Tradeoffs:**\n\n| Aspect | Without Sondera | With Sondera |\n|--------|----------------|--------------|\n| **Installation** | Simple (git clone) | Complex (Rust, Ollama, models) |\n| **Performance** | Fast | Slower (LLM validation overhead) |\n| **Security** | Trust-based | Policy-enforced |\n| **Use Case** | Development, research | Production, compliance |\n| **Maintenance** | Low | Higher (harness service) |\n| **Platform** | Cross-platform | Linux/macOS only |\n\n**Disabling Sondera:**\n\n```bash\n# Remove hook configuration\nrm .claude/settings.local.json\n\n# Stop harness service\n# If using systemd (Linux):\nsystemctl --user stop sondera-harness\n\n# If launched manually:\npkill -f sondera-harness\n```\n\n**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.\n\n---\n\n## Quick Start\n\n### 1. Natural Language\n\n```\nUser: Help me debug this authentication issue\nClaude: [Selects communicator agent, applies debugging methodology]\n```\n\n### 2. Using Commands\n\n```\nUser: /sc:analyze src/auth/\nClaude: [Runs comprehensive static analysis, security review, quality assessment]\n```\n\n### 3. Specifying Agents\n\n```\nUser: @python-expert Review this Flask application\nClaude: [Uses Python expert persona with framework-specific knowledge]\n```\n\n### 4. Iterative Improvement\n\n```\nUser: /sc:implement new user registration --loop\nClaude: [Implements with quality gates, iterates until score >= 70 or max 5 iterations]\n```\n\n### 5. Using MCP Tools\n\nWith PAL MCP configured:\n```\nUser: Use PAL to review this code\nClaude: [Invokes mcp__pal__codereview for multi-model code review]\n```\n\n---\n\n## Dashboard\n\nSuperClaude includes a native desktop dashboard for visualizing and controlling the agentic framework.\n\n### Features\n\n- **Feature Inventory** - Browse all 19 agents, 24 commands, 38 skills, and 6 behavioral modes\n- **Live Monitor** - Real-time execution tracking with event streaming, heartbeat indicator, and quality score visualization\n- **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)\n- **Execution Tree** - Visual tree of iterations, tool calls, and subagent spawns built from streaming events\n- **Diff Viewer** - Inline diff display for Edit/Write tool invocations showing before/after changes\n- **Historical Metrics** - View past session data, event timelines, and performance trends\n\n### Quick Start\n\n```bash\n# Terminal 1: Start the daemon\ncargo run -p superclaude-daemon\n\n# Terminal 2: Launch the dashboard\ncd crates/dashboard\ncargo tauri dev\n```\n\nThe dashboard window will open showing the Feature Inventory page. Navigate using the sidebar to access Monitor, Control, and History views.\n\n### Building for Production\n\n```bash\ncd crates/dashboard\ncargo tauri build\n\n# Output packages:\n# - Debian/Ubuntu: target/release/bundle/deb/superclaude-dashboard_*.deb\n# - Universal Linux: target/release/bundle/appimage/superclaude-dashboard_*.AppImage\n```\n\n### System Requirements\n\n- **OS**: Linux (tested on Manjaro/Arch, Ubuntu 22.04+)\n- **Dependencies**: webkit2gtk-4.1, libappindicator-gtk3, librsvg\n- **Runtime**: SuperClaude daemon running on port 50051\n\nSee [Dashboard README](crates/dashboard/README.md) for detailed usage guide.\n\n---\n\n## Agent System\n\n### Core Agents (5)\n\nHigh-priority generalists for common tasks:\n\n| Agent | Triggers | Purpose |\n|-------|----------|---------|\n| architect | architecture, design, system, backend, frontend, api, database, infrastructure, ci/cd, deploy, fullstack | System design spanning architecture, infrastructure, backend, frontend, and deployment |\n| developer | implement, create, build, develop, task, general, requirement, spec | Versatile implementation and multi-domain coordination |\n| optimizer | optimize, performance, slow, refactor, improve, clean | Performance optimization and code quality improvement |\n| guardian | security, vulnerability, test, validate, quality, qa | Security analysis and comprehensive testing |\n| communicator | document, docs, explain, learn, tutorial, debug, investigate | Documentation, teaching, and debugging explanations |\n\n### Traits (7)\n\nComposable behavior modifiers that can be combined with any agent:\n\n| Trait | Purpose | Example Usage |\n|-------|---------|---------------|\n| security-first | Prioritize security considerations | `@architect +security-first` |\n| performance-first | Focus on optimization | `@optimizer +performance-first` |\n| test-driven | Enforce TDD practices | `@developer +test-driven` |\n| minimal-changes | Reduce change scope | `@optimizer +minimal-changes` |\n| principles-enforced | Enforce SOLID, Let It Crash, KISS, Pure Functions | `@architect +principles-enforced` |\n| mcp-pal-enabled | Enables PAL MCP tools (consensus, debug, codereview) | `@guardian +mcp-pal-enabled` |\n| mcp-rube-enabled | Enables Rube MCP tools (500+ app integrations) | `@architect +mcp-rube-enabled` |\n\n### Extensions (7)\n\nDomain-specialist agents for deep expertise:\n\n| Extension | Triggers | Specialty |\n|-----------|----------|-----------|\n| typescript-react-expert | typescript, ts, node, react, hooks, nextjs | TypeScript and React with strong typing |\n| python-expert | python, django, fastapi, pytest | Python development with modern patterns |\n| golang-expert | go, golang, goroutine | Go development with idiomatic patterns |\n| rust-expert | rust, cargo, ownership | Rust with ownership patterns |\n| kubernetes-specialist | kubernetes, k8s, helm, pod | Kubernetes orchestration |\n| data-engineer | data, pipeline, etl, spark, kafka | Data engineering and pipelines |\n| ml-engineer | ml, machine learning, pytorch, tensorflow | Machine learning systems |\n\n### Agent Selection Algorithm\n\nAgents are selected using weighted semantic matching:\n\n```mermaid\nflowchart TD\n START[\"User Request\"] --> PARSE[\"Parse Keywords & Context\"]\n\n PARSE --> TRIGGER{\"Exact Trigger
Match?\"}\n TRIGGER -->|\"Yes (0.35)\"| CORE{\"Core
Agent?\"}\n TRIGGER -->|\"No\"| CATEGORY{\"Category
Match?\"}\n\n CORE -->|\"Yes\"| USE_CORE[\"Load Core Agent
(5 available)\"]\n CORE -->|\"No\"| USE_EXT[\"Load Trait/Extension
(14 available)\"]\n\n CATEGORY -->|\"Yes (0.25)\"| CAT_SELECT[\"Select from Category\"]\n CATEGORY -->|\"No\"| DESC{\"Description
Match?\"}\n\n DESC -->|\"Yes (0.20)\"| DESC_SELECT[\"Score by Description\"]\n DESC -->|\"No\"| TOOL{\"Tool
Match?\"}\n\n TOOL -->|\"Yes (0.20)\"| TOOL_SELECT[\"Match Required Tools\"]\n TOOL -->|\"No\"| FILE{\"File
Context?\"}\n\n FILE -->|\".py files\"| PYTHON[\"Python Expert\"]\n FILE -->|\".ts/.js\"| TS[\"TypeScript Pro\"]\n FILE -->|\".go files\"| GO[\"Golang Pro\"]\n FILE -->|\".rs files\"| RUST[\"Rust Engineer\"]\n FILE -->|\"Other\"| GENERAL[\"General Purpose\"]\n\n USE_CORE --> EXEC[\"Execute Task\"]\n USE_EXT --> EXEC\n CAT_SELECT --> EXEC\n DESC_SELECT --> EXEC\n TOOL_SELECT --> EXEC\n PYTHON --> EXEC\n TS --> EXEC\n GO --> EXEC\n RUST --> EXEC\n GENERAL --> EXEC\n\n style START fill:#4caf50,color:#fff\n style EXEC fill:#2196f3,color:#fff\n```\n\n**Selection Weights (from `select_agent.py`):**\n\n```yaml\nselection:\n weights:\n keyword_match: 0.35 # Keyword/trigger matching (highest priority)\n category_match: 0.25 # Domain/category alignment\n task_match: 0.20 # Task text matching\n file_patterns: 0.10 # File pattern matching\n priority_bonus: 0.10 # Tier priority bonus\n\n thresholds:\n minimum_score: 0.3 # Minimum match score\n confidence_levels:\n excellent: 0.7 # >= 0.7 score\n high: 0.5 # >= 0.5 score\n medium: 0.3 # >= 0.3 score\n```\n\n---\n\n## Command System\n\nCommands provide structured execution patterns with optional quality gates.\n\n### Command Format\n\nEach command is a markdown file with YAML frontmatter:\n\n```markdown\n---\nname: implement\ndescription: Feature implementation with quality gates\naliases: [build, create, develop]\nflags: [--loop, --tests, --docs, --pal-review, --consensus]\nevidence_required: true\n---\n\n# Implement Command\n\n[Structured implementation methodology...]\n```\n\n### Command Execution Flow\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant C as Claude Code\n participant CMD as Command Template\n participant A as Agent Persona\n participant O as LoopOrchestrator\n participant Q as QualityAssessor\n participant P as PAL MCP\n\n U->>C: /sc:implement feature --loop\n C->>CMD: Load implement.md template\n CMD->>A: Activate relevant personas\n C->>O: Initialize loop (max 5 iter)\n\n rect rgb(230, 245, 255)\n note over O,P: Iterative Improvement Loop\n loop Iteration 0..N (max 5)\n O->>A: Execute with context\n A-->>O: Return evidence\n O->>Q: Assess quality\n Q-->>O: Score + improvements\n\n alt Score >= 70\n O-->>C: QUALITY_MET\n else Oscillation/Stagnation\n O->>P: Generate debug signal\n O-->>C: Terminate\n else Continue\n O->>P: Generate review signal\n P-->>O: PAL feedback\n O->>A: Next iteration\n end\n end\n end\n\n O->>P: Final validation signal\n P-->>O: Validation result\n O-->>C: LoopResult\n C->>U: Implementation + quality report\n```\n\n### Available Commands\n\n| Command | Aliases | Evidence | Key Flags |\n|---------|---------|----------|-----------|\n| analyze | analyse, check, inspect | No | --security, --deep, --performance |\n| implement | build, create, develop | Yes | --loop, --pal-review, --consensus, --tests |\n| test | verify, check | Yes | --coverage, --unit, --integration |\n| design | architect, plan | No | --adr, --diagram, --review |\n| document | docs, readme | No | --api, --readme, --changelog |\n| brainstorm | ideate, explore | No | --divergent, --constraints |\n| explain | teach, learn, understand | No | --verbose, --simple, --diagram |\n| improve | refactor, enhance, optimize | Yes | --performance, --readability, --security |\n| build | compile, package | No | --watch, --production, --docker |\n| git | commit, branch | No | --commit, --pr, --branch |\n| workflow | pipeline, sequence | No | --spec, --parallel |\n| estimate | scope, size | No | --breakdown, --risks |\n| cicd-setup | cicd-init, pipeline-setup | No | --lang, --minimal, --full |\n| readme | readme-sync, doc-sync | No | --base, --preview, --consensus |\n| pr-fix | prfix, cifix, fix-pr | Yes | --branch, --auto-fix, --max-fix-attempts |\n| pr-check | preflight, prepr | No | --fix, --strict |\n| log-fix | logfix, debug-logs | No | --source, --pattern |\n| e2e | e2e-test, browser-test | Yes | --browser, --headed, --trace |\n| tdd | test-driven | Yes | --cycle, --framework |\n| principles | validate-principles | No | --kiss, --solid, --purity, --crash |\n| worktree | git-worktree | No | --name, --branch |\n| mcp | mcp-orchestrate | No | --pal, --rube, --consensus |\n| code-review | review, cr | No | --models, --consensus |\n| research | deep-research | No | --depth, --sources |\n| eda | data-analysis | No | --format, --output |\n| evaluate | eval, judge | No | --dataset, --judge-model |\n| push | git-push | No | --remotes, --exclude |\n\n---\n\n## Loop Orchestration\n\nThe loop orchestration system manages iterative improvement workflows with safety guarantees.\n\n### Termination Conditions\n\n```mermaid\nflowchart TD\n START[\"Start Loop Iteration 0\"] --> EXEC[\"Execute Skill\"]\n EXEC --> EVIDENCE[\"Collect Evidence\"]\n EVIDENCE --> ASSESS[\"Assess Quality\"]\n ASSESS --> SCORE{\"Score >= 70?\"}\n\n SCORE -->|\"Yes\"| QUALITY_MET[\"QUALITY_MET\"]\n SCORE -->|\"No\"| MAX{\"Iteration >= max?\"}\n\n MAX -->|\"Yes\"| MAX_ITER[\"MAX_ITERATIONS\"]\n MAX -->|\"No\"| TMOUT{\"Timeout?\"}\n\n TMOUT -->|\"Yes\"| TIMEOUT_TERM[\"TIMEOUT\"]\n TMOUT -->|\"No\"| PAL[\"Generate PAL Review Signal\"]\n PAL --> FEEDBACK[\"Incorporate Feedback\"]\n FEEDBACK --> NEXT[\"Prepare Next Context\"]\n NEXT --> EXEC\n\n QUALITY_MET --> FINAL[\"Final PAL Validation Signal\"]\n\n FINAL --> DONE[\"Return LoopResult\"]\n MAX_ITER --> DONE\n TIMEOUT_TERM --> DONE\n\n style QUALITY_MET fill:#4caf50,color:#fff\n style MAX_ITER fill:#ff9800,color:#fff\n style TIMEOUT_TERM fill:#f44336,color:#fff\n```\n\n### All 5 Termination Reasons\n\n| Reason | Trigger | PAL Signal |\n|--------|---------|------------|\n| `QUALITY_MET` | Score >= threshold (70) | Final validation |\n| `MAX_ITERATIONS` | Iteration >= 5 (hard cap) | None |\n| `ERROR` | Skill execution failure | None |\n| `HUMAN_ESCALATION` | Requires human review | None |\n| `TIMEOUT` | Wall-clock time exceeded | None |\n\n### PAL Signal Types\n\nThe loop orchestrator generates two types of PAL signals:\n\n1. **Review Signal** - Within-loop review for quality improvement\n2. **Final Validation Signal** - After successful completion (score >= 70)\n\n---\n\n## MCP Integrations\n\nSuperClaude integrates with powerful MCP servers for enhanced capabilities:\n\n```mermaid\nflowchart TB\n subgraph PAL[\"PAL MCP - 11 Collaborative Tools\"]\n P1[\"chat\"] & P2[\"thinkdeep\"] & P3[\"debug\"]\n P4[\"planner\"] & P5[\"precommit\"]\n P6[\"codereview\"] & P7[\"consensus\"] & P8[\"challenge\"]\n P9[\"apilookup\"] & P10[\"listmodels\"] & P11[\"clink\"]\n end\n\n subgraph Rube[\"Rube MCP - 500+ App Integrations (11 tools)\"]\n R1[\"SEARCH_TOOLS\"] & R2[\"GET_TOOL_SCHEMAS\"] & R3[\"MULTI_EXECUTE_TOOL\"]\n R4[\"REMOTE_BASH_TOOL\"] & R5[\"REMOTE_WORKBENCH\"]\n R6[\"FIND_RECIPE\"] & R7[\"EXECUTE_RECIPE\"] & R8[\"GET_RECIPE_DETAILS\"]\n R9[\"CREATE_UPDATE_RECIPE\"] & R10[\"MANAGE_CONNECTIONS\"] & R11[\"MANAGE_RECIPE_SCHEDULE\"]\n end\n\n TASK[\"SuperClaude Task\"] --> PAL\n TASK --> Rube\n\n style PAL fill:#e3f2fd\n style Rube fill:#fce4ec\n```\n\n### PAL MCP (11 Tools)\n\nCollaborative intelligence for code review, debugging, and multi-model consensus:\n\n| Tool | Purpose | Use Case |\n|------|---------|----------|\n| `mcp__pal__chat` | General collaborative thinking | Brainstorming, second opinions |\n| `mcp__pal__thinkdeep` | Multi-stage investigation | Complex problem analysis |\n| `mcp__pal__planner` | Interactive sequential planning | Project planning with revision |\n| `mcp__pal__consensus` | Multi-model decision making | Architecture decisions, evaluations |\n| `mcp__pal__codereview` | Systematic code review | Quality assessment, security review |\n| `mcp__pal__precommit` | Git change validation | Pre-commit checks, change impact |\n| `mcp__pal__debug` | Root cause analysis | Complex debugging, issue diagnosis |\n| `mcp__pal__challenge` | Critical thinking | Push back on assumptions |\n| `mcp__pal__apilookup` | API documentation lookup | Current SDK/API information |\n| `mcp__pal__listmodels` | List available models | Model selection and capabilities |\n| `mcp__pal__clink` | External AI CLI linking | Connect to Gemini, Codex, etc. |\n\n### Rube MCP (Composio)\n\nSession-based workflow automation with 500+ app integrations:\n\n```mermaid\nsequenceDiagram\n participant C as Claude Code\n participant R as Rube MCP\n participant A as External App (Slack, GitHub, etc.)\n\n C->>R: RUBE_SEARCH_TOOLS
{session: {generate_id: true}, queries: [...]}\n R-->>C: session_id + available tools + execution plan\n\n C->>R: RUBE_MULTI_EXECUTE_TOOL
{session_id, tools: [...], memory: {...}}\n R->>A: Execute tool (e.g., SLACK_SEND_MESSAGE)\n A-->>R: Tool result\n R-->>C: Results + updated memory\n\n opt Complex Workflow\n C->>R: RUBE_CREATE_PLAN
{session_id, use_case, difficulty}\n R-->>C: Detailed execution plan\n end\n\n opt Recipe Execution\n C->>R: RUBE_FIND_RECIPE
{query: \"...\"}\n R-->>C: Matching recipes with recipe_id\n C->>R: RUBE_EXECUTE_RECIPE
{recipe_id, input_data}\n R-->>C: Recipe execution result\n end\n```\n\n**Connected Services:**\n| Category | Examples |\n|----------|----------|\n| Development | GitHub, GitLab, Bitbucket, Linear, Jira |\n| Communication | Slack, Discord, Teams, Email |\n| Productivity | Notion, Asana, Trello, Airtable |\n| Google Workspace | Gmail, Calendar, Drive, Sheets, Docs |\n| Microsoft | Outlook, Teams, OneDrive, SharePoint |\n| Social | X (Twitter), LinkedIn, Meta apps |\n| AI Tools | Various AI services and APIs |\n\n### Web Search (via Rube MCP)\n\nWeb search capabilities are available through Rube MCP's LINKUP_SEARCH tool:\n- Deep or standard search depth\n- Sourced answers with citations and URLs\n- Accessed via `LINKUP_SEARCH` tool in `RUBE_MULTI_EXECUTE_TOOL`\n\n---\n\n## Skills System\n\nSuperClaude includes 43 active Claude Code skills in `.claude/skills/`:\n\n```mermaid\nflowchart TB\n subgraph Skills[\".claude/skills/ (43 active)\"]\n subgraph Agent[\"Agent Skills (8)\"]\n A1[\"agent-data-engineer\"]\n A2[\"agent-fullstack-developer\"]\n A3[\"agent-kubernetes-specialist\"]\n A4[\"agent-ml-engineer\"]\n A5[\"agent-performance-engineer\"]\n A6[\"agent-react-specialist\"]\n A7[\"agent-security-engineer\"]\n A8[\"agent-technical-writer\"]\n end\n\n subgraph Command[\"Command Skills (26)\"]\n C1[\"sc-analyze\"]\n C2[\"sc-brainstorm\"]\n C3[\"sc-build\"]\n C4[\"sc-cicd-setup\"]\n C5[\"sc-code-review\"]\n C6[\"sc-design\"]\n C7[\"sc-document\"]\n C8[\"sc-e2e\"]\n C9[\"sc-estimate\"]\n C10[\"sc-evaluate\"]\n C11[\"sc-explain\"]\n C12[\"sc-git\"]\n C13[\"sc-implement\"]\n C14[\"sc-improve\"]\n C15[\"sc-log-fix\"]\n C16[\"sc-mcp\"]\n C17[\"sc-pr-check\"]\n C18[\"sc-pr-fix\"]\n C19[\"sc-principles\"]\n C20[\"sc-push\"]\n C21[\"sc-readme\"]\n C22[\"sc-research\"]\n C23[\"sc-tdd\"]\n C24[\"sc-test\"]\n C25[\"sc-workflow\"]\n C26[\"sc-worktree\"]\n end\n\n subgraph GitNexus[\"GitNexus Skills (6)\"]\n G1[\"gitnexus-cli\"]\n G2[\"gitnexus-exploring\"]\n G3[\"gitnexus-guide\"]\n G4[\"gitnexus-impact-analysis\"]\n G5[\"gitnexus-debugging\"]\n G6[\"gitnexus-refactoring\"]\n end\n\n subgraph Utility[\"Utility Skills (3)\"]\n U1[\"ask
(single-select)\"]\n U2[\"ask-multi
(multi-select)\"]\n U3[\"learned
(auto-learned)\"]\n end\n end\n\n subgraph Structure[\"Skill File Structure\"]\n direction LR\n SKILL[\"SKILL.md
(AI-facing interface)\"]\n SCRIPTS[\"scripts/
(Tool implementations)\"]\n end\n\n Skills --> Structure\n\n subgraph ScriptDetail[\"sc-implement/scripts/ (5 tools)\"]\n S1[\"select_agent.py (551 lines)
Weighted agent selection\"]\n S2[\"run_tests.py (344 lines)
Test framework detection\"]\n S3[\"evidence_gate.py (256 lines)
Quality validation\"]\n S4[\"skill_learn.py (466 lines)
Skill extraction\"]\n S5[\"loop_entry.py (226 lines)
Loop orchestration\"]\n end\n```\n\n### Skill Types\n\n| Type | Pattern | Count | Purpose |\n|------|---------|-------|---------|\n| Agent Skills | `agent-*` | 8 | Specialized personas for domains |\n| Command Skills | `sc-*` | 26 | Structured workflow implementations |\n| GitNexus Skills | `gitnexus-*` | 6 | Code intelligence, impact analysis, refactoring |\n| Utility Skills | `ask`, `ask-multi`, `learned` | 3 | User interaction and learning |\n\n### Skill Architecture\n\nEach skill follows a standard structure:\n\n```\n.claude/skills/agent-security-engineer/\nā””ā”€ā”€ SKILL.md # AI-facing interface (what Claude reads)\n\n.claude/skills/sc-implement/\nā”œā”€ā”€ SKILL.md # Command interface\nā””ā”€ā”€ scripts/ # Optional tool implementations\n ā”œā”€ā”€ select_agent.py # Weighted agent selection algorithm\n ā”œā”€ā”€ run_tests.py # Test framework detection and execution\n ā”œā”€ā”€ evidence_gate.py # Quality validation (production_ready/acceptable/needs_review)\n ā”œā”€ā”€ skill_learn.py # Skill extraction from successful executions\n ā””ā”€ā”€ loop_entry.py # Loop orchestration entry point\n```\n\n**Important Distinction:**\n- `SKILL.md` = The interface Claude reads to understand when/how to invoke\n- `scripts/*.py` = Backend implementations executed by the host system\n\nThis follows standard agentic patterns: config-first architecture means the AI-facing interface is pure configuration, while Python handles orchestration.\n\n### Skill Learning System\n\nThe `learned/` skill directory stores patterns extracted from successful executions:\n\n- **Extraction**: `skill_learn.py` extracts patterns from successful `--loop` executions\n- **Promotion**: Skills promoted when quality score >= 85.0 and success rate >= 70%\n- **Retrieval**: Auto-retrieved based on task keywords, file types, domain context\n- **Metadata**: Tracks provenance (session ID, timestamp, quality progression)\n\n### Using Skills\n\nSkills are invoked via:\n1. **Semantic selection** - Claude automatically selects based on task context\n2. **Direct reference** - `@agent-security-engineer` or `/sc-implement`\n3. **Skill tool** - `Skill(\"agent-security-engineer\")` for explicit invocation\n\n---\n\n## Quality System\n\nSuperClaude uses a 9-dimension quality scoring system with automated actions:\n\n```mermaid\nflowchart LR\n subgraph Dimensions[\"9 Quality Dimensions\"]\n C[\"Correctness
25%\"]\n CO[\"Completeness
20%\"]\n P[\"Performance
10%\"]\n M[\"Maintainability
10%\"]\n S[\"Security
10%\"]\n SC[\"Scalability
10%\"]\n T[\"Testability
10%\"]\n U[\"Usability
5%\"]\n PAL[\"PAL Review
0%*\"]\n end\n\n subgraph Bands[\"Quality Bands\"]\n E[\"90+ Excellent\"]\n G[\"70-89 Good\"]\n A[\"50-69 Acceptable\"]\n P2[\"30-49 Poor\"]\n F[\"0-29 Failing\"]\n end\n\n subgraph Actions[\"Auto-Actions\"]\n FT[\"Fast-track
Skip review\"]\n AP[\"Approve
Complete task\"]\n IT[\"Iterate
Loop continues\"]\n ES[\"Escalate
Human review\"]\n BL[\"Block
Reject output\"]\n end\n\n Dimensions -->|\"Weighted
Average\"| Bands\n E --> FT\n G --> AP\n A --> IT\n P2 --> ES\n F --> BL\n\n style E fill:#4caf50,color:#fff\n style G fill:#8bc34a\n style A fill:#ffeb3b\n style P2 fill:#ff9800,color:#fff\n style F fill:#f44336,color:#fff\n```\n\n*PAL Review: Dynamic weight when `--pal-review` enabled\n\n### Quality Dimensions\n\n| Dimension | Weight | Indicators |\n|-----------|--------|------------|\n| Correctness | 25% | Tests pass, no runtime errors, output validation |\n| Completeness | 20% | Feature coverage, edge cases, documentation |\n| Performance | 10% | Time/space complexity, resource usage |\n| Maintainability | 10% | Readability, modularity, naming conventions |\n| Security | 10% | Input validation, authentication, data protection |\n| Scalability | 10% | Architecture patterns, database design, caching |\n| Testability | 10% | Unit tests, integration tests, test quality |\n| Usability | 5% | UI consistency, error messages, accessibility |\n| PAL Review | 0%* | External code review score (dynamic weight) |\n\n### Evidence Requirements\n\n| Requires Evidence | Does Not Require Evidence |\n|-------------------|---------------------------|\n| `sc-implement` - File diffs, test results | `sc-analyze` - Analysis output |\n| `sc-improve` - Before/after, metrics | `sc-design` - Specifications, diagrams |\n| `sc-test` - Test output, coverage | `sc-document` - Documentation files |\n| | `sc-git` - Git history (self-documenting) |\n| | `sc-explain` - Learning materials |\n\n### Quality Thresholds (from `evidence_gate.py`)\n\n| Status | Score | Action |\n|--------|-------|--------|\n| Production Ready | 90.0+ | Fast-track, skip additional review |\n| Acceptable | 70.0-89.9 | Approve, task complete |\n| Needs Review | 50.0-69.9 | Iterate or escalate |\n| Below Threshold | < 50.0 | Block, requires significant rework |\n\n---\n\n## Quality Gates\n\nSuperClaude enforces code quality through automated validators integrated into the development workflow via the `/sc:principles` command.\n\n### KISS Validator\n\nEnforces code simplicity via AST analysis. Located at `.claude/skills/sc-principles/scripts/validate_kiss.py`.\n\n| Metric | Threshold | Severity | Description |\n|--------|-----------|----------|-------------|\n| Cyclomatic Complexity | > 10 | error | Number of independent paths through code |\n| Cyclomatic Complexity | > 7 | warning | Early warning for growing complexity |\n| Cognitive Complexity | > 15 | error | Weighted complexity (nested structures count more) |\n| Function Length | > 50 lines | error | Lines of code per function |\n| Nesting Depth | > 4 levels | error | If/for/while/with/try nesting |\n| Parameter Count | > 5 | warning | Function parameters |\n\n**Usage:**\n```bash\npython .claude/skills/sc-principles/scripts/validate_kiss.py --scope-root . --json\n```\n\n**Cognitive vs Cyclomatic Complexity:**\n- Cyclomatic counts decision points (branches)\n- Cognitive weights nested structures more heavily: `1 + nesting_depth` per control structure\n- Example: `if (if (if ...))` has low cyclomatic but high cognitive (hard to read)\n\n### Purity Validator\n\nEnforces \"Functional Core, Imperative Shell\" architectural pattern. Located at `.claude/skills/sc-principles/scripts/validate_purity.py`.\n\n| Layer | Path Patterns | I/O Allowed | Severity |\n|-------|---------------|-------------|----------|\n| Core (purity required) | `*/domain/*`, `*/logic/*`, `*/services/*`, `*/utils/*`, `*/core/*` | NO | error |\n| Shell (I/O allowed) | `*/handlers/*`, `*/adapters/*`, `*/api/*`, `*/cli/*`, `*/scripts/*`, `*/tests/*` | YES | warning |\n\n**Detected I/O Patterns:**\n\n| Category | Examples |\n|----------|----------|\n| File I/O | `open()`, `read()`, `write()`, `Path.read_text()` |\n| Network | `requests.get()`, `httpx`, `urllib`, `socket` |\n| Database | `execute()`, `query()`, `session.add()`, `cursor` |\n| Subprocess | `subprocess.run()`, `os.system()`, `Popen` |\n| Global State | `global`, `nonlocal` keywords |\n| Side Effects | `print()`, `logging.*`, `logger.*` |\n| Async I/O | `async def`, `await`, `async for`, `async with` |\n\n**Usage:**\n```bash\npython .claude/skills/sc-principles/scripts/validate_purity.py --scope-root . --json\n```\n\n### SOLID Validator\n\nEnforces SOLID design principles via AST analysis. Located at `.claude/skills/sc-principles/scripts/validate_solid.py`.\n\n| Principle | Check | Threshold | Severity |\n|-----------|-------|-----------|----------|\n| SRP (Single Responsibility) | File length | > 300 lines | error |\n| SRP (Single Responsibility) | Class public methods | > 5 | error |\n| OCP (Open/Closed) | isinstance cascades | > 2 chained | error |\n| LSP (Liskov Substitution) | NotImplementedError in overrides | Any | error |\n| ISP (Interface Segregation) | Fat interfaces/protocols | > 7 methods | error |\n| DIP (Dependency Inversion) | Direct instantiation in business logic | Any | warning |\n\n**Usage:**\n```bash\npython .claude/skills/sc-principles/scripts/validate_solid.py --scope-root . --json\n```\n\n### Let It Crash Validator\n\nEnforces the \"Let It Crash\" error handling philosophy by detecting anti-patterns. Located at `.claude/skills/sc-principles/scripts/validate_crash.py`.\n\n| Anti-Pattern | Description | Severity |\n|--------------|-------------|----------|\n| Bare `except:` | Catches all exceptions without specificity | error |\n| `except Exception` without re-raise | Swallows exceptions silently | error |\n| `except: pass` | Silent failure hiding bugs | error |\n| Nested try/except cascades | Deeply nested error handling (> 2 levels) | error |\n\n**Usage:**\n```bash\npython .claude/skills/sc-principles/scripts/validate_crash.py --scope-root . --json\n```\n\n### Pre-commit Integration\n\nAdd to `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: local\n hooks:\n - id: kiss-check\n name: KISS Validation\n entry: python .claude/skills/sc-principles/scripts/validate_kiss.py --scope-root . --json\n language: python\n types: [python]\n pass_filenames: false\n\n - id: purity-check\n name: Purity Validation\n entry: python .claude/skills/sc-principles/scripts/validate_purity.py --scope-root . --json\n language: python\n types: [python]\n pass_filenames: false\n\n - id: solid-check\n name: SOLID Validation\n entry: python .claude/skills/sc-principles/scripts/validate_solid.py --scope-root . --json\n language: python\n types: [python]\n pass_filenames: false\n\n - id: crash-check\n name: Let It Crash Validation\n entry: python .claude/skills/sc-principles/scripts/validate_crash.py --scope-root . --json\n language: python\n types: [python]\n pass_filenames: false\n```\n\n### Exit Codes\n\n| Code | Meaning | Action |\n|------|---------|--------|\n| 0 | Validation passed | Proceed |\n| 2 | Violations detected | Blocked - refactor required |\n| 3 | Validation error | Manual intervention needed |\n\n### Refactoring Guidance\n\nWhen violations are detected:\n\n**For Complexity Violations:**\n- **Extract Method** - Split large functions into smaller, named pieces\n- **Guard Clauses** - Replace nested if/else with early returns\n- **Strategy Pattern** - Replace complex switch/if-else with polymorphism\n- **Decompose Conditional** - Name complex conditions as explaining variables\n\n**For Purity Violations:**\n- **Dependency Injection** - Pass dependencies as arguments\n- **Repository Pattern** - Isolate database operations\n- **Adapter Pattern** - Wrap external APIs\n- **Return Don't Print** - Return values, let callers handle output\n\n---\n\n## Metrics System\n\nSuperClaude includes a callback-based metrics system (`core/metrics.py`) that decouples the orchestrator from specific metrics backends.\n\n### MetricsEmitter Protocol\n\n```python\n@runtime_checkable\nclass MetricsEmitter(Protocol):\n \"\"\"Protocol defining the interface for metrics emission.\"\"\"\n\n def __call__(\n self,\n metric_name: str,\n value: Any,\n tags: Optional[Dict[str, str]] = None,\n ) -> None: ...\n```\n\n### Available Emitters\n\n| Emitter | Purpose | Use Case |\n|---------|---------|----------|\n| `noop_emitter` | Does nothing | Default when no emitter configured |\n| `InMemoryMetricsCollector` | Collects to list | Testing and debugging |\n| `LoggingMetricsEmitter` | Logs via Python logging | Simple production logging |\n\n### InMemoryMetricsCollector\n\nTesting utility for collecting and querying metrics:\n\n```python\nfrom core.metrics import InMemoryMetricsCollector\n\ncollector = InMemoryMetricsCollector()\norchestrator = LoopOrchestrator(config, metrics_emitter=collector)\nresult = orchestrator.run(context, invoker)\n\n# Query collected metrics\nassert collector.get(\"loop.completed.count\") == 1\nassert collector.get(\"loop.duration.seconds\") > 0\nassert collector.count(\"loop.iteration.quality_score.gauge\") == 3\n\n# Filter by tags\nerror_metrics = collector.filter_by_tags(\n \"loop.errors.count\",\n {\"reason\": \"skill_invocation\"}\n)\n```\n\n### Emitted Metrics\n\n**Loop Orchestrator Metrics:**\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `loop.started.count` | counter | Loop initiated |\n| `loop.completed.count` | counter | Loop finished (tags: termination_reason) |\n| `loop.duration.seconds` | timing | Total loop time |\n| `loop.iterations.total.gauge` | gauge | Iterations executed |\n| `loop.quality_score.final.gauge` | gauge | Final quality score |\n| `loop.errors.count` | counter | Errors (tags: reason) |\n| `loop.iteration.duration.seconds` | timing | Per-iteration timing |\n| `loop.iteration.quality_score.gauge` | gauge | Per-iteration quality |\n| `loop.iteration.quality_delta.gauge` | gauge | Quality change per iteration |\n\n**Skill Learning Metrics:**\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `learning.skills.applied.count` | counter | Skills injected at start |\n| `learning.skills.extracted.count` | counter | Skills learned (tags: domain, success) |\n| `learning.skills.promoted.count` | counter | Skills auto-promoted (tags: reason) |\n\n### Naming Convention\n\n```\n..\n```\n\n| Suffix | Type | Use Case |\n|--------|------|----------|\n| `.count` | counter | Events (incremental) |\n| `.gauge` | gauge | Current state (point-in-time) |\n| `.seconds` | timing | Duration measurement |\n\n### Integration Examples\n\n**Prometheus:**\n\n```python\nfrom prometheus_client import Counter, Gauge\n\ncounters, gauges = {}, {}\n\ndef prometheus_emitter(name, value, tags=None):\n labels = tags or {}\n if name.endswith('.count'):\n if name not in counters:\n counters[name] = Counter(name.replace('.', '_'), '', list(labels.keys()))\n counters[name].labels(**labels).inc(value)\n elif name.endswith('.gauge'):\n if name not in gauges:\n gauges[name] = Gauge(name.replace('.', '_'), '', list(labels.keys()))\n gauges[name].labels(**labels).set(value)\n```\n\n**StatsD:**\n\n```python\nimport statsd\nclient = statsd.StatsClient()\n\ndef statsd_emitter(name, value, tags=None):\n if name.endswith('.count'):\n client.incr(name, value)\n elif name.endswith('.gauge'):\n client.gauge(name, value)\n elif name.endswith('.seconds'):\n client.timing(name, value * 1000) # Convert to ms\n```\n\n---\n\n## Type System\n\nCore types defined in `core/types.py`:\n\n### TerminationReason\n\n```python\nclass TerminationReason(Enum):\n \"\"\"Reasons for loop termination.\"\"\"\n QUALITY_MET = \"quality_threshold_met\" # Score >= 70\n MAX_ITERATIONS = \"max_iterations_reached\" # Hard cap at 5\n ERROR = \"improver_error\" # Skill execution failure\n HUMAN_ESCALATION = \"requires_human_review\" # Needs human input\n TIMEOUT = \"timeout\" # Wall-clock exceeded\n```\n\n### LoopConfig\n\n```python\n@dataclass\nclass LoopConfig:\n \"\"\"Configuration for the agentic loop.\"\"\"\n max_iterations: int = 3 # Requested max (user-configurable)\n hard_max_iterations: int = 5 # P0 SAFETY: Cannot be overridden\n quality_threshold: float = 70.0 # Target score to meet\n timeout_seconds: Optional[float] # Wall-clock timeout (optional)\n pal_review_enabled: bool = True # Enable PAL MCP review within loop\n pal_model: str = \"gpt-5\" # Model to use for PAL reviews\n```\n\n### QualityAssessment\n\n```python\n@dataclass\nclass QualityAssessment:\n \"\"\"Result of quality assessment for an iteration.\"\"\"\n overall_score: float # Numeric quality score (0-100)\n passed: bool # Whether quality threshold was met\n threshold: float = 70.0 # The threshold checked against\n improvements_needed: list[str] # Specific improvements to make\n metrics: dict[str, float] # Detailed breakdown by dimension\n band: str = \"unknown\" # Quality band (excellent/good/acceptable/poor)\n metadata: dict[str, Any] # Additional context from evidence\n```\n\n### IterationResult\n\n```python\n@dataclass\nclass IterationResult:\n \"\"\"Result of a single loop iteration.\"\"\"\n iteration: int # Zero-based iteration number\n input_quality: float # Quality score before this iteration\n output_quality: float # Quality score after this iteration\n improvements_applied: list[str] # Improvements that were applied\n time_taken: float = 0.0 # Duration in seconds\n success: bool = False # Whether iteration improved quality\n termination_reason: str = \"\" # If loop terminated, why\n pal_review: Optional[Dict] = None # PAL MCP review results\n changed_files: list[str] # Files modified in this iteration\n```\n\n### LoopResult\n\n```python\n@dataclass\nclass LoopResult:\n \"\"\"Final result of complete loop execution.\"\"\"\n final_output: dict[str, Any] # Final state after all iterations\n final_assessment: QualityAssessment # Quality assessment of final state\n iteration_history: list[IterationResult] # All iteration results\n termination_reason: TerminationReason # Why the loop stopped\n total_iterations: int # Number of iterations executed\n total_time: float = 0.0 # Total wall-clock time\n```\n\n---\n\n## Configuration\n\nSuperClaude uses 6 YAML configuration files:\n\n### config/superclaud.yaml\n\nMain framework configuration:\n\n```yaml\nversion: 7.0.0\nname: SuperClaude Framework\n\nmodes:\n default: normal\n available: [normal, brainstorming, introspection, task_management, token_efficiency, orchestration]\n\nagents:\n max_delegation_depth: 5\n circular_detection: true\n parallel_execution: true\n default_timeout: 300\n\ncommands:\n prefix: \"/sc:\"\n discovery_path: SuperClaude/Commands\n cache_ttl: 3600\n\nquality:\n enabled: true\n default_threshold: 70.0\n max_iterations: 5\n dimensions:\n correctness: 0.25\n completeness: 0.20\n performance: 0.10\n maintainability: 0.10\n security: 0.10\n scalability: 0.10\n testability: 0.10\n usability: 0.05\n pal_review: 0.00 # Dynamic when enabled\n\nmcp_servers:\n enabled: true\n timeout: 300\n retry_attempts: 3\n servers:\n pal:\n enabled: true\n models: [gpt-5, claude-opus-4.1, gemini-2.5-pro]\n\ntriggers:\n mode_triggers:\n brainstorming: [explore, brainstorm, \"figure out\", \"not sure\"]\n introspection: [\"analyze my reasoning\", reflect, meta-cognitive]\n agent_triggers:\n communicator: [debug, error, broken, \"not working\", explain]\n optimizer: [refactor, \"improve code\", \"clean up\", optimize]\n\nworkflows:\n default_workflow: [analyze, plan, implement, test, document]\n debug_workflow: [reproduce, analyze, isolate, fix, verify]\n```\n\nQuality dimensions, model routing, and consensus policies are configured at runtime:\n- Quality dimensions and weights are in `config/superclaud.yaml` (quality section)\n- Model routing is handled by PAL MCP (`mcp__pal__listmodels` at runtime)\n- Agent selection is filesystem-based (`agents/core/`, `agents/traits/`, `agents/extensions/`)\n\n---\n\n## Directory Structure\n\n```\nSuperClaude/\nā”œā”€ā”€ CLAUDE.md # Master system prompt\nā”œā”€ā”€ README.md # This file\nā”œā”€ā”€ CONTRIBUTING.md # Contribution guidelines\nā”œā”€ā”€ CHANGELOG.md # Version history\nā”œā”€ā”€ SONDERA_INTEGRATION.md # Sondera security layer integration guide\nā”œā”€ā”€ pyproject.toml # Python project config\nā”œā”€ā”€ install-with-sondera.sh # Automated Sondera installer\nā”œā”€ā”€ test-sondera-integration.sh # Sondera integration verification\nā”‚\nā”œā”€ā”€ .claude/\nā”‚ ā””ā”€ā”€ skills/ # 43 Claude Code skills\nā”‚ ā”œā”€ā”€ agent-*/ # 8 agent persona skills\nā”‚ ā”‚ ā””ā”€ā”€ SKILL.md\nā”‚ ā”œā”€ā”€ sc-*/ # 26 command skills\nā”‚ ā”‚ ā”œā”€ā”€ SKILL.md\nā”‚ ā”‚ ā””ā”€ā”€ scripts/ # Optional tool implementations\nā”‚ ā”œā”€ā”€ gitnexus/ # 6 GitNexus code intelligence skills\nā”‚ ā”‚ ā”œā”€ā”€ gitnexus-cli/\nā”‚ ā”‚ ā”œā”€ā”€ gitnexus-exploring/\nā”‚ ā”‚ ā”œā”€ā”€ gitnexus-guide/\nā”‚ ā”‚ ā”œā”€ā”€ gitnexus-impact-analysis/\nā”‚ ā”‚ ā”œā”€ā”€ gitnexus-debugging/\nā”‚ ā”‚ ā””ā”€ā”€ gitnexus-refactoring/\nā”‚ ā”œā”€ā”€ ask/ # Single-select questions\nā”‚ ā”œā”€ā”€ ask-multi/ # Multi-select questions\nā”‚ ā””ā”€ā”€ learned/ # Auto-learned skills\nā”‚\nā”œā”€ā”€ agents/\nā”‚ ā”œā”€ā”€ index.yaml # Agent registry\nā”‚ ā”œā”€ā”€ core/ # 5 core agent prompts\nā”‚ ā”‚ ā”œā”€ā”€ architect.md\nā”‚ ā”‚ ā”œā”€ā”€ developer.md\nā”‚ ā”‚ ā”œā”€ā”€ optimizer.md\nā”‚ ā”‚ ā”œā”€ā”€ guardian.md\nā”‚ ā”‚ ā””ā”€ā”€ communicator.md\nā”‚ ā”œā”€ā”€ traits/ # 7 composable trait prompts\nā”‚ ā”‚ ā”œā”€ā”€ security-first.md\nā”‚ ā”‚ ā”œā”€ā”€ performance-first.md\nā”‚ ā”‚ ā”œā”€ā”€ test-driven.md\nā”‚ ā”‚ ā”œā”€ā”€ minimal-changes.md\nā”‚ ā”‚ ā”œā”€ā”€ principles-enforced.md\nā”‚ ā”‚ ā”œā”€ā”€ mcp-pal-enabled.md\nā”‚ ā”‚ ā””ā”€ā”€ mcp-rube-enabled.md\nā”‚ ā”œā”€ā”€ extensions/ # 7 domain specialist prompts\nā”‚ ā”‚ ā”œā”€ā”€ typescript-react-expert.md\nā”‚ ā”‚ ā”œā”€ā”€ python-expert.md\nā”‚ ā”‚ ā”œā”€ā”€ golang-expert.md\nā”‚ ā”‚ ā”œā”€ā”€ rust-expert.md\nā”‚ ā”‚ ā”œā”€ā”€ kubernetes-specialist.md\nā”‚ ā”‚ ā”œā”€ā”€ data-engineer.md\nā”‚ ā”‚ ā””ā”€ā”€ ml-engineer.md\nā”‚ ā””ā”€ā”€ DEPRECATED/ # Archived agents from previous versions (25 files)\nā”‚\nā”œā”€ā”€ commands/\nā”‚ ā”œā”€ā”€ index.yaml # Command registry\nā”‚ ā”œā”€ā”€ index.md # Command reference\nā”‚ ā”œā”€ā”€ analyze.md\nā”‚ ā”œā”€ā”€ implement.md\nā”‚ ā”œā”€ā”€ test.md\nā”‚ ā””ā”€ā”€ ... # 16 command templates\nā”‚\nā”œā”€ā”€ config/\nā”‚ ā”œā”€ā”€ superclaud.yaml # Main framework config (read by Rust crates)\nā”‚ ā””ā”€ā”€ schemas/ # JSON schemas for validation\nā”‚\nā”œā”€ā”€ core/ # Python orchestration layer\nā”‚ ā”œā”€ā”€ __init__.py\nā”‚ ā”œā”€ā”€ loop_orchestrator.py # Loop management (~410 lines)\nā”‚ ā”œā”€ā”€ quality_assessment.py # Quality scoring\nā”‚ ā”œā”€ā”€ pal_integration.py # PAL MCP signals\nā”‚ ā”œā”€ā”€ metrics.py # Callback-based metrics protocol\nā”‚ ā”œā”€ā”€ types.py # Core types (150 lines)\nā”‚ ā”œā”€ā”€ skill_learning_integration.py\nā”‚ ā””ā”€ā”€ skill_persistence.py\nā”‚\nā”œā”€ā”€ SuperClaude/\nā”‚", "bytes": 60000, "sha": "4838aaebf9023fc88f9f1d9d2a375e8712ee1e27a20c4cbcca85afc1d2ffaee1", "repo_slug": "tony363/superclaude", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_tony363_superclaude_claude_skills_deprec_378a9393/readme" }