SuperClaude/README.md

SuperClaude - Claude Code Cfg Framework

Legend

Symbol	Meaning		Abbrev	Meaning
→	leads to		cfg	configuration
&	and/with		fn	function
w/	with		impl	implementation
@	at/located		env	environment
+	add/include		dev	development
-	remove/exclude		auth	authentication
∀	for all/every		API	application interface

Advanced cfg framework for Claude Code | v4.0.0

What is SuperClaude

Comprehensive cfg system enhancing Claude Code w/:

• CLAUDE.md → Main cfg + ops
• RULES.md → Governance + practices
• PERSONAS.md → 9 cognitive archetypes
• MCP.md → Model Context Protocol patterns
• 18 Slash Commands → Specialized workflows
• 19 Shared Resources → Advanced cfgs

Installation

SuperClaude installs globally → ~/.claude/ ∀ projects.

Directory Structure

~/.claude/
├── CLAUDE.md          # Main cfg (loads others)
├── RULES.md           # Ops rules & standards  
├── PERSONAS.md        # 9 cognitive archetypes
├── MCP.md             # Model Context Protocol ops
└── commands/          # 17 specialized slash commands + index
    ├── analyze.md     ├── build.md       ├── cleanup.md
    ├── deploy.md      ├── design.md      ├── dev-setup.md
    ├── document.md    ├── estimate.md    ├── explain.md
    ├── git.md         ├── improve.md     ├── index.md
    ├── load.md        ├── migrate.md     ├── scan.md
    ├── spawn.md       ├── test.md        ├── troubleshoot.md
    └── shared/        # 19 cfg resources
        ├── ambiguity-check.yml    ├── audit.yml
        ├── checkpoint.yml         ├── cleanup-patterns.yml
        ├── command-memory.yml     ├── documentation-dirs.yml
        ├── evidence.yml           ├── git-operations.yml
        ├── git-workflow.yml       ├── impl.yml
        ├── loading-cfg.yml        ├── mcp-flags.yml
        ├── patterns.yml           ├── performance-monitoring.yml
        ├── planning-mode.yml      ├── research-first.yml
        ├── thinking-modes.yml     ├── ultracompressed.yml
        └── validation.yml

Quick Install (Recommended)

git clone https://github.com/your-username/SuperClaude.git
cd SuperClaude
./install.sh

Manual Install

# 1. Create structure
mkdir -p ~/.claude/commands/shared

# 2. Copy cfg files
cp CLAUDE.md RULES.md PERSONAS.md MCP.md ~/.claude/

# 3. Copy commands
cp .claude/commands/*.md ~/.claude/commands/

# 4. Copy shared resources  
cp .claude/commands/shared/*.yml ~/.claude/commands/shared/

Verify Installation

# Check installation
ls -la ~/.claude/          # Should show 4 main files
ls -la ~/.claude/commands/ # Should show 17 files (16 commands + index)

# Test usage
# Open any project in Claude Code & try:
/user:analyze --code
/persona:architect

How to Use SuperClaude

Core Usage Patterns

1. Personas - Cognitive Archetypes

Activate specialized thinking w/ /persona:<name>:

Persona	Focus	Use When	Example
architect	Systems design, long-term maintainability	Planning large systems	/persona:architect → /user:design --api --ddd
frontend	UX, visual interfaces	UI/UX work	/persona:frontend → /user:build --react
backend	Performance, reliability, APIs	Server-side dev	/persona:backend → /user:build --api
analyzer	Root cause analysis, evidence-based	Debugging complex issues	/persona:analyzer → /user:troubleshoot --investigate
security	Threat modeling, secure by default	Security reviews	/persona:security → /user:scan --security
mentor	Teaching, guided discovery	Learning/explaining	/persona:mentor → /user:explain --depth
refactorer	Code quality, simplification	Code improvement	/persona:refactorer → /user:improve --quality
performance	Speed optimization, bottlenecks	Performance tuning	/persona:performance → /user:improve --performance
qa	Quality assurance, testing	Testing workflows	/persona:qa → /user:test --coverage

2. Slash Commands - Specialized Workflows

Universal Flags (∀ commands):

Planning & Thinking:

• --plan - Show execution plan before running
• --think - Standard analysis mode (multi-file context)
• --think-hard - Deep analysis mode (architecture level)
• --ultrathink - Critical analysis mode (system-wide)

Documentation Control:

• --ultracompressed / --uc - ~70% token reduction mode

MCP Server Control:

• --c7 / --no-c7 - Enable/disable Context7 documentation
• --seq / --no-seq - Enable/disable Sequential thinking
• --magic / --no-magic - Enable/disable Magic UI builder
• --pup / --no-pup - Enable/disable Puppeteer browser
• --all-mcp - Enable all MCP servers
• --no-mcp - Disable all MCP servers (native tools only)

Dev Commands (3):

• /user:build - Universal project builder
  • --init (new project), --feature (add feature), --react (React app), --api (backend), --tdd (test-driven)
• /user:dev-setup - Dev env setup
  • --install (tools), --ci (CI/CD), --monitor (monitoring)
• /user:test - Testing framework
  • --coverage (coverage), --watch (watch mode), --e2e (end-to-end)

Analysis & Improvement Commands (4):

• /user:analyze - Multi-dimensional analysis
  • --code (code review), --architecture (design), --profile (performance), --security (vulnerabilities)
• /user:troubleshoot - Debug & fix issues
  • --investigate (explore), --fix (repair), --five-whys (root cause), --prod (production)
• /user:improve - Enhance code/performance
  • --quality (refactor), --performance (optimize), --iterate (continuous), --threshold (target %)
• /user:explain - Deep explanations
  • --depth (complexity level), --visual (diagrams), --examples (code samples)

Ops Commands (6):

• /user:deploy - App deployment
  • --env (environment), --rollback (revert)
• /user:migrate - DB/code migration
  • --dry-run (preview), --rollback (revert)
• /user:scan - Security & validation
  • --validate (verify), --security (vulnerabilities), --owasp (security scan), --deps (dependencies)
• /user:estimate - Time/complexity predictions
  • --detailed (breakdown), --worst-case (pessimistic)
• /user:cleanup - Project maintenance
  • --code (clean code), --files (artifacts), --deps (dependencies), --git (git cleanup), --all (everything), --dry-run (preview)
• /user:git - Git workflow mgmt
  • --status (comprehensive status), --commit (create commits), --branch (manage branches), --sync (fetch/pull/push), --merge (merge branches), --stash (stash changes), --history (view history), --checkpoint (create checkpoint), --rollback (revert changes)

Design & Architecture Commands (1):

• /user:design - System design
  • --api (REST), --ddd (domain-driven), --prd (requirements), --openapi (specs), --graphql (GraphQL), --bounded-context (DDD contexts)

Workflow Commands (2):

• /user:spawn - Create specialized sub-agent
  • --task (specific assignment)
• /user:document - Documentation creation
  • --api (API docs), --user (user guides)

System Commands (1):

• /user:load - Load project context
  • --depth (analysis level)

3. MCP Integration - Intelligent Tool Usage

SuperClaude: auto & manual control over Model Context Protocol tools:

Manual Control w/ Flags:

# Explicit MCP control
/user:build --react --magic          # Force Magic UI builder
/user:analyze --code --no-c7         # Disable Context7
/user:troubleshoot --seq --think     # Sequential + thinking mode
/user:test --e2e --pup              # Force Puppeteer for testing
/user:explain --no-mcp              # Use only native tools

# Combine multiple MCPs
/user:design --api --seq --c7       # Sequential planning + docs
/user:build --react --magic --pup   # UI generation + testing

Auto Activation:

Context7 (C7) - Docs & Libraries:

# Auto activation:
"How to use React hooks?" → C7 resolve-library-id → get-docs
"Express.js auth" → C7 get-docs → impl

# Manual w/ personas:
/persona:mentor → asks about lib → C7 provides learning resources

Sequential - Complex Analysis:

# Auto activation:
"Why is my app slow?" → Sequential analysis → optimization plan
"Design microservices architecture" → Sequential system design

# Manual w/ personas:
/persona:architect → /user:design → Sequential long-term thinking
/persona:analyzer → /user:troubleshoot → Sequential root cause analysis

Magic UI Builder - Component Generation:

# Auto activation:
"I need a dashboard" → Magic builder → component integration
"Create a form component" → Magic builder → refiner if needed

# Manual w/ personas:
/persona:frontend → UI request → Magic + Puppeteer testing

Puppeteer - Browser Testing:

# Auto activation:
UI components → Puppeteer validation
Performance testing → Puppeteer metrics

# Manual w/ personas:
/persona:qa → testing workflows → Puppeteer comprehensive testing
/persona:performance → /user:improve → Puppeteer performance monitoring

4. Planning Mode

Default: Execute immediately Control: Add --plan → preview before execution

Ex: /user:deploy --plan → show plan first

5. Thinking Modes

Control analysis depth via flags:

/user:analyze --code                    # Basic
/user:analyze --code --think           # Standard (~4K)
/user:design --api --think-hard        # Deep (~10K)
/user:troubleshoot --prod --ultrathink # Critical (~32K)

Natural language: "think about X" / "think hard about Y" / "ultrathink Z"

6. Research-First Standards

Auto Research:

• External libs → C7 docs lookup
• UI components → Magic search
• API integration → official docs
• Performance → benchmarks

Workflow: Detect → Research → Cite → Implement

Ex:

# ❌ Blocked w/o docs
import { fn } from 'unknown-lib'

# ✓ Proceeds w/ citation  
// Source: React docs
import { useState } from 'react'

Workflow Examples

Full-Stack Dev

/persona:architect → /user:load --depth deep → /user:analyze --architecture
/user:design --api --ddd → /user:estimate --detailed
/persona:backend → /user:build --api
/persona:frontend → /user:build --react → /user:test --coverage
/persona:security → /user:scan --security → /user:improve --quality
/user:cleanup --all → /user:deploy --env staging

Debug & Performance

/persona:analyzer → /user:troubleshoot --investigate --prod → /user:analyze --profile
"think hard about performance bottlenecks" → /user:troubleshoot --five-whys
/persona:performance → /user:improve --performance --iterate --threshold 90%
/persona:qa → /user:test --e2e → /user:scan --validate

Learning & Mentoring

/persona:mentor → /user:explain --depth beginner --visual --examples
/user:document --user → /user:build --tdd → /user:analyze --code

Git Workflow

/user:git --status → /user:git --branch feature/new-component
/user:build --react --magic → /user:test --coverage → /user:git --commit "feat: Add dashboard"
/user:git --sync → /user:git --merge develop --think → /user:git --push
/user:git --history → /user:git --checkpoint before-refactor → /user:cleanup --git

UltraCompressed Mode - 70% Token Reduction

Auto: Context >70% | Token budget | "minimal tokens" Manual: /user:document --uc | /user:explain --uc "OAuth"

Features:

• Telegram-style: Remove articles/conjunctions/prepositions
• Symbols: →(to), &(and), @(at), w/(with), +(add), -(remove)
• Abbrevs: cfg(config), fn(function), impl(implementation)
• Auto-legend: @ doc start w/ used symbols/abbrevs
• Format: YAML>JSON>tables>lists>prose

Transform Ex:

# Normal (45): "This comprehensive guide provides detailed instructions for configuring the authentication system including all environment variables and dependencies"
# UltraCompressed (14): "Auth cfg guide: env vars & deps"

Docs Directory Standards

Separation: ops reports vs project docs

.claudedocs/              # Claude ops docs
├── audit/ reports/ summaries/ metrics/ incidents/

/docs                     # Project docs  
├── api/ guides/ architecture/ development/

Auto Reports: analyze→reports/ | scan→reports/ | test→metrics/ | troubleshoot→incidents/

Manual Docs: /user:document → API→/docs/api/ | guides→/docs/guides/

Model Selection

• Simple → sonnet (cost-effective)
• Complex → sonnet-4 (balanced)
• Critical → opus-4 (max capability)

Context Mgmt

/compact  # Smart reduction
/clear    # Fresh start
/model    # Switch models

Troubleshooting

Commands not working: ls ~/.claude/commands/ (should show 17 files)

Planning: Add --plan flag → /user:deploy --plan

Personas: /persona:architect → /persona:security → /user:scan --security

MCP: "React docs" → C7 | "slow app" → Sequential

Help

• Install issues: ./install.sh again
• Cmd ref: /user:load in project
• Advanced: Read ~/.claude/commands/
• Config: Modify ~/.claude/

Update & Maintenance

Update:

cd SuperClaude && git pull && ./install.sh

Backup:

cp -r ~/.claude/ ~/.claude.backup.$(date +%Y%m%d)

Uninstall:

rm -rf ~/.claude/

---

SuperClaude v4.0.0 - Cfg framework, not executable code