External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 09:46:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: comprehensive documentation update and command system enhancement

Browse Source 
- Updated all documentation files for improved coherence and consistency
- Enhanced command guides with clearer examples and workflows
- Improved installation instructions and troubleshooting sections
- Refined personas guide with better auto-activation explanations
- Standardized tone and messaging across all documentation
- Added comprehensive cross-references between guide sections

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK 2025-07-14 19:45:00 +02:00
parent 90716ab7b8
commit 64455cc91c
6 changed files with 175 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
Docs/commands-guide.md
View File

@ -1,16 +1,16 @@
# SuperClaude Commands Guide 🛠️
## 💡 Don't Overthink It - SuperClaude Picks the Right Tools
## 💡 Don't Overthink It - SuperClaude Tries to Help
**The truth about these 15 commands**: You don't need to memorize them. Just start with `/analyze` or `/build` and let SuperClaude figure out the rest!
**The truth about these 15 commands**: You don't need to memorize them. Just start with `/sc:analyze` or `/sc:build` and see what happens!
**Here's how it actually works:**
**Here's how it usually works:**
- Type `/` in Claude Code → See available commands
- Use basic ones like `/analyze`, `/build`, `/improve`
- **SuperClaude automatically picks the best tools and experts** for each situation
- Use basic ones like `/sc:analyze`, `/sc:build`, `/sc:improve`
- **SuperClaude tries to pick helpful tools and experts** for each situation
- More commands become useful as you get comfortable
**Auto-activation is the secret sauce** 🪄 - SuperClaude detects what you're trying to do and activates the right specialists (security expert, performance optimizer, etc.) without you managing any of it.
**Auto-activation is pretty neat** 🪄 - SuperClaude attempts to detect what you're trying to do and activate relevant specialists (security expert, performance optimizer, etc.) without you managing it. Usually works well! 😊
---
@ -19,13 +19,13 @@
**Start here** (no reading required):
```bash
/sc:help # See what's available
/sc:analyze src/ # Smart analysis of your code
/sc:build # Intelligent project building
/sc:improve messy-file.js # Clean up code automatically
/sc:troubleshoot "error" # Get help with problems
/sc:analyze src/ # Tries to analyze your code smartly
/sc:build # Attempts intelligent project building
/sc:improve messy-file.js # Tries to clean up code
/sc:troubleshoot "error" # Attempts to help with problems
```
**That's honestly enough to get started.** Everything else below is here when you get curious about what other tools are available.
**That's honestly enough to get started.** Everything else below is here when you get curious about what other tools are available. 🛠️
---
@ -37,35 +37,35 @@ A practical guide to all 15 SuperClaude slash commands. We'll be honest about wh
| Command | Purpose | Auto-Activates | Best For |
|---------|---------|-----------------|----------|
| `/analyze` | Smart code analysis | Security/performance experts | Finding issues, understanding codebases |
| `/build` | Intelligent building | Frontend/backend specialists | Compilation, bundling, deployment prep |
| `/improve` | Automatic code cleanup | Quality experts | Refactoring, optimization, quality fixes |
| `/troubleshoot` | Problem investigation | Debug specialists | Debugging, issue investigation |
| `/test` | Smart testing | QA experts | Running tests, coverage analysis |
| `/document` | Auto documentation | Writing specialists | README files, code comments, guides |
| `/git` | Enhanced git workflows | DevOps specialists | Smart commits, branch management |
| `/design` | System design help | Architecture experts | Architecture planning, API design |
| `/explain` | Learning assistant | Teaching specialists | Learning concepts, understanding code |
| `/cleanup` | Debt reduction | Refactoring experts | Removing dead code, organizing files |
| `/scan` | Security/quality scans | Security experts | Vulnerability detection, compliance |
| `/load` | Context understanding | Analysis experts | Project analysis, codebase understanding |
| `/estimate` | Smart estimation | Planning experts | Time/effort planning, complexity analysis |
| `/spawn` | Complex workflows | Orchestration system | Multi-step operations, workflow automation |
| `/task` | Project management | Planning system | Long-term feature planning, task tracking |
| `/sc:analyze` | Smart code analysis | Security/performance experts | Finding issues, understanding codebases |
| `/sc:build` | Intelligent building | Frontend/backend specialists | Compilation, bundling, deployment prep |
| `/sc:improve` | Automatic code cleanup | Quality experts | Refactoring, optimization, quality fixes |
| `/sc:troubleshoot` | Problem investigation | Debug specialists | Debugging, issue investigation |
| `/sc:test` | Smart testing | QA experts | Running tests, coverage analysis |
| `/sc:document` | Auto documentation | Writing specialists | README files, code comments, guides |
| `/sc:git` | Enhanced git workflows | DevOps specialists | Smart commits, branch management |
| `/sc:design` | System design help | Architecture experts | Architecture planning, API design |
| `/sc:explain` | Learning assistant | Teaching specialists | Learning concepts, understanding code |
| `/sc:cleanup` | Debt reduction | Refactoring experts | Removing dead code, organizing files |
| `/sc:load` | Context understanding | Analysis experts | Project analysis, codebase understanding |
| `/sc:estimate` | Smart estimation | Planning experts | Time/effort planning, complexity analysis |
| `/sc:spawn` | Complex workflows | Orchestration system | Multi-step operations, workflow automation |
| `/sc:task` | Project management | Planning system | Long-term feature planning, task tracking |
| `/sc:index` | Command navigation | Help system | Finding the right command for your task |
**Pro tip**: Just try the ones that sound useful. SuperClaude will automatically activate the right experts and tools for each situation! 🎯
**Pro tip**: Just try the ones that sound useful. SuperClaude usually tries to activate helpful experts and tools for each situation! 🎯
## Development Commands 🔨
### `/build` - Project Building
**What it does**: Builds, compiles, and packages projects with smart error handling.
**The easy way**: Just type `/build` and SuperClaude figures out your build system automatically! 🎯
**The easy way**: Just type `/sc:build` and SuperClaude tries to figure out your build system! 🎯
**When to use it**:
- You need to compile/bundle your project (just try `/build`)
- You need to compile/bundle your project (just try `/sc:build`)
- Build process is failing and you want help debugging
- Setting up build optimization (it auto-detects what you need)
- Setting up build optimization (it tries to detect what you need)
- Preparing for deployment
**Basic syntax**:
@ -135,13 +135,13 @@ A practical guide to all 15 SuperClaude slash commands. We'll be honest about wh
### `/analyze` - Code Analysis
**What it does**: Comprehensive analysis of code quality, security, performance, and architecture.
**The magic**: SuperClaude automatically detects what kind of analysis you need and activates the right experts! 🔍
**The helpful part**: SuperClaude tries to detect what kind of analysis you need and usually picks relevant experts! 🔍
**When to use it**:
- Understanding unfamiliar codebases (just point it at any folder)
- Finding security vulnerabilities (security expert auto-activates)
- Performance bottleneck hunting (performance expert jumps in)
- Code quality assessment (quality specialist takes over)
- Finding security vulnerabilities (security expert usually jumps in)
- Performance bottleneck hunting (performance expert usually helps)
- Code quality assessment (quality specialist often takes over)
**Basic syntax**:
```bash
@ -448,7 +448,7 @@ A practical guide to all 15 SuperClaude slash commands. We'll be honest about wh
```
**Gotchas**:
- Still experimental - may not persist perfectly across sessions
- Still experimental - doesn't always persist across sessions reliably 😅
- Better for planning than actual project management
- Works best when you're specific about requirements
@ -674,11 +674,11 @@ A practical guide to all 15 SuperClaude slash commands. We'll be honest about wh
**The real truth about these commands** 💯:
- **Just try them** - You don't need to study this guide first
- **Start with the basics** - `/analyze`, `/build`, `/improve` cover most needs
- **Let auto-activation work** - SuperClaude picks the right experts automatically
- **Let auto-activation work** - SuperClaude usually picks helpful experts
- **Experiment freely** - Use `--preview` if you want to see what would happen first
**Still rough around the edges:**
- Complex orchestration (spawn, task) may not work perfectly
- Complex orchestration (spawn, task) can be a bit flaky
- Some analysis depends heavily on your project setup
- Error handling could be better in some commands

