SuperClaude Architecture Map -- Architecture Guide

01

System Overview

SuperClaude is not standalone software with running processes. It is a carefully organized collection of Markdown context files that Claude Code reads at session start to adopt specialized behaviors, structured workflows, and domain expertise. The power comes from systematic prompt engineering, not executing code.

30

Slash Commands

16

Agents

7

Modes

8

MCP Servers

3

PM Patterns

5

Flag Types

graph TB subgraph USER["User Input"] U1["/sc:command target --flags"] U2["@agent-name task"] U3["Natural language request"] end subgraph CONTEXT["Context Loading Engine"] CL["CLAUDE.md
Import Processor"] CORE["Core Context
RULES + PRINCIPLES + FLAGS"] CMD["Command Context
30 Workflow Patterns"] AGT["Agent Context
16 Domain Specialists"] MODE["Mode Context
7 Behavioral Modifiers"] MCP_CTX["MCP Context
8 Server Configs"] end subgraph CLAUDE["Claude Code Runtime"] PARSE["Input Parser"] ROUTE["Behavioral Router"] EXEC["Execution Engine"] OUT["Structured Output"] end U1 --> PARSE U2 --> PARSE U3 --> PARSE CL --> CORE CL --> CMD CL --> AGT CL --> MODE CL --> MCP_CTX CORE --> ROUTE PARSE --> ROUTE ROUTE --> CMD ROUTE --> AGT ROUTE --> MODE CMD --> EXEC AGT --> EXEC MODE --> EXEC MCP_CTX --> EXEC EXEC --> OUT style USER fill:#1a2030,stroke:#4ade80,color:#e8edf5 style CONTEXT fill:#151a24,stroke:#a78bfa,color:#e8edf5 style CLAUDE fill:#1a2010,stroke:#fbbf24,color:#e8edf5 style CL fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style CORE fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style PARSE fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style ROUTE fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style EXEC fill:#2a2010,stroke:#fbbf24,color:#e8edf5

Fig 1.1 -- SuperClaude system-level architecture: context files shape Claude Code behavior

Key insight: SuperClaude transforms Claude Code through "behavioral instruction injection" -- structured Markdown files that Claude reads to modify how it thinks, plans, and executes. There is no executing code or running processes in the framework itself.

02

Context-Oriented Configuration

The heart of SuperClaude is its import system. The main CLAUDE.md file uses @import statements to load a hierarchy of context files at session start. These files are organized by priority: mandatory rules load first, then MCP configs, then behavioral modes.

graph TD CLAUDEMD["CLAUDE.md
Master Import File"] subgraph MANDATORY["MANDATORY -- Always Loaded"] FLAGS["FLAGS.md
Behavioral Triggers"] RULES["RULES.md
Behavioral Rules"] PRINCIPLES["PRINCIPLES.md
Engineering Mindset"] end subgraph SECONDARY["SECONDARY -- MCP Integration"] M1["MCP_Tavily.md"] M2["MCP_Context7.md"] M3["MCP_Sequential.md"] M4["MCP_Serena.md"] M5["MCP_Playwright.md"] M6["MCP_Magic.md"] M7["MCP_Morphllm.md"] M8["MCP_Chrome-DevTools.md"] end subgraph CRITICAL["CRITICAL -- Behavioral Modes"] B1["MODE_Brainstorming.md"] B2["MODE_DeepResearch.md"] B3["MODE_Orchestration.md"] B4["MODE_Task_Management.md"] B5["MODE_Token_Efficiency.md"] B6["MODE_Business_Panel.md"] B7["MODE_Introspection.md"] end CLAUDEMD --> MANDATORY CLAUDEMD --> SECONDARY CLAUDEMD --> CRITICAL style CLAUDEMD fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style MANDATORY fill:#2a1a10,stroke:#fb923c,color:#e8edf5 style SECONDARY fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style CRITICAL fill:#2a1a30,stroke:#a78bfa,color:#e8edf5

Fig 2.1 -- CLAUDE.md import hierarchy with priority tiers

Context File Types

Type	Purpose	Activation	Count
Commands	Define workflow patterns and structured procedures	`/sc:command` triggers file read	30
Agents	Domain expertise, behavioral patterns, problem-solving	`@agent-name` or auto-activation	16
Modes	Modify interaction style and decision-making	Flags or keyword triggers	7
Core	Fundamental rules, principles, flag definitions	Always loaded at session start	3
MCP	Integration configs for external tool servers	Flag triggers or auto-detection	8

Context Loading Sequence

sequenceDiagram participant U as User participant CC as Claude Code participant CM as CLAUDE.md participant CMD as Command Files participant AGT as Agent Files participant MCP as MCP Servers U->>CC: /sc:implement "JWT auth" --think-hard CC->>CM: Load CLAUDE.md imports CM-->>CC: RULES + PRINCIPLES + FLAGS + Modes CC->>CC: Parse command: implement CC->>CMD: Load implement.md workflow CC->>CC: Detect keywords: auth, JWT CC->>AGT: Auto-activate security-engineer.md CC->>AGT: Auto-activate backend-architect.md CC->>CC: Parse flag: --think-hard CC->>MCP: Enable Sequential + Context7 CC->>CC: Execute with all contexts merged CC->>U: Structured implementation output

Fig 2.2 -- End-to-end context loading when a user issues a slash command

03

Slash Command System

SuperClaude provides 30 slash commands organized into 7 categories. Each command is a Markdown file installed to ~/.claude/commands/sc/ that defines a structured workflow pattern. When a user types /sc:command, Claude Code reads the corresponding file and adopts that workflow.

graph LR subgraph PLAN["Planning & Design"] P1["/brainstorm"] P2["/design"] P3["/estimate"] P4["/spec-panel"] end subgraph DEV["Development"] D1["/implement"] D2["/build"] D3["/improve"] D4["/cleanup"] D5["/explain"] end subgraph TEST["Testing & Quality"] T1["/test"] T2["/analyze"] T3["/troubleshoot"] T4["/reflect"] end subgraph PM["Project Management"] PM1["/pm"] PM2["/task"] PM3["/workflow"] end subgraph RESEARCH["Research"] R1["/research"] R2["/business-panel"] end subgraph UTIL["Utilities"] U1["/agent"] U2["/spawn"] U3["/save & /load"] U4["/select-tool"] U5["/index-repo"] end style PLAN fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style DEV fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style TEST fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style PM fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style RESEARCH fill:#2a1020,stroke:#fb7185,color:#e8edf5 style UTIL fill:#201a10,stroke:#fb923c,color:#e8edf5

Fig 3.1 -- 30 slash commands organized by development lifecycle category

Command Anatomy

Each command Markdown file contains structured sections that define its behavior:

---
name: implement
description: Code implementation workflow
category: development
complexity: enhanced
mcp-servers: [context7, sequential]
personas: [architect, engineer]
---

# /sc:implement

## Triggers
- New feature creation, code generation
- Keywords: implement, build, create, code

## Workflow Pattern
1. Understand requirements
2. Plan with parallelization analysis
3. Execute in Wave pattern
4. Validate with tests
            

Installation: Commands are installed via pipx install superclaude && superclaude install which copies all 30 Markdown files to ~/.claude/commands/sc/. Claude Code's native slash command system reads them automatically.

04

Agent Orchestration

SuperClaude defines 16 specialized domain agents plus a meta-layer PM Agent. Agents are not separate AI models -- they are context files that instruct Claude Code to adopt domain-specific expertise, behavioral patterns, and problem-solving approaches.

graph TB subgraph META["Meta Layer"] PM["PM Agent
Self-improvement, documentation,
mistake analysis, knowledge capture"] end subgraph ARCH["Architecture Specialists"] SA["System Architect"] BA["Backend Architect"] FA["Frontend Architect"] DA["DevOps Architect"] end subgraph QUAL["Quality Specialists"] SE["Security Engineer"] PE["Performance Engineer"] QE["Quality Engineer"] RE["Refactoring Expert"] end subgraph KNOWLEDGE["Knowledge Specialists"] DR["Deep Research Agent"] LG["Learning Guide"] SM["Socratic Mentor"] TW["Technical Writer"] end subgraph ANALYSIS["Analysis Specialists"] RA["Requirements Analyst"] RCA["Root Cause Analyst"] PE2["Python Expert"] BP["Business Panel"] end PM --> ARCH PM --> QUAL PM --> KNOWLEDGE PM --> ANALYSIS style META fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style ARCH fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style QUAL fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style KNOWLEDGE fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style ANALYSIS fill:#2a1020,stroke:#fb7185,color:#e8edf5

Fig 4.1 -- Agent hierarchy: PM meta-layer oversees 4 specialist groups (16 agents)

Activation Mechanisms

Manual Override

Use @agent-security to directly invoke a specific agent. Takes highest priority over all other activation methods.

Keyword Auto-Activation

Domain terminology in requests triggers agents automatically. "JWT authentication" activates security-engineer, "React dashboard" activates frontend-architect.

File Type Detection

File extensions trigger language specialists. Working with .py files activates python-expert, .jsx activates frontend-architect.

Complexity Routing

Multi-step tasks and cross-domain problems trigger coordination agents. System-architect provides oversight for high-complexity operations.

Agent Selection Priority

graph TD INPUT["Incoming Task"] --> MANUAL{"Manual @agent
prefix?"} MANUAL -->|Yes| USE_AGENT["Use specified agent"] MANUAL -->|No| KEYWORD{"Domain keywords
detected?"} KEYWORD -->|Yes| PRIMARY["Activate primary
domain agent"] KEYWORD -->|No| FILETYPE{"File type
matches?"} FILETYPE -->|Yes| LANG["Activate language
specialist"] FILETYPE -->|No| COMPLEX{"Multi-domain
or complex?"} COMPLEX -->|Yes| COORD["Coordinate
multiple agents"] COMPLEX -->|No| REQ["Activate
requirements-analyst"] PRIMARY --> QUALITY{"Quality
critical?"} QUALITY -->|Yes| ADD_QA["Add security +
performance + QE"] style INPUT fill:#1a2030,stroke:#4ade80,color:#e8edf5 style USE_AGENT fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style PRIMARY fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style COORD fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style ADD_QA fill:#2a1020,stroke:#fb7185,color:#e8edf5

Fig 4.2 -- Agent selection decision tree with priority hierarchy

PM Agent -- The Meta Layer

The PM Agent sits above all other agents as a self-improvement layer. Unlike task-execution agents, the PM Agent activates after work is complete to document patterns, analyze mistakes, and maintain the knowledge base. It implements three core patterns:

ConfidenceChecker

Pre-execution confidence assessment. Requires 90%+ confidence to proceed, 70-89% presents alternatives, below 70% asks clarifying questions. ROI: 25-250x token savings.

SelfCheckProtocol

Post-implementation evidence-based validation. No speculation allowed -- every claim must be verified through tests or documentation.

ReflexionPattern

Error learning and cross-session pattern matching. When mistakes occur, root cause is analyzed and prevention checklists are created for future reference.

05

Behavioral Modes

Modes are behavioral modifiers that change how Claude Code communicates, reasons, and prioritizes. Each mode is a MODE_*.md file that adjusts interaction patterns without changing domain expertise.

Mode	Flag	Trigger	Behavior
Brainstorming	`--brainstorm`	Vague requests, "maybe", "thinking about"	Collaborative discovery, probing questions
Deep Research	`/sc:research`	Research queries, "find out", analysis	Multi-hop reasoning, source scoring
Orchestration	`--orchestrate`	Multi-tool operations, parallel opportunities	Tool matrix optimization, parallel execution
Task Management	`--task-manage`	3+ steps, complex scope	Delegation, progressive enhancement
Token Efficiency	`--token-efficient`	Context usage above 75%	Symbol-enhanced, 30-50% reduction
Business Panel	`/sc:business-panel`	Strategic analysis needs	Multi-expert business analysis
Introspection	`--introspect`	Self-analysis, error recovery	Transparent reasoning with markers

graph LR subgraph FLAGS["Flag System"] F1["--brainstorm"] F2["--think / --think-hard / --ultrathink"] F3["--orchestrate"] F4["--token-efficient"] F5["--introspect"] F6["--delegate"] F7["--loop"] end subgraph DEPTH["Analysis Depth"] D1["--think
~4K tokens"] D2["--think-hard
~10K tokens"] D3["--ultrathink
~32K tokens"] end subgraph MCP_FLAGS["MCP Flags"] MF1["--c7 / --context7"] MF2["--seq / --sequential"] MF3["--magic"] MF4["--morph"] MF5["--play / --playwright"] MF6["--tavily"] MF7["--all-mcp"] MF8["--no-mcp"] end style FLAGS fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style DEPTH fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style MCP_FLAGS fill:#1a2040,stroke:#38bdf8,color:#e8edf5

Fig 5.1 -- Flag taxonomy: behavioral modes, analysis depth levels, and MCP server toggles

06

MCP Server Integration

SuperClaude integrates 8 MCP (Model Context Protocol) servers that provide Claude Code with enhanced capabilities. MCP servers are actual running software -- SuperClaude's context files tell Claude when and how to use them. Installation is optional but provides 2-3x faster execution and 30-50% fewer tokens.

graph TB subgraph SC["SuperClaude Context Layer"] CMD_R["Command Files
Workflow patterns"] AGT_R["Agent Files
Domain expertise"] FLAG_R["Flag Definitions
Activation triggers"] end subgraph MCP_LAYER["MCP Server Layer -- Actual Running Software"] TAV["Tavily
Web Search"] C7["Context7
Doc Lookup"] SEQ["Sequential
Multi-step Reasoning"] SER["Serena
Code Understanding"] PW["Playwright
Browser Automation"] MAG["Magic
UI Components"] MOR["Morphllm
Code Transform"] CDT["Chrome DevTools
Performance"] end subgraph TOOLS["Tool Capabilities"] SEARCH["Web search + discovery"] DOCS["Official documentation"] REASON["Structured analysis"] MEMORY["Session persistence"] BROWSER["E2E testing"] UI["Component generation"] BULK["Bulk code editing"] PERF["Performance profiling"] end CMD_R --> TAV CMD_R --> C7 CMD_R --> SEQ AGT_R --> SER AGT_R --> PW AGT_R --> MAG FLAG_R --> MOR FLAG_R --> CDT TAV --> SEARCH C7 --> DOCS SEQ --> REASON SER --> MEMORY PW --> BROWSER MAG --> UI MOR --> BULK CDT --> PERF style SC fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style MCP_LAYER fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style TOOLS fill:#2a2010,stroke:#fbbf24,color:#e8edf5

Fig 6.1 -- MCP integration: context files direct Claude to external tool servers

Deep Research orchestration: The /sc:research command coordinates multiple MCP servers in sequence -- Tavily for web search, Sequential for multi-step reasoning, Playwright for complex content extraction, Context7 for documentation lookup, and Serena for memory persistence. This enables autonomous multi-hop research with up to 5 iterative search hops.

Deep Research Pipeline

graph LR Q["Research Query"] --> PLAN["Planning
Strategy Selection"] PLAN --> HOP1["Hop 1
Initial Search"] HOP1 --> SCORE1["Quality Scoring
0.0 - 1.0"] SCORE1 -->|Below 0.8| HOP2["Hop 2
Entity Expansion"] SCORE1 -->|Above 0.8| SYNTH["Synthesis"] HOP2 --> SCORE2["Quality Scoring"] SCORE2 -->|Below 0.8| HOP3["Hop 3
Concept Deepening"] SCORE2 -->|Above 0.8| SYNTH HOP3 --> HOP4["Hop 4-5
Temporal + Causal"] HOP4 --> SYNTH SYNTH --> OUT["Research Report
with Confidence"] style Q fill:#1a2030,stroke:#4ade80,color:#e8edf5 style PLAN fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style SYNTH fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style OUT fill:#1a3a2a,stroke:#4ade80,color:#e8edf5

Fig 6.2 -- Deep Research multi-hop pipeline with quality-gated iteration

07

Execution Patterns

SuperClaude defines execution patterns that Claude Code follows for task execution. The core pattern is Wave-Checkpoint-Wave: parallel operations grouped into waves with validation checkpoints between them, achieving 3.5x speedup over sequential execution.

graph TD subgraph WAVE1["Wave 1 -- Parallel Read"] R1["Read file A"] R2["Read file B"] R3["Read file C"] R4["Read file D"] end subgraph CHECK1["Checkpoint 1"] AN["Analyze dependencies
Plan changes"] end subgraph WAVE2["Wave 2 -- Parallel Edit"] E1["Edit file A"] E2["Edit file B"] E3["Edit file C"] end subgraph CHECK2["Checkpoint 2"] VAL["Run tests
Validate changes"] end subgraph WAVE3["Wave 3 -- Parallel Verify"] V1["Lint check"] V2["Type check"] V3["Test suite"] end WAVE1 --> CHECK1 CHECK1 --> WAVE2 WAVE2 --> CHECK2 CHECK2 --> WAVE3 style WAVE1 fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style CHECK1 fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style WAVE2 fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style CHECK2 fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style WAVE3 fill:#2a1a30,stroke:#a78bfa,color:#e8edf5

Fig 7.1 -- Wave-Checkpoint-Wave execution pattern (3.5x faster than sequential)

Task Lifecycle

graph LR U["Understand"] --> P["Plan"] P --> TODO["TodoWrite
3+ tasks"] TODO --> EXEC["Execute
in Waves"] EXEC --> TRACK["Track
Progress"] TRACK --> VALIDATE["Validate
Evidence-based"] VALIDATE -->|Issues| EXEC VALIDATE -->|Pass| DONE["Complete"] DONE --> PM["PM Agent
Documentation"] style U fill:#1a2030,stroke:#4ade80,color:#e8edf5 style P fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style TODO fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style EXEC fill:#1a2040,stroke:#38bdf8,color:#e8edf5 style VALIDATE fill:#2a1a30,stroke:#a78bfa,color:#e8edf5 style PM fill:#2a1020,stroke:#fb7185,color:#e8edf5

Fig 7.2 -- Task lifecycle: Understand, Plan, Execute, Track, Validate, Document

Rule Priority System

CRITICAL Rules

Security, data safety, production stability. Never compromised. Includes: git status before changes, feature branches only, root cause analysis on failures, absolute paths only.

IMPORTANT Rules

Quality, maintainability, professionalism. Strong preference. Includes: TodoWrite for 3+ step tasks, complete all implementations, MVP scope, professional language.

RECOMMENDED Rules

Optimization, style, best practices. Applied when practical. Includes: parallel operations, descriptive naming, MCP tools over basic alternatives, batch operations.

08

Memory and Learning System

SuperClaude implements cross-session memory through file-based persistence. The PM Agent maintains a knowledge base of patterns learned, solutions discovered, workflow metrics, and reflexion logs. This enables the framework to improve over time.

graph TB subgraph SESSION["Current Session"] WORK["Task Execution"] ERR["Error Detection"] DONE2["Task Completion"] end subgraph PM_LAYER["PM Agent Processing"] CONF["ConfidenceChecker
Pre-execution gate"] SELF["SelfCheckProtocol
Post-implementation"] REFL["ReflexionPattern
Error analysis"] end subgraph MEMORY["Persistent Memory -- docs/memory/"] PAT["patterns_learned.jsonl
Reusable patterns"] SOL["solutions_learned.jsonl
Successful approaches"] WF["workflow_metrics.jsonl
Performance data"] REFLOG["reflexion.jsonl
Error prevention"] LAST["last_session.md
Session context"] NEXT["next_actions.md
Continuity"] end WORK --> CONF CONF -->|90%+| WORK DONE2 --> SELF ERR --> REFL SELF --> PAT SELF --> SOL REFL --> REFLOG WORK --> WF WORK --> LAST DONE2 --> NEXT style SESSION fill:#1a2030,stroke:#4ade80,color:#e8edf5 style PM_LAYER fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style MEMORY fill:#2a1a30,stroke:#a78bfa,color:#e8edf5

Fig 8.1 -- Memory system: PM Agent patterns persist across sessions via JSONL files

Session Lifecycle

Sessions follow a structured lifecycle with explicit save/load commands:

/sc:load -- Initialize session by loading last_session.md and next_actions.md
Work phase -- Execute tasks with 30-minute checkpoint intervals
/sc:save -- Persist session state, patterns learned, and next actions before ending

The /sc:save and /sc:load commands enable session continuity, preserving context across conversations so the next session picks up exactly where the last one ended.

Confidence Gate

graph LR TASK["New Task"] --> ASSESS["Confidence
Assessment"] ASSESS -->|"90%+"| GO["Proceed with
implementation"] ASSESS -->|"70-89%"| ALT["Present
alternatives"] ASSESS -->|"Below 70%"| ASK["Ask clarifying
questions"] ALT --> GO ASK -->|"Clarified"| ASSESS style TASK fill:#1a2030,stroke:#4ade80,color:#e8edf5 style GO fill:#1a3a2a,stroke:#4ade80,color:#e8edf5 style ALT fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style ASK fill:#2a1a30,stroke:#a78bfa,color:#e8edf5

Fig 8.2 -- ConfidenceChecker gate prevents wrong-direction work (25-250x token savings)

09

Installation Architecture

SuperClaude is distributed as a Python package via PyPI. The CLI tool copies context files to the appropriate locations in the Claude Code configuration directory.

graph TD subgraph DIST["Distribution"] PYPI["PyPI Package
superclaude"] GIT["Git Clone
install.sh"] end subgraph CLI["CLI Tool"] INSTALL["superclaude install
Copy 30 commands"] MCP_I["superclaude mcp
Configure MCP servers"] DOC["superclaude doctor
Health diagnostics"] end subgraph TARGET["Target Locations"] CLAUDE_DIR["~/.claude/"] CMD_DIR["~/.claude/commands/sc/
30 command .md files"] AGENT_DIR["~/.claude/agents/
16 agent .md files"] ROOT_FILES["~/.claude/
CLAUDE.md + RULES.md +
FLAGS.md + PRINCIPLES.md +
MODE_*.md + MCP_*.md"] CLAUDE_JSON["~/.claude.json
MCP server configs"] end PYPI --> CLI GIT --> CLI INSTALL --> CMD_DIR INSTALL --> AGENT_DIR INSTALL --> ROOT_FILES MCP_I --> CLAUDE_JSON DOC --> TARGET style DIST fill:#1a2030,stroke:#4ade80,color:#e8edf5 style CLI fill:#2a2010,stroke:#fbbf24,color:#e8edf5 style TARGET fill:#2a1a30,stroke:#a78bfa,color:#e8edf5

Fig 9.1 -- Installation flow: PyPI package deploys context files to Claude Code directories

Package Structure

Python Package (src/superclaude/)

CLI tools, pytest plugin, PM Agent implementation (confidence.py, self_check.py, reflexion.py), parallel execution engine, and the context file source.

Plugins (plugins/superclaude/)

Mirror of context files for plugin distribution. Contains agents/, commands/, modes/, mcp/ configs, and core files. Synced from src/ during build.

Test Suite (tests/)

Unit and integration tests for PM Agent patterns, CLI installation, confidence checker, reflexion learning, and token budget management.

10

Repository Structure

The SuperClaude repository is a Python package with a well-organized hierarchy separating source code, context files, documentation, and tooling.

SuperClaude_Framework/
# Root context files
CLAUDE.md              # Dev guide for working on the repo itself
PLANNING.md            # Architecture, design principles, absolute rules
TASK.md                # Current tasks and priorities
KNOWLEDGE.md           # Accumulated insights and best practices

# Python source package
src/superclaude/
  cli/                 # CLI: main.py, doctor.py, install_commands.py, install_mcp.py
  pm_agent/            # confidence.py, self_check.py, reflexion.py, token_budget.py
  execution/           # parallel.py, reflection.py, self_correction.py
  commands/            # 30 command .md files (implement, test, research...)
  agents/              # 16 agent .md files (security-engineer, pm-agent...)
  modes/               # 7 MODE_*.md files (Brainstorming, DeepResearch...)
  mcp/                 # MCP_*.md guides + configs/*.json for 8 servers
  core/                # RULES.md, PRINCIPLES.md, FLAGS.md
  hooks/               # hooks.json lifecycle configuration

# Documentation
docs/
  architecture/        # Migration plans, phase completions, context window analysis
  developer-guide/     # Technical architecture, contributing, testing
  user-guide/          # Commands, agents, modes, flags, MCP, session management
  memory/              # Persistent memory: patterns, solutions, metrics, reflexion
  research/            # Research notes on parallel execution, token efficiency
  mistakes/            # Documented errors with root cause analysis

# Build and distribution
plugins/superclaude/   # Plugin distribution mirror of context files
scripts/               # Build, analysis, A/B testing, cleanup tools
tests/                 # Unit + integration test suite
pyproject.toml         # Package config with pytest entry point
install.sh             # Direct installation script
        

Design philosophy: SuperClaude embodies context engineering -- the discipline of structuring information so that AI systems produce better outputs. Rather than writing code that executes, SuperClaude writes instructions that shape how Claude Code thinks. Every .md file is a carefully crafted prompt that guides behavior through structured context, not through running software.