SuperClaude/docs/Development/ARCHITECTURE.md

SuperClaude Architecture

Last Updated: 2025-10-14 Version: 4.1.5

📋 Table of Contents

1. System Overview
2. Core Architecture
3. PM Agent Mode: The Meta-Layer
4. Component Relationships
5. Serena MCP Integration
6. PDCA Engine
7. Data Flow
8. Extension Points

---

System Overview

What is SuperClaude?

SuperClaude is a Context-Oriented Configuration Framework that transforms Claude Code into a structured development platform. It is NOT standalone software with running processes - it is a collection of .md instruction files that Claude Code reads to adopt specialized behaviors.

Key Components

SuperClaude Framework
├── Commands (26)      → Workflow patterns
├── Agents (16)        → Domain expertise
├── Modes (7)          → Behavioral modifiers
├── MCP Servers (8)    → External tool integrations
└── PM Agent Mode      → Meta-layer orchestration (Always-Active)

Version Information

• Current Version: 4.1.5
• Commands: 26 slash commands (/sc:*)
• Agents: 16 specialized domain experts
• Modes: 7 behavioral modes
• MCP Servers: 8 integrations (Context7, Sequential, Magic, Playwright, Morphllm, Serena, Tavily, Chrome DevTools)

---

Core Architecture

Context-Oriented Configuration

SuperClaude's architecture is built on a simple principle: behavioral modification through structured context files.

User Input
    ↓
Context Loading (CLAUDE.md imports)
    ↓
Command Detection (/sc:* pattern)
    ↓
Agent Activation (manual or auto)
    ↓
Mode Application (flags or triggers)
    ↓
MCP Tool Coordination
    ↓
Output Generation

Directory Structure

~/.claude/
├── CLAUDE.md                   # Main context with @imports
├── FLAGS.md                    # Flag definitions
├── RULES.md                    # Core behavioral rules
├── PRINCIPLES.md               # Guiding principles
├── MODE_*.md                   # 7 behavioral modes
├── MCP_*.md                    # 8 MCP server integrations
├── agents/                     # 16 specialized agents
│   ├── pm-agent.md            # 🆕 Meta-layer orchestrator
│   ├── backend-architect.md
│   ├── frontend-architect.md
│   ├── security-engineer.md
│   └── ... (13 more)
└── commands/sc/               # 26 workflow commands
    ├── pm.md                  # 🆕 PM Agent command
    ├── implement.md
    ├── analyze.md
    └── ... (23 more)

---

PM Agent Mode: The Meta-Layer

Position in Architecture

PM Agent operates as a meta-layer above all other components:

┌─────────────────────────────────────────────┐
│         PM Agent Mode (Meta-Layer)          │
│   • Always Active (Session Start)           │
│   • Context Preservation                     │
│   • PDCA Self-Evaluation                     │
│   • Knowledge Management                     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│          Specialist Agents (16)              │
│   backend-architect, security-engineer, etc. │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│           Commands & Modes                   │
│   /sc:implement, /sc:analyze, etc.          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│            MCP Tool Layer                    │
│   Context7, Sequential, Magic, etc.         │
└─────────────────────────────────────────────┘

PM Agent Responsibilities

1. Session Lifecycle Management

   • Auto-activation at session start
   • Context restoration from Serena MCP memory
   • User report generation (前回/進捗/今回/課題)

2. PDCA Cycle Execution

   • Plan: Hypothesis generation
   • Do: Experimentation with checkpoints
   • Check: Self-evaluation
   • Act: Knowledge extraction

3. Documentation Strategy

   • Temporary documentation (docs/temp/)
   • Formal patterns (docs/patterns/)
   • Mistake records (docs/mistakes/)
   • Knowledge evolution to CLAUDE.md

4. Sub-Agent Orchestration

   • Auto-delegation to specialists
   • Context coordination
   • Quality gate validation
   • Progress monitoring

---

Component Relationships

Commands → Agents → Modes → MCP

User: "/sc:implement authentication" --security
         ↓
    [Command Layer]
    commands/sc/implement.md
         ↓
    [Agent Auto-Activation]
    agents/security-engineer.md
    agents/backend-architect.md
         ↓
    [Mode Application]
    MODE_Task_Management.md (TodoWrite)
         ↓
    [MCP Tool Coordination]
    Context7 (auth patterns)
    Sequential (complex analysis)
         ↓
    [PM Agent Meta-Layer]
    Document learnings → docs/patterns/