18
Docs/flags-guide.md
View File

@ -2,13 +2,13 @@
## 🤖 Most Flags Activate Automatically - Don't Stress About It!
**The honest truth**: You don't need to memorize these flags. SuperClaude automatically adds the right ones based on what you're doing!
**The honest truth**: You don't need to memorize these flags. SuperClaude usually tries to add helpful ones based on what you're doing!
**Here's what actually happens:**
- You type `/analyze auth.js`
- SuperClaude detects it's security-related code
- **Automatically adds** `--persona-security`, `--focus security`, `--validate`
- You get expert security analysis without managing any flags
- **Usually adds** `--persona-security`, `--focus security`, `--validate`
- You often get expert security analysis without managing any flags
**When might you manually use flags?**
- You want to **override** what SuperClaude picked (rare)
@ -314,7 +314,7 @@ Direct SuperClaude's attention to specific areas.
## Auto-Activation Examples 🤖
SuperClaude automatically adds flags based on context. Here's when:
SuperClaude usually adds flags based on context. Here's when it tries:
### Complexity-Based
```bash
@ -493,10 +493,10 @@ SuperClaude automatically adds flags based on context. Here's when:
## Tips for Effective Flag Usage 💡
### Starting Out (The Honest Truth)
1. **Just ignore flags at first** - Auto-activation handles 90% of cases perfectly
1. **Just ignore flags at first** - Auto-activation handles most cases pretty well
2. **Watch what gets auto-activated** - You'll learn by seeing what SuperClaude picks
3. **Use `--help` when curious** - Many commands show what flags are available
4. **Trust the automation** - SuperClaude usually picks better than manual selection
4. **Trust the automation** - SuperClaude usually picks reasonable defaults
### Getting Advanced (If You Want To)
1. **Experiment with overrides** - Try `--persona-security` on non-security code for different perspectives
@ -515,13 +515,13 @@ SuperClaude automatically adds flags based on context. Here's when:
## Final Notes 📝
**The real truth about flags** 💯:
- **Auto-activation is usually better** than manual flag selection
- **Auto-activation usually works pretty well** compared to manual flag selection
- **You can ignore most of this guide** and just use basic commands
- **Flags are here when you want them** - not because you need them
- **Learning emerges naturally** through use, not through studying
- **Learning happens naturally** through use, not through studying guides 😊
**Don't feel overwhelmed** 🧘‍♂️:
- SuperClaude is designed to work great without flag knowledge
- SuperClaude tries to work well without flag knowledge
- The detailed info above is for curiosity, not necessity
- Auto-activation keeps getting smarter based on usage patterns
- You're not missing out by not memorizing flags

4
Docs/installation-guide.md
View File

@ -11,7 +11,7 @@ python3 SuperClaude.py install --quick
# That's it! 🎉
```
**What just happened?** SuperClaude set up everything you need automatically. No complex configuration, no dependency hunting, no setup headaches.
**What just happened?** SuperClaude tried to set up everything you need. Usually no complex configuration, dependency hunting, or setup headaches! 🎉
---
@ -463,7 +463,7 @@ python3 SuperClaude.py install --profile developer --dev-hooks
**Now that SuperClaude is installed (that was easy, right?):**
1. **Just start using it** - Try `/analyze some-file.js` or `/build` and see what happens ✨
2. **Don't stress about learning** - SuperClaude figures out what you need automatically
2. **Don't stress about learning** - SuperClaude usually figures out what you need
3. **Experiment freely** - Commands like `/improve` and `/troubleshoot` are pretty forgiving
4. **Read guides if curious** - Check `Docs/` when you want to understand what just happened
5. **Give feedback** - Let us know what works and what doesn't