Activation Flow

1. Explicit Command: User types /sc:implement

   • Loads commands/sc/implement.md
   • Activates related agents (backend-architect, etc.)

2. Agent Activation: @agent-security or auto-detected

   • Loads agent expertise context
   • May activate related MCP servers

3. Mode Application: --brainstorm flag or keywords

   • Modifies interaction style
   • Enables specific behaviors

4. PM Agent Meta-Layer: Always active

   • Monitors all interactions
   • Documents learnings
   • Preserves context across sessions

---

Serena MCP Integration

Memory Operations

Serena MCP provides semantic code analysis and session persistence through memory operations:

Session Start:
  PM Agent → list_memories()
  PM Agent → read_memory("pm_context")
  PM Agent → read_memory("last_session")
  PM Agent → read_memory("next_actions")
  PM Agent → Report to User

During Work (every 30min):
  PM Agent → write_memory("checkpoint", progress)
  PM Agent → write_memory("decision", rationale)

Session End:
  PM Agent → write_memory("last_session", summary)
  PM Agent → write_memory("next_actions", todos)
  PM Agent → write_memory("pm_context", complete_state)

Memory Structure

{
  "pm_context": {
    "project": "SuperClaude_Framework",
    "current_phase": "Phase 1: Documentation",
    "active_tasks": ["ARCHITECTURE.md", "ROADMAP.md"],
    "architecture": "Context-Oriented Configuration",
    "patterns": ["PDCA Cycle", "Session Lifecycle"]
  },
  "last_session": {
    "date": "2025-10-14",
    "accomplished": ["PM Agent mode design", "Salvaged implementations"],
    "issues": ["Serena MCP not configured"],
    "learned": ["Session Lifecycle pattern", "PDCA automation"]
  },
  "next_actions": [
    "Create docs/development/ structure",
    "Write ARCHITECTURE.md",
    "Configure Serena MCP server"
  ]
}

---

PDCA Engine

Continuous Improvement Cycle

┌─────────────┐
│    Plan     │ → write_memory("plan", goal)
│   (仮説)    │ → docs/temp/hypothesis-YYYY-MM-DD.md
└──────┬──────┘
       ↓
┌─────────────┐
│     Do      │ → TodoWrite tracking
│   (実験)    │ → write_memory("checkpoint", progress)
└──────┬──────┘ → docs/temp/experiment-YYYY-MM-DD.md
       ↓
┌─────────────┐
│   Check     │ → think_about_task_adherence()
│   (評価)    │ → think_about_whether_you_are_done()
└──────┬──────┘ → docs/temp/lessons-YYYY-MM-DD.md
       ↓
┌─────────────┐
│    Act      │ → Success: docs/patterns/[name].md
│   (改善)    │ → Failure: docs/mistakes/mistake-*.md
└──────┬──────┘ → Update CLAUDE.md
       ↓
   [Repeat]

Documentation Evolution

Trial-and-Error (docs/temp/)
    ↓
Success → Formal Pattern (docs/patterns/)
    ↓
Accumulate Knowledge
    ↓
Extract Best Practices → CLAUDE.md (Global Rules)

Mistake Detection (docs/temp/)
    ↓
Root Cause Analysis → docs/mistakes/
    ↓
Prevention Checklist
    ↓
Update Anti-Patterns → CLAUDE.md

---

Data Flow

Session Lifecycle Data Flow

Session Start:
┌──────────────┐
│ Claude Code  │
│   Startup    │
└──────┬───────┘
       ↓
┌──────────────┐
│  PM Agent    │ list_memories()
│  Activation  │ read_memory("pm_context")
└──────┬───────┘
       ↓
┌──────────────┐
│   Serena     │ Return: pm_context,
│     MCP      │          last_session,
└──────┬───────┘          next_actions
       ↓
┌──────────────┐
│  Context     │ Restore project state
│ Restoration  │ Generate user report
└──────┬───────┘
       ↓
┌──────────────┐
│    User      │ 前回: [summary]
│   Report     │ 進捗: [status]
└──────────────┘ 今回: [actions]
                 課題: [blockers]

Implementation Data Flow

User Request → PM Agent Analyzes
    ↓
PM Agent → Delegate to Specialist Agents
    ↓
Specialist Agents → Execute Implementation
    ↓
Implementation Complete → PM Agent Documents
    ↓
PM Agent → write_memory("checkpoint", progress)
PM Agent → docs/temp/experiment-*.md
    ↓
Success → docs/patterns/ | Failure → docs/mistakes/
    ↓
Update CLAUDE.md (if global pattern)

---

Extension Points

Adding New Components

1. New Command

File: ~/.claude/commands/sc/new-command.md
Structure:
  - Metadata (name, category, complexity)
  - Triggers (when to use)
  - Workflow Pattern (step-by-step)
  - Examples

Integration:
  - Auto-loads when user types /sc:new-command
  - Can activate related agents
  - PM Agent automatically documents usage patterns

2. New Agent

File: ~/.claude/agents/new-specialist.md
Structure:
  - Metadata (name, category)
  - Triggers (keywords, file types)
  - Behavioral Mindset
  - Focus Areas

Integration:
  - Auto-activates on trigger keywords
  - Manual activation: @agent-new-specialist
  - PM Agent orchestrates with other agents

3. New Mode

File: ~/.claude/MODE_NewMode.md
Structure:
  - Activation Triggers (flags, keywords)
  - Behavioral Modifications
  - Interaction Patterns

Integration:
  - Flag: --new-mode
  - Auto-activation on complexity threshold
  - Modifies all agent behaviors

4. New MCP Server

File: ~/.claude/.claude.json
{
  "mcpServers": {
    "new-server": {
      "command": "npx",
      "args": ["-y", "new-server-mcp@latest"]
    }
  }
}

File: ~/.claude/MCP_NewServer.md
Structure:
  - Purpose (what this server provides)
  - Triggers (when to use)
  - Integration (how to coordinate with other tools)

PM Agent Integration for Extensions

All new components automatically integrate with PM Agent meta-layer:

1. Session Lifecycle: New components' usage tracked across sessions
2. PDCA Cycle: Patterns extracted from new component usage
3. Documentation: Learnings automatically documented
4. Orchestration: PM Agent coordinates new components with existing ones

---

Architecture Principles

1. Simplicity First

• No executing code, only context files
• No performance systems, only instructional patterns
• No detection engines, Claude Code does pattern matching

2. Context-Oriented

• Behavior modification through structured context
• Import system for modular context loading
• Clear trigger patterns for activation

3. Meta-Layer Design

• PM Agent orchestrates without interfering
• Specialist agents work transparently
• Users interact with cohesive system

4. Knowledge Accumulation

• Every experience generates learnings
• Mistakes documented with prevention
• Patterns extracted to reusable knowledge

5. Session Continuity

• Context preserved across sessions
• No re-explanation needed
• Seamless resumption from last checkpoint

---

Technical Considerations

Performance

• Framework is pure context (no runtime overhead)
• Token efficiency through dynamic MCP loading
• Strategic context caching for related phases

Scalability

• Unlimited commands/agents/modes through context files
• Modular architecture supports independent development
• PM Agent meta-layer handles coordination complexity

Maintainability

• Clear separation of concerns (Commands/Agents/Modes)
• Self-documenting through PDCA cycle
• Living documentation evolves with usage

Extensibility

• Drop-in new contexts without code changes
• MCP servers add capabilities externally
• PM Agent auto-integrates new components

---

Future Architecture

Planned Enhancements

1. Auto-Activation System

   • PM Agent activates automatically at session start
   • No manual invocation needed

2. Enhanced Memory Operations

   • Full Serena MCP integration
   • Cross-project knowledge sharing
   • Pattern recognition across sessions

3. PDCA Automation

   • Automatic documentation lifecycle
   • AI-driven pattern extraction
   • Self-improving knowledge base

4. Multi-Project Orchestration

   • PM Agent coordinates across projects
   • Shared learnings and patterns
   • Unified knowledge management

---

Summary

SuperClaude's architecture is elegantly simple: structured context files that Claude Code reads to adopt sophisticated behaviors. The addition of PM Agent mode as a meta-layer transforms this from a collection of tools into a continuously learning, self-improving development platform.

Key Architectural Innovation: PM Agent meta-layer provides:

• Always-active foundation layer
• Context preservation across sessions
• PDCA self-evaluation and learning
• Systematic knowledge management
• Seamless orchestration of specialist agents

This architecture enables SuperClaude to function as a 最高司令官 (Supreme Commander) that orchestrates all development activities while continuously learning and improving from every interaction.

---

Last Verified: 2025-10-14 Next Review: 2025-10-21 (1 week) Version: 4.1.5