42
Docs/personas-guide.md
View File

@ -2,13 +2,13 @@
## 🎭 Personas Auto-Activate - No Need to Choose!
**The simple truth**: You don't need to pick personas or memorize what they do. SuperClaude automatically brings in the right expert for each situation!
**The simple truth**: You don't need to pick personas or memorize what they do. SuperClaude usually tries to bring in helpful experts for each situation!
**Here's what actually happens:**
- You type `/analyze auth.js` → Security expert automatically jumps in 🛡️
- You work on React components → Frontend specialist takes over 🎨
- You debug performance issues → Performance optimizer activates ⚡
- You write documentation → Professional writer helps out ✍️
- You type `/analyze auth.js` → Security expert usually jumps in 🛡️
- You work on React components → Frontend specialist often takes over 🎨
- You debug performance issues → Performance optimizer often helps ⚡
- You write documentation → Professional writer usually helps out ✍️
**It's like having a smart team** that knows when to jump in and help, without you managing who does what.
@ -34,22 +34,22 @@ Think of SuperClaude personas as having a team of specialists on demand. Each pe
## What Are Personas? 🤔
**Personas are AI specialists** that automatically adapt SuperClaude's behavior for different types of work. Instead of generic responses, you get expert-level help from the right specialist.
**Personas are AI specialists** that try to adapt SuperClaude's behavior for different types of work. Instead of generic responses, you often get expert-level help from relevant specialists.
**How they actually work in practice:**
- **Auto-activation** - SuperClaude automatically picks the right expert (90% of the time this is all you need!)
- **Auto-activation** - SuperClaude usually tries to pick helpful experts (most of the time this works pretty well!)
- **Smart detection** - Recognizes security work, frontend tasks, performance issues, etc.
- **Seamless switching** - Different experts jump in as needed within the same conversation
- **Team coordination** - Multiple experts collaborate automatically on complex tasks
- **Team coordination** - Multiple experts often coordinate on complex tasks
- **Manual override available** - You can explicitly choose with `--persona-name` flags when you want a different perspective
**Why this matters (automatically):**
- Get expert-level advice without knowing which expert to ask
- Better decision-making aligned with what you're actually working on
**Why this matters:**
- Often get expert-level advice without knowing which expert to ask
- Usually get better decision-making aligned with what you're actually working on
- More focused and relevant responses based on the task
- Access to specialized workflows that activate when useful
**The magic**: You just work on your stuff, and the right experts show up when needed. 🎯
**The neat part**: You just work on your stuff, and helpful experts usually show up when needed. 🎯
## The SuperClaude Team 👥
@ -107,7 +107,7 @@ Think of SuperClaude personas as having a team of specialists on demand. Each pe
**Performance budgets they enforce**:
- Load time: <3s on 3G, <1s on WiFi
- Bundle size: <500KB initial, <2MB total
- Accessibility: 90%+ WCAG compliance
- Accessibility: WCAG compliance target
**Example workflows**:
```bash
@ -756,14 +756,14 @@ Personas often work together automatically. Here are common collaboration patter
### Auto-Activation Triggers
**High confidence triggers** (90%+ activation):
**Strong triggers** (usually work well):
- "security audit" → 🛡️ security
- "UI component" → 🎨 frontend
- "UI component" → 🎨 frontend
- "API design" → ⚙️ backend
- "system architecture" → 🏗️ architect
- "debug issue" → 🔍 analyzer
**Medium confidence triggers** (70-90% activation):
**Moderate triggers** (often work):
- "improve performance" → ⚡ performance
- "write tests" → 🧪 qa
- "clean up code" → 🔄 refactorer
@ -843,14 +843,14 @@ Personas often work together automatically. Here are common collaboration patter
## Final Notes 📝
**The real truth about personas** 💯:
- **Auto-activation is usually better** than trying to pick the right expert yourself
- **You can completely ignore this guide** and still get expert help automatically
- **Auto-activation usually works pretty well** compared to trying to pick experts yourself
- **You can completely ignore this guide** and still often get helpful expert assistance
- **Personas exist to help you** - not to create complexity you need to manage
- **Learning happens naturally** through use, not through studying persona descriptions
- **Learning happens naturally** through use, not through studying persona descriptions 😊
**Don't feel overwhelmed by the team** 🧘‍♂️:
- You don't need to know what each persona does
- SuperClaude handles expert selection intelligently
- SuperClaude usually handles expert selection reasonably well
- The detailed descriptions above are for curiosity, not necessity
- You're not missing anything by letting auto-activation work
@ -868,4 +868,4 @@ Personas often work together automatically. Here are common collaboration patter
---
*Behind all this apparent complexity of having 11 specialists, SuperClaude is actually simple to use. Just start coding and let the experts show up automatically! 🚀*
*Behind all this apparent complexity of having 11 specialists, SuperClaude tries to be simple to use. Just start coding and helpful experts usually show up when needed! 🚀*

126
Docs/superclaude-user-guide.md
View File

@ -6,7 +6,7 @@
You don't need to learn all the commands, flags, and personas. Just start using it! 🎈
SuperClaude has an **intelligent routing system** that figures out what you need automatically:
SuperClaude has an **intelligent routing system** that tries to figure out what you need:
- Type `/analyze some-code/` → It picks the right analysis tools
- Ask about security → Security expert auto-activates
- Work on frontend → UI specialist takes over
@ -72,14 +72,14 @@ SuperClaude makes Claude Code smarter for development work. Instead of generic r
**The honest truth**: We just released v3.0 and it's fresh out of beta. It works pretty well for what it does, but you should expect some rough edges as we continue improving things. We built this because we wanted Claude Code to be more helpful for real software development workflows.
**The magic part?** You don't need to manage any of this complexity. Just use normal commands like `/analyze` or `/build` and SuperClaude automatically figures out which experts to involve and what tools to use. 🪄
**The neat part?** You don't need to manage any of this complexity. Just use normal commands like `/analyze` or `/build` and SuperClaude usually figures out which experts to involve and what tools to use. 🪄
### What SuperClaude Adds ✨
**🛠️ 15 Specialized Commands** *(that auto-activate intelligently)*
- Development tools: `/build`, `/dev-setup`, `/design`
- Analysis tools: `/analyze`, `/review`, `/troubleshoot`
- Quality tools: `/improve`, `/scan`, `/test`
- Development tools: `/build`, `/design`
- Analysis tools: `/analyze`, `/troubleshoot`, `/explain`
- Quality tools: `/improve`, `/cleanup`, `/test`
- Plus utilities for documentation, git, deployment, and more
- **You just use them** - SuperClaude handles the complexity automatically
@ -107,7 +107,7 @@ SuperClaude makes Claude Code smarter for development work. Instead of generic r
- Smart compression when context gets full
- Symbol system for efficient communication
- Performance optimization for large operations
- **Automatic activation** when needed for large projects
- **Usually activates** when needed for large projects
### Current Status (v3.0) 📊
@ -142,7 +142,7 @@ We're pretty happy with v3 as a foundation, but there's definitely room for impr
**You don't see any of this complexity** - it just feels like Claude got way smarter about development stuff.
The beauty is that most of this happens automatically. You make a request, SuperClaude figures out the best approach, and executes with appropriate tools and expertise. No configuration, no setup, no learning curve - just better results. ✨
The nice thing is that most of this usually happens automatically. You make a request, SuperClaude tries to figure out a good approach, and executes with appropriate tools and expertise. Usually no configuration or setup needed - just hopefully better results. ✨
### Quick Feature Overview 🎯
@ -155,7 +155,7 @@ The beauty is that most of this happens automatically. You make a request, Super
| **Modes** | 3 operational modes for different workflows | [This guide](#the-three-operational-modes-🎭) |
| **Orchestrator** | The smart routing that makes it all work | [This guide](#the-orchestrator-system-🎯) |
**Remember**: You can use SuperClaude effectively without reading any of these guides. They're here when you get curious about how the magic works! 🎪
**Remember**: You can use SuperClaude effectively without reading any of these guides. They're here when you get curious about how it works! 🎪
---
@ -171,26 +171,26 @@ Commands are specialized tools that handle specific types of development work. I
**Development** 🔨
- `/build` - Project building, compilation, bundling
- `/dev-setup` - Development environment configuration
- `/design` - System architecture and component design
**Analysis** 🔍
- `/analyze` - Comprehensive code and system analysis
- `/review` - Code review and quality assessment
- `/troubleshoot` - Problem investigation and debugging
- `/explain` - Educational explanations and learning
**Quality** ✨
- `/improve` - Code enhancement and optimization
- `/scan` - Security and quality scanning
- `/cleanup` - Technical debt reduction
- `/test` - Testing and coverage analysis
**Utilities** 🔧
- `/document` - Documentation creation
- `/deploy` - Deployment operations
- `/git` - Enhanced git workflows
- `/migrate` - Migration management
- `/load` - Project context loading
- `/estimate` - Project estimation
- `/task` - Long-term project management
- `/spawn` - Complex operation orchestration
- `/index` - Command navigation and help
Each command has its own flags, auto-activates appropriate personas, and integrates with relevant MCP servers. For detailed examples and usage patterns, see the [Commands Guide](commands-guide.md).
@ -225,7 +225,7 @@ Flags change how SuperClaude processes your requests. They're like command-line
- `--scope project` - Set analysis scope
- `--persona-[name]` - Activate specific personas
Flags often auto-activate based on context. For example, security-related requests automatically get `--persona-security` and `--focus security`. See the [Flags Guide](flags-guide.md) for comprehensive details and patterns.
Flags often auto-activate based on context. For example, security-related requests usually get `--persona-security` and `--focus security`. See the [Flags Guide](flags-guide.md) for comprehensive details and patterns.
### Personas: AI Specialists 🎭
@ -250,7 +250,7 @@ Personas are like having a team of specialists available on demand. Each brings
- 👨‍🏫 **mentor** - Education, knowledge transfer
- ✍️ **scribe** - Documentation, technical writing
Personas auto-activate based on request patterns but you can override with `--persona-[name]` flags. Each has different priorities (e.g., security persona prioritizes security over speed). See the [Personas Guide](personas-guide.md) for detailed descriptions and examples.
Personas usually auto-activate based on request patterns but you can override with `--persona-[name]` flags. Each has different priorities (e.g., security persona prioritizes security over speed). See the [Personas Guide](personas-guide.md) for detailed descriptions and examples.
### MCP Servers: External Capabilities 🔧
@ -282,18 +282,18 @@ MCP (Model Context Protocol) servers provide specialized capabilities beyond Cla
- **What it provides**: Cross-browser testing, visual validation, metrics
- **Example**: `/test e2e --play` runs comprehensive browser tests
MCP servers coordinate automatically but you can control them with `--all-mcp`, `--no-mcp`, or specific flags like `--c7`.
MCP servers usually coordinate automatically but you can control them with `--all-mcp`, `--no-mcp`, or specific flags like `--c7`.
### How Components Work Together 🤝
The magic happens when components coordinate:
The neat part is when components coordinate:
**Example: Security Analysis Request**
```bash
/sc:analyze auth-system/ --focus security
```
**What happens automatically:**
**What usually happens:**
1. **Command**: `/analyze` handles code analysis
2. **Flag**: `--focus security` directs attention
3. **Persona**: 🛡️ security specialist auto-activates
@ -302,7 +302,7 @@ The magic happens when components coordinate:
**Result**: Security-focused analysis with threat modeling perspective, systematic methodology, and comprehensive coverage.
This coordination happens for all requests - SuperClaude figures out the best combination of tools and expertise for your specific need.
This coordination usually happens for most requests - SuperClaude tries to figure out a good combination of tools and expertise for your specific need.
---
@ -327,7 +327,7 @@ SuperClaude operates in three distinct modes that optimize different aspects of
- **Usage**: Real-time progress tracking for immediate work
```bash
# SuperClaude automatically creates and manages session tasks
# SuperClaude usually creates and manages session tasks
/sc:build large-project/
# → Creates: "Analyze project structure", "Run build process", "Validate output"
```
@ -372,7 +372,7 @@ SuperClaude operates in three distinct modes that optimize different aspects of
- **Real-Time Updates**: Immediate status changes as work progresses
- **Quality Gates**: Validation before marking tasks complete
**Automatic Task Detection**:
**Task Detection**:
- Multi-step operations (3+ steps) → Creates task breakdown
- Keywords: build, implement, create, fix, optimize → Activates task tracking
- Scope indicators: system, feature, comprehensive → Adds progress monitoring
@ -424,7 +424,7 @@ When introspection mode is active, you'll see these markers:
#### When Introspection Activates
**Automatic activation**:
**Usually activates for**:
- Complex multi-step problems requiring meta-cognitive oversight
- Error recovery when outcomes don't match expectations
- Framework discussions or SuperClaude troubleshooting
@ -478,7 +478,7 @@ When introspection mode is active, you'll see these markers:
#### Activation Strategy
**Automatic activation**:
**Usually activates when**:
- Context usage >75% → Enables compression
- Large-scale operations → Prevents token overflow
- Complex orchestration → Optimizes communication
@ -489,11 +489,11 @@ When introspection mode is active, you'll see these markers:
/sc:improve legacy-system/ --uc --delegate auto # Efficient large operations
```
**Performance Metrics**:
- Target: 30-50% token reduction
- Quality: ≥95% information preservation
- Speed: <100ms compression decisions
- Integration: Seamless framework compliance
**Performance Goals** (still improving!):
- Target: ~30-50% token reduction
- Quality: Tries to preserve ~95% of information
- Speed: Usually <100ms compression decisions
- Integration: Works with framework components
#### Mode Integration
@ -512,7 +512,7 @@ The three modes often work together:
## The Orchestrator System 🎯
The orchestrator is SuperClaude's intelligent routing system that analyzes your requests and coordinates the optimal combination of tools, personas, and integrations. It's what makes SuperClaude feel smart and responsive rather than just a collection of separate tools.
The orchestrator is SuperClaude's intelligent routing system that tries to analyze your requests and coordinate a good combination of tools, personas, and integrations. It's what hopefully makes SuperClaude feel smart and responsive rather than just a collection of separate tools.
### How the Orchestrator Works 🔄
@ -573,13 +573,13 @@ The routing system uses dynamic decision trees to map detected patterns to optim
#### Master Routing Table
| Request Pattern | Auto-Activates | Confidence | Why |
| Request Pattern | Usually Auto-Activates | How Often | Why |
|----------------|----------------|------------|-----|
| "analyze architecture" | 🏗️ architect + --ultrathink + Sequential | 95% | Complex system analysis |
| "create UI component" | 🎨 frontend + Magic + --uc | 90% | Frontend domain with generation |
| "security audit" | 🛡️ security + --ultrathink + Sequential | 95% | Security expertise needed |
| "debug complex issue" | 🔍 analyzer + --think + Sequential | 85% | Investigation methodology |
| "improve performance" | ⚡ performance + --think-hard + Playwright | 90% | Performance expertise + testing |
| "analyze architecture" | 🏗️ architect + --ultrathink + Sequential | Most times | Complex system analysis |
| "create UI component" | 🎨 frontend + Magic + --uc | Pretty often | Frontend domain with generation |
| "security audit" | 🛡️ security + --ultrathink + Sequential | Most times | Security expertise needed |
| "debug complex issue" | 🔍 analyzer + --think + Sequential | Often | Investigation methodology |
| "improve performance" | ⚡ performance + --think-hard + Playwright | Pretty often | Performance expertise + testing |
#### Intelligent Coordination
@ -587,7 +587,7 @@ The routing system uses dynamic decision trees to map detected patterns to optim
```bash
/sc:design user-dashboard --type api
```
**Orchestrator coordinates**:
**Orchestrator usually coordinates**:
- 🏗️ architect persona (system design)
- 🎨 frontend persona (UI design)
- Context7 MCP (framework patterns)
@ -600,7 +600,7 @@ The routing system uses dynamic decision trees to map detected patterns to optim
### Quality Gates & Validation Framework ✅
SuperClaude implements an 8-step validation cycle for all operations:
SuperClaude tries to implement an 8-step validation cycle for operations:
#### 8-Step Quality Process
@ -608,7 +608,7 @@ SuperClaude implements an 8-step validation cycle for all operations:
2. **Type Checking** - Sequential analysis + compatibility verification
3. **Linting** - Context7 rules + quality analysis
4. **Security Review** - Sequential analysis + OWASP compliance
5. **Testing** - Playwright E2E + coverage analysis (≥80% unit, ≥70% integration)
5. **Testing** - Playwright E2E + coverage analysis (aiming for good coverage)
6. **Performance** - Sequential analysis + benchmarking
7. **Documentation** - Context7 patterns + completeness validation
8. **Integration** - Playwright testing + deployment validation
@ -627,7 +627,7 @@ SuperClaude implements an 8-step validation cycle for all operations:
### Performance Optimization ⚡
The orchestrator optimizes for sub-100ms performance targets through several strategies:
The orchestrator tries to optimize for good performance through several strategies:
#### Resource Management
@ -663,7 +663,7 @@ The orchestrator optimizes for sub-100ms performance targets through several str
#### Example 1: Security Analysis Request
```bash
/sc:scan user-auth/ --focus security
/sc:analyze user-auth/ --focus security
```
**Orchestrator Analysis**:
@ -671,7 +671,7 @@ The orchestrator optimizes for sub-100ms performance targets through several str
- Complexity: Moderate (authentication system)
- Operation: Analysis + scanning
**Auto-Coordination**:
**Usually coordinates**:
- 🛡️ security persona (threat modeling perspective)
- Sequential MCP (systematic analysis)
- --validate flag (pre-operation safety check)
@ -689,7 +689,7 @@ The orchestrator optimizes for sub-100ms performance targets through several str
- Complexity: High (performance optimization)
- Operation: Improvement + validation
**Auto-Coordination**:
**Usually coordinates**:
- ⚡ performance persona (primary)
- 🎨 frontend persona (secondary, if UI detected)
- Playwright MCP (performance testing)
@ -707,7 +707,7 @@ The orchestrator optimizes for sub-100ms performance targets through several str
- Complexity: High (enterprise-scale)
- Resources: High token usage predicted
**Auto-Coordination**:
**Usually coordinates**:
- --delegate auto flag (parallel processing)
- --uc flag (token optimization)
- 🏗️ architect persona (system-level analysis)
@ -735,7 +735,7 @@ orchestrator_config:
wave_score_threshold: 0.7
```
The orchestrator continuously learns from successful patterns and optimizes future routing decisions based on outcomes.
The orchestrator tries to learn from successful patterns and improve future routing decisions based on outcomes.
---
@ -745,7 +745,7 @@ SuperClaude operates according to core rules and principles that ensure consiste
### Core Operational Rules ⚖️
These are the non-negotiable rules that SuperClaude always follows:
These are the core rules that SuperClaude tries to follow:
#### File Operation Security 🔐
- **Always Read before Write/Edit** - SuperClaude never modifies files without understanding current content
@ -759,7 +759,7 @@ These are the non-negotiable rules that SuperClaude always follows:
- **Evidence-based progress** - Tasks are only marked complete when there's measurable evidence
- **Single focus protocol** - Only one task is "in_progress" at a time for clarity
- **Quality gates** - All operations include validation steps before completion
- **Context retention** - ≥90% context preservation across operations
- **Context retention** - Tries to preserve context well across operations
**Why this matters**: Ensures reliable progress tracking and prevents work from being lost or forgotten.
@ -830,13 +830,13 @@ Because SuperClaude follows consistent rules, you can predict how it will approa
#### Quality Assurance
The principles ensure high-quality outcomes:
- **No magic changes** - SuperClaude explains its reasoning
- **No breaking changes** - Existing functionality is preserved
- **No security compromises** - Security principles are non-negotiable
- **No technical debt introduction** - Improvements maintain or reduce complexity
- **Tries to avoid magic changes** - SuperClaude usually explains its reasoning
- **Aims for no breaking changes** - Tries to preserve existing functionality
- **Security-conscious** - Security principles are important
- **Debt-aware** - Tries to maintain or reduce complexity
#### Transparency
You always understand what SuperClaude is doing and why:
You should usually understand what SuperClaude is doing and why:
```bash
/sc:analyze --introspect complex-system/
@ -868,7 +868,7 @@ You always understand what SuperClaude is doing and why:
**Request**: "Add authentication to our API"
**Rules Applied**:
- Security persona auto-activates
- Security persona usually auto-activates
- Never compromise on security fundamentals
- Check existing patterns first
- Quality gates include security validation
@ -898,7 +898,7 @@ You always understand what SuperClaude is doing and why:
SuperClaude enforces rules through its quality gate system:
#### Automatic Enforcement
#### Enforcement Approach
- **Pre-operation validation** - Checks risks before starting
- **Real-time monitoring** - Tracks rule compliance during execution
- **Post-operation verification** - Confirms rules were followed
@ -963,7 +963,7 @@ Try these commands to see how SuperClaude automatically chooses the right tools:
/sc:build src/components/
# Security analysis → security persona + Sequential MCP
/sc:scan auth/ --focus security
/sc:analyze auth/ --focus security
# Performance investigation → performance persona + Playwright MCP
/sc:analyze --focus performance slow-endpoints/
@ -986,7 +986,7 @@ When starting work on an unfamiliar project:
# → 🏗️ architect persona provides system understanding
# 3. Check code quality
/sc:scan --focus quality
/sc:analyze --focus quality
# → 🧪 qa persona identifies potential issues
# 4. Review documentation
@ -1062,10 +1062,10 @@ For improving existing code:
#### Security-First Development
```bash
# Development with security focus
/sc:scan --persona-security --focus security
/sc:analyze --persona-security --focus security
/sc:build --validate --safe-mode
/sc:test --type security
/sc:deploy --persona-security --validate
/sc:git --persona-security --validate
```
#### Performance-Optimized Workflow
@ -1074,13 +1074,13 @@ For improving existing code:
/sc:analyze --focus performance --persona-performance
/sc:improve --type performance --benchmark
/sc:test --focus performance --play
/sc:deploy --monitor-performance
/sc:test --focus performance --play
```
#### Team Collaboration Workflow
```bash
# Collaborative development patterns
/sc:review team-code/ --persona-qa --focus quality
/sc:analyze team-code/ --persona-qa --focus quality
/sc:document features/ --persona-scribe --type guide
/sc:git --smart-commit --branch-strategy
/sc:task status # Check team progress
@ -1101,7 +1101,7 @@ For working with enterprise-scale projects:
# → Multi-stage improvements with safety checks
# Comprehensive quality review
/sc:scan enterprise-app/ --delegate folders --focus quality
/sc:analyze enterprise-app/ --delegate folders --focus quality
# → Distributed quality analysis
```
@ -1577,7 +1577,7 @@ Real-world scenarios showing SuperClaude in action. These examples demonstrate h
#### Step 2: Code Quality Assessment
```bash
/sc:scan --focus quality
/sc:analyze --focus quality
```
**Auto-coordination**:
- 🧪 qa persona activates (quality focus)
@ -2922,9 +2922,9 @@ SuperClaude transforms Claude Code from a general-purpose AI assistant into a sp
- **Intelligent orchestration** that coordinates tools automatically
- **Quality-first approach** that maintains safety and reliability
#### The Magic is in the Coordination
#### The Power is in the Coordination
SuperClaude's power comes not from any single feature, but from how components work together:
- Commands activate appropriate personas and MCP servers automatically
- Commands usually activate appropriate personas and MCP servers
- Personas coordinate with each other for multi-domain problems
- The orchestrator optimizes tool selection and resource usage
- Quality gates ensure consistent, reliable outcomes

80
README.md
View File

@ -11,14 +11,14 @@ A framework that extends Claude Code with specialized commands, personas, and MC
## What is SuperClaude? 🤔
SuperClaude extends Claude Code with:
- 🛠️ **15 specialized commands** for development, analysis, and quality tasks
- 🎭 **Smart personas** that adapt behavior for different domains (frontend, security, architecture, etc.)
- 🔧 **MCP server integration** for documentation lookup, UI components, and browser automation
- 📋 **Enhanced task management** with progress tracking and validation
- ⚡ **Token optimization** for more efficient conversations
SuperClaude tries to make Claude Code more helpful for development work by adding:
- 🛠️ **15 specialized commands** for common dev tasks (some work better than others!)
- 🎭 **Smart personas** that usually pick the right expert for different domains
- 🔧 **MCP server integration** for docs, UI components, and browser automation
- 📋 **Task management** that tries to keep track of progress
- ⚡ **Token optimization** to help with longer conversations
This is what we've been working on to make Claude Code more helpful for development workflows.
This is what we've been building to make development workflows smoother. Still rough around the edges, but getting better! 😊
## Current Status 📊
@ -40,27 +40,31 @@ This is what we've been working on to make Claude Code more helpful for developm
### Commands 🛠️
We focused on 15 essential commands for the most common tasks:
**Development**: `/sc:build`, `/sc:dev-setup`
**Analysis**: `/sc:analyze`, `/sc:review`, `/sc:troubleshoot`
**Quality**: `/sc:improve`, `/sc:scan`, `/sc:test`
**Others**: `/sc:document`, `/sc:deploy`, `/sc:git`, `/sc:migrate`, `/sc:estimate`, `/sc:task`, `/sc:design`
**Development**: `/sc:build`, `/sc:design`
**Analysis**: `/sc:analyze`, `/sc:troubleshoot`, `/sc:explain`
**Quality**: `/sc:improve`, `/sc:test`, `/sc:cleanup`
**Others**: `/sc:document`, `/sc:git`, `/sc:estimate`, `/sc:task`, `/sc:index`, `/sc:load`, `/sc:spawn`
### Smart Personas 🎭
Auto-activating specialists that adapt Claude's behavior:
- 🏗️ **architect** - Systems design and architecture
AI specialists that try to jump in when they seem relevant:
- 🏗️ **architect** - Systems design and architecture stuff
- 🎨 **frontend** - UI/UX and accessibility
- ⚙️ **backend** - APIs and infrastructure
- 🔍 **analyzer** - Investigation and root cause analysis
- 🛡️ **security** - Threat modeling and vulnerabilities
- ✍️ **scribe** - Documentation and technical writing
- *...and 5 more*
- 🔍 **analyzer** - Debugging and figuring things out
- 🛡️ **security** - Security concerns and vulnerabilities
- ✍️ **scribe** - Documentation and writing
- *...and 5 more specialists*
*(They don't always pick perfectly, but usually get it right!)*
### MCP Integration 🔧
Specialized servers for different tasks:
- **Context7** - Official library documentation and patterns
- **Sequential** - Complex multi-step analysis and reasoning
- **Magic** - Modern UI component generation
- **Playwright** - Browser automation and E2E testing
External tools that connect when useful:
- **Context7** - Grabs official library docs and patterns
- **Sequential** - Helps with complex multi-step thinking
- **Magic** - Generates modern UI components
- **Playwright** - Browser automation and testing stuff
*(These work pretty well when they connect properly! 🤞)*
## ⚠️ Upgrading from v2? Important!
@ -121,23 +125,25 @@ The installer handles everything: framework files, MCP servers, and Claude Code
## How It Works 🔄
SuperClaude enhances Claude Code through:
SuperClaude tries to enhance Claude Code through:
1. **Framework Files** - Core documentation installed to `~/.claude/` that guides Claude's behavior
2. **Slash Commands** - 15 specialized commands for different development tasks
3. **MCP Servers** - External services that add capabilities like documentation lookup and UI generation
4. **Smart Routing** - Automatic selection of tools and personas based on your requests
1. **Framework Files** - Documentation installed to `~/.claude/` that guides how Claude responds
2. **Slash Commands** - 15 specialized commands for different dev tasks
3. **MCP Servers** - External services that add extra capabilities (when they work!)
4. **Smart Routing** - Attempts to pick the right tools and experts based on what you're doing
Everything is designed to work seamlessly with Claude Code's existing functionality.
Most of the time it plays nicely with Claude Code's existing stuff. 🤝
## What's Coming in v4 🔮
We're working on the next version which will include:
- **Hooks System** - Event-driven enhancements (removed from v3, being redesigned)
- **MCP Suite** - Expanded server ecosystem
- **Better Performance** - Faster response times and smarter caching
- **More Personas** - Additional domain specialists
- **Cross-CLI Support** - Work with other AI coding assistants
We're hoping to work on these things for the next version:
- **Hooks System** - Event-driven stuff (removed from v3, trying to redesign it properly)
- **MCP Suite** - More external tool integrations
- **Better Performance** - Trying to make things faster and less buggy
- **More Personas** - Maybe a few more domain specialists
- **Cross-CLI Support** - Might work with other AI coding assistants
*(No promises on timeline though - we're still figuring v3 out! 😅)*
## Configuration ⚙️
@ -145,7 +151,7 @@ After installation, you can customize SuperClaude by editing:
- `~/.claude/settings.json` - Main configuration
- `~/.claude/*.md` - Framework behavior files
Most users won't need to change anything - it works well out of the box.
Most users probably won't need to change anything - it usually works okay out of the box. 🎛️
## Documentation 📖
@ -201,7 +207,7 @@ A: It was getting complex and buggy. We're redesigning it properly for v4.
A: Currently Claude Code only, but v4 will have broader compatibility.
**Q: Is this stable enough for daily use?**
A: The core features work well, but expect some rough edges since it's a fresh release.
A: The basic stuff works pretty well, but definitely expect some rough edges since it's a fresh release. Probably fine for experimenting! 🧪
## SuperClaude Contributors
@ -222,6 +228,6 @@ MIT - [See LICENSE file for details](https://opensource.org/licenses/MIT)
</a>
---
*Built by developers, for developers. We hope you find it useful! 🙂*
*Built by developers who got tired of generic responses. Hope you find it useful! 🙂*
---