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

📚 Major documentation cleanup: Fix CLI confusion and streamline content

Browse Source 
## Critical Fixes ✅
- **CLI Command Syntax**: Fixed all ambiguous `SuperClaude --version` → `python3 -m SuperClaude --version`
- **Architecture Clarity**: Verified dual architecture documentation (Python CLI + Context Framework)
- **External Dependencies**: Marked unverified APIs as experimental (TWENTYFIRST_API_KEY, MORPH_API_KEY)
- **Installation Instructions**: Clarified NPM package names with verification warnings

## Content Optimization 🗑️
- **Removed unnecessary files**:
  - optimization-guide.md (inappropriate for context files)
  - quick-start-practices.md (duplicate content)
  - Various outdated socratic learning components
- **Updated cross-references**: Fixed all broken links to point to existing, relevant content
- **Consolidated navigation**: Streamlined Reference/README.md documentation matrix

## Technical Accuracy 🎯
- **Command References**: All commands now specify exact usage context (terminal vs Claude Code)
- **Framework Nature**: Consistently explains SuperClaude as context framework, not executable software
- **Installation Verification**: Updated diagnostic scripts with correct Python CLI commands
- **MCP Configuration**: Marked experimental services appropriately

## Impact Summary 📊
- **Files Modified**: 15+ documentation files for accuracy and consistency
- **Files Removed**: 5+ unnecessary/duplicate files
- **Broken Links**: 0 (all cross-references updated)
- **User Clarity**: Significantly improved understanding of dual architecture

Result: Professional documentation that accurately represents SuperClaude's sophisticated
dual architecture (Python CLI installation system + Claude Code context framework).

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
2025-08-21 19:03:25 +02:00
parent c78d5f8c01
commit 41761f405c
43 changed files with 3098 additions and 23245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
Docs/User-Guide/agents.md
View File

@@ -1,7 +1,7 @@
# SuperClaude Agents Guide 🤖
## ✅ Verification Status
- **SuperClaude Version**: v4.0+ Compatible
- **
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Agent Activation**: ✅ All Verified
@@ -11,27 +11,62 @@
Before using this guide, verify agent selection works:
```bash
# Test security agent activation
/sc:implement "JWT authentication"
# Expected: Security engineer should activate automatically
# Test manual agent invocation
@agents-python-expert "explain decorators"
# Example behavior: Python expert responds with detailed explanation
# Test frontend agent activation
# Test security agent auto-activation
/sc:implement "JWT authentication"
# Example behavior: Security engineer should activate automatically
# Test frontend agent auto-activation
/sc:implement "responsive navigation component"
# Expected: Frontend architect + Magic MCP should activate
# Example behavior: Frontend architect + Magic MCP should activate
# Test systematic analysis
/sc:troubleshoot "slow API performance"
# Expected: Root-cause analyst + performance engineer activation
# Example behavior: Root-cause analyst + performance engineer activation
# Test combining manual and auto
/sc:analyze src/
@agents-refactoring-expert "suggest improvements"
# Example behavior: Analysis followed by refactoring suggestions
```
**If tests fail**: Check agent activation patterns in this guide or restart Claude Code session
**If tests fail**: Check agent files exist in `~/.claude/agents/` or restart Claude Code session
## Core Concepts
### What are SuperClaude Agents?
**Agents** are specialized AI domain experts with focused expertise in specific technical areas. Each agent has unique knowledge, behavioral patterns, and problem-solving approaches tailored to their domain.
**Agents** are specialized AI domain experts implemented as context instructions that modify Claude Code's behavior. Each agent is a carefully crafted `.md` file in the `SuperClaude/Agents/` directory containing domain-specific expertise, behavioral patterns, and problem-solving approaches.
**Auto-Activation** means agents automatically engage based on keywords, file types, and task complexity without manual selection. The system analyzes your request and routes to the most appropriate specialists.
**Important**: Agents are NOT separate AI models or software - they are context configurations that Claude Code reads to adopt specialized behaviors.
### Two Ways to Use Agents
#### 1. Manual Invocation with @agents- Prefix
```bash
# Directly invoke a specific agent
@agents-security "review authentication implementation"
@agents-frontend "design responsive navigation"
@agents-architect "plan microservices migration"
```
#### 2. Auto-Activation (Behavioral Routing)
"Auto-activation" means Claude Code reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests. SuperClaude provides behavioral guidelines that Claude follows to route to the most appropriate specialists.
> **📝 How Agent "Auto-Activation" Works**:
> Agent activation isn't automatic system logic - it's behavioral instructions in context files.
> When documentation says agents "auto-activate", it means Claude Code reads instructions to engage
> specific domain expertise based on keywords and patterns in your request. This creates the
> experience of intelligent routing while being transparent about the underlying mechanism.
```bash
# These commands auto-activate relevant agents
/sc:implement "JWT authentication" # → security-engineer auto-activates
/sc:design "React dashboard" # → frontend-architect auto-activates
/sc:troubleshoot "memory leak" # → performance-engineer auto-activates
```
**MCP Servers** provide enhanced capabilities through specialized tools like Context7 (documentation), Sequential (analysis), Magic (UI), Playwright (testing), and Morphllm (code transformation).
@@ -40,12 +75,14 @@ Before using this guide, verify agent selection works:
### Agent Selection Rules
**Priority Hierarchy:**
1. **Keywords** - Direct domain terminology triggers primary agents
2. **File Types** - Extensions activate language/framework specialists
3. **Complexity** - Multi-step tasks engage coordination agents
4. **Context** - Related concepts trigger complementary agents
1. **Manual Override** - @agents-[name] takes precedence over auto-activation
2. **Keywords** - Direct domain terminology triggers primary agents
3. **File Types** - Extensions activate language/framework specialists
4. **Complexity** - Multi-step tasks engage coordination agents
5. **Context** - Related concepts trigger complementary agents
**Conflict Resolution:**
- Manual invocation → Specified agent takes priority
- Multiple matches → Multi-agent coordination
- Unclear context → Requirements analyst activation
- High complexity → System architect oversight
@@ -54,6 +91,7 @@ Before using this guide, verify agent selection works:
**Selection Decision Tree:**
```
Task Analysis →
├─ Manual @agents-? → Use specified agent
├─ Single Domain? → Activate primary agent
├─ Multi-Domain? → Coordinate specialist agents
├─ Complex System? → Add system-architect oversight
@@ -63,19 +101,39 @@ Task Analysis →
## Quick Start Examples
**Automatic Agent Coordination:**
### Manual Agent Invocation
```bash
# Triggers: security-engineer + backend-architect + quality-engineer
# Explicitly call specific agents with @agents- prefix
@agents-python-expert "optimize this data processing pipeline"
@agents-quality-engineer "create comprehensive test suite"
@agents-technical-writer "document this API with examples"
@agents-socratic-mentor "explain this design pattern"
```
### Automatic Agent Coordination
```bash
# Commands that trigger auto-activation
/sc:implement "JWT authentication with rate limiting"
# → Triggers: security-engineer + backend-architect + quality-engineer
# Triggers: frontend-architect + learning-guide + technical-writer
/sc:design "accessible React dashboard with documentation"
# → Triggers: frontend-architect + learning-guide + technical-writer
# Triggers: devops-architect + performance-engineer + root-cause-analyst
/sc:troubleshoot "slow deployment pipeline with intermittent failures"
# → Triggers: devops-architect + performance-engineer + root-cause-analyst
# Triggers: security-engineer + quality-engineer + refactoring-expert
/sc:audit "payment processing security vulnerabilities"
# → Triggers: security-engineer + quality-engineer + refactoring-expert
```
### Combining Manual and Auto Approaches
```bash
# Start with command (auto-activation)
/sc:implement "user profile system"
# Then explicitly add specialist review
@agents-security "review the profile system for OWASP compliance"
@agents-performance-engineer "optimize database queries"
```
---
@@ -437,7 +495,11 @@ Task Analysis →
### Troubleshooting Agent Activation
## 🚨 Quick Troubleshooting
## Troubleshooting
For troubleshooting help, see:
- [Common Issues](../Reference/common-issues.md) - Quick fixes for frequent problems
- [Troubleshooting Guide](../Reference/troubleshooting.md) - Comprehensive problem resolution
### Common Issues (< 2 minutes)
- **No agent activation**: Use domain keywords: "security", "performance", "frontend"
@@ -765,7 +827,7 @@ Add "documented", "explained", or "tutorial" to requests for automatic technical
### Advanced Usage
- **[Behavioral Modes](modes.md)** - Context optimization for enhanced agent coordination
- **[Best Practices](../Reference/quick-start-practices.md)** - Expert techniques for agent optimization
- **[Getting Started](../Getting-Started/quick-start.md)** - Expert techniques for agent optimization
- **[Examples Cookbook](../Reference/examples-cookbook.md)** - Real-world agent coordination patterns
### Development Resources

794
Docs/User-Guide/commands.md
View File

@@ -1,9 +1,65 @@
# SuperClaude Commands Guide
> **Command Context**: This guide covers **Claude Code Commands** (`/sc:` commands). These run inside Claude Code chat, not in your terminal. For installation commands, see [Installation Guide](../Getting-Started/installation.md).
SuperClaude provides 21 commands for Claude Code: `/sc:*` commands for workflows and `@agents-*` for specialists.
## Command Types
| Type | Where Used | Format | Example |
|------|------------|--------|---------|
| **Slash Commands** | Claude Code | `/sc:[command]` | `/sc:implement "feature"` |
| **Agents** | Claude Code | `@agents-[name]` | `@agents-security "review"` |
| **Installation** | Terminal | `SuperClaude [command]` | `SuperClaude install` |
## Quick Test
```bash
# Terminal: Verify installation
python3 -m SuperClaude --version
# Alternative: SuperClaude --version (if installed globally)
# Claude Code: Test commands
/sc:brainstorm "test project" # Should ask discovery questions
/sc:analyze README.md # Should provide analysis
```
**Workflow**: `/sc:brainstorm "idea"` → `/sc:implement "feature"` → `/sc:test`
## 🎯 Understanding SuperClaude Commands
## How SuperClaude Works
SuperClaude provides behavioral context files that Claude Code reads to adopt specialized behaviors. When you type `/sc:implement`, Claude Code reads the `implement.md` context file and follows its behavioral instructions.
**SuperClaude commands are NOT executed by software** - they are context triggers that modify Claude Code's behavior through reading specialized instruction files from the framework.
### Command Types:
- **Slash Commands** (`/sc:*`): Trigger workflow patterns and behavioral modes
- **Agent Invocations** (`@agents-*`): Manually activate specific domain specialists
- **Flags** (`--think`, `--safe-mode`): Modify command behavior and depth
### The Context Mechanism:
1. **User Input**: You type `/sc:implement "auth system"`
2. **Context Loading**: Claude Code reads `~/.claude/SuperClaude/Commands/implement.md`
3. **Behavior Adoption**: Claude applies domain expertise, tool selection, and validation patterns
4. **Enhanced Output**: Structured implementation with security considerations and best practices
**Key Point**: This creates sophisticated development workflows through context management rather than traditional software execution.
### Installation vs Usage Commands
**🖥️ Terminal Commands** (Actual CLI software):
- `SuperClaude install` - Installs the framework components
- `SuperClaude update` - Updates existing installation
- `SuperClaude uninstall` - Removes framework installation
- `python3 -m SuperClaude --version` - Check installation status
**💬 Claude Code Commands** (Context triggers):
- `/sc:brainstorm` - Activates requirements discovery context
- `/sc:implement` - Activates feature development context
- `@agents-security` - Activates security specialist context
- All commands work inside Claude Code chat interface only
## ✅ Verification Status
- **SuperClaude Version**: v4.0+ Compatible
- **Last Updated**: 2025-01-21
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Command Syntax**: ✅ All Verified
@@ -14,38 +70,43 @@
### 🖥️ Terminal Verification (Run in Terminal/CMD)
```bash
# Verify SuperClaude is working
# Verify SuperClaude is working (primary method)
python3 -m SuperClaude --version
# Example output: SuperClaude 4.0.0
# Alternative version check (if installed globally)
SuperClaude --version
# Expected: SuperClaude Framework v4.0+
# Example output: SuperClaude 4.0.0
# Check MCP server connectivity
SuperClaude install --list-components | grep mcp
# Expected: Shows installed MCP components
# Example output: Shows installed MCP components
```
### 💬 Claude Code Testing (Type in Claude Code Chat)
```
# Test basic /sc: command
/sc:brainstorm "test project"
# Expected: Interactive requirements discovery starts
# Example behavior: Interactive requirements discovery starts
# Test command help
/sc:help
# Expected: List of available commands
# Example behavior: List of available commands
```
**If tests fail**: Check [Installation Guide](../Getting-Started/installation.md) or [Troubleshooting](#troubleshooting)
### 📋 Command Quick Reference
### 📝 Command Quick Reference
| Command Type | Where to Run | Format | Purpose |
|-------------|--------------|--------|---------|
| **🖥️ Installation** | Terminal/CMD | `SuperClaude [command]` | Setup and maintenance |
| **🔧 Configuration** | Terminal/CMD | `python3 -m SuperClaude` | Advanced configuration |
| **💬 Development** | Claude Code | `/sc:[command]` | AI-enhanced development |
| **⚡ Workflow** | Claude Code | `/sc:[command] --flags` | Enhanced automation |
| Command Type | Where to Run | Format | Purpose | Example |
|-------------|--------------|--------|---------|----------|
| **🖥️ Installation** | Terminal/CMD | `SuperClaude [command]` | Setup and maintenance | `SuperClaude install` |
| **🔧 Configuration** | Terminal/CMD | `python3 -m SuperClaude [command]` | Advanced configuration | `python3 -m SuperClaude --version` |
| **💬 Slash Commands** | Claude Code | `/sc:[command]` | Workflow automation | `/sc:implement "feature"` |
| **🤖 Agent Invocation** | Claude Code | `@agents-[name]` | Manual specialist activation | `@agents-security "review"` |
| **⚡ Enhanced Flags** | Claude Code | `/sc:[command] --flags` | Behavior modification | `/sc:analyze --think-hard` |
> **Remember**: All `/sc:` commands work inside Claude Code chat, not your terminal.
> **Remember**: All `/sc:` commands and `@agents-` invocations work inside Claude Code chat, not your terminal. They trigger Claude Code to read specific context files from the SuperClaude framework.
## Table of Contents
@@ -59,683 +120,192 @@ SuperClaude install --list-components | grep mcp
## Essential Commands
**Start with these 8 commands for immediate productivity:**
**Core workflow commands for immediate productivity:**
### `/sc:brainstorm` - Project Discovery
**Purpose**: Interactive requirements discovery and project planning
**Syntax**: `/sc:brainstorm "your idea"` `[--strategy systematic|creative]`
**Auto-Activation**: Architect + Analyst + PM specialists, Sequential + Context7 MCP
#### Success Criteria
- [ ] Command executes without errors
- [ ] Generates 3-5 discovery questions relevant to your domain
- [ ] Produces structured requirements document or PRD
- [ ] Maintains discovery context for follow-up questions
**Use Cases**:
- New project planning: `/sc:brainstorm "e-commerce platform"`
- Feature exploration: `/sc:brainstorm "user authentication system"`
- Problem solving: `/sc:brainstorm "slow database queries"`
- Architecture decisions: `/sc:brainstorm "microservices vs monolith"`
**Examples**:
```bash
/sc:brainstorm "mobile todo app" # → Requirements document + PRD
/sc:brainstorm "API performance" --strategy systematic # → Analysis + solutions
```
**Verify:** `/sc:brainstorm "test project"` should ask discovery questions about scope, users, and technology choices
**Test:** Follow-up questions should build on initial responses
**Check:** Output should include actionable requirements or next steps
### `/sc:implement` - Feature Development
**Purpose**: Full-stack feature implementation with intelligent specialist routing
**Syntax**: `/sc:implement "feature description"` `[--type frontend|backend|fullstack] [--focus security|performance]`
**Auto-Activation**: Context-dependent specialists (Frontend, Backend, Security), Context7 + Magic MCP
#### Success Criteria
- [ ] Command activates appropriate domain specialists
- [ ] Generates functional, production-ready code
- [ ] Includes basic error handling and validation
- [ ] Follows project conventions and patterns
**Use Cases**:
- Authentication: `/sc:implement "JWT login system"` → Security specialist + validation
- UI components: `/sc:implement "responsive dashboard"` → Frontend + Magic MCP
- APIs: `/sc:implement "REST user endpoints"` → Backend + Context7 patterns
- Database: `/sc:implement "user schema with relationships"` → Database specialist
**Examples**:
```bash
/sc:implement "user registration with email verification" # → Full auth flow
/sc:implement "payment integration" --focus security # → Secure payment system
```
**Verify:** Code should compile/run without immediate errors
**Test:** `/sc:implement "hello world function"` should produce working code
**Check:** Security specialist should activate for auth-related implementations
- Authentication: `/sc:implement "JWT login system"`
- UI components: `/sc:implement "responsive dashboard"`
- APIs: `/sc:implement "REST user endpoints"`
- Database: `/sc:implement "user schema with relationships"`
### `/sc:analyze` - Code Assessment
**Purpose**: Comprehensive code analysis across quality, security, and performance
**Syntax**: `/sc:analyze [path]` `[--focus quality|security|performance|architecture]`
**Auto-Activation**: Analyzer specialist + domain experts based on focus
**Use Cases**:
- Project health: `/sc:analyze .` → Overall assessment
- Security audit: `/sc:analyze --focus security` → Vulnerability report
- Performance review: `/sc:analyze --focus performance` → Bottleneck identification
- Architecture review: `/sc:analyze --focus architecture` → Design patterns analysis
**Syntax**: `/sc:analyze [path]` `[--focus quality|security|performance|architecture]`
**Examples**:
```bash
/sc:analyze src/ # → Quality + security + performance report
/sc:analyze --focus security --depth deep # → Detailed security audit
```
**Use Cases**:
- Project health: `/sc:analyze .`
- Security audit: `/sc:analyze --focus security`
- Performance review: `/sc:analyze --focus performance`
### `/sc:troubleshoot` - Problem Diagnosis
**Purpose**: Systematic issue diagnosis with root cause analysis
**Syntax**: `/sc:troubleshoot "issue description"` `[--type build|runtime|performance]`
**Auto-Activation**: Analyzer + DevOps specialists, Sequential MCP for systematic debugging
**Use Cases**:
- Runtime errors: `/sc:troubleshoot "500 error on login"` → Error investigation
- Build failures: `/sc:troubleshoot --type build` → Compilation issues
- Performance problems: `/sc:troubleshoot "slow page load"` → Performance analysis
- Integration issues: `/sc:troubleshoot "API timeout errors"` → Connection diagnosis
**Syntax**: `/sc:troubleshoot "issue description"` `[--type build|runtime|performance]`
**Examples**:
```bash
/sc:troubleshoot "users can't login" # → Systematic auth flow analysis
/sc:troubleshoot --type build --fix # → Build errors + suggested fixes
```
**Use Cases**:
- Runtime errors: `/sc:troubleshoot "500 error on login"`
- Build failures: `/sc:troubleshoot --type build`
- Performance problems: `/sc:troubleshoot "slow page load"`
### `/sc:test` - Quality Assurance
**Purpose**: Comprehensive testing with coverage analysis
**Syntax**: `/sc:test` `[--type unit|integration|e2e] [--coverage] [--fix]`
**Auto-Activation**: QA specialist, Playwright MCP for E2E testing
**Use Cases**:
- Full test suite: `/sc:test --coverage` → All tests + coverage report
- Unit testing: `/sc:test --type unit --watch` → Continuous unit tests
- E2E validation: `/sc:test --type e2e` → Browser automation tests
- Test fixing: `/sc:test --fix` → Repair failing tests
**Syntax**: `/sc:test` `[--type unit|integration|e2e] [--coverage] [--fix]`
**Examples**:
```bash
/sc:test --coverage --report # → Complete test run with coverage
/sc:test --type e2e --browsers chrome,firefox # → Cross-browser testing
```
**Use Cases**:
- Full test suite: `/sc:test --coverage`
- Unit testing: `/sc:test --type unit --watch`
- E2E validation: `/sc:test --type e2e`
### `/sc:improve` - Code Enhancement
**Purpose**: Apply systematic code improvements and optimizations
**Syntax**: `/sc:improve [path]` `[--type performance|quality|security] [--preview]`
**Auto-Activation**: Analyzer specialist, Morphllm MCP for pattern-based improvements
**Use Cases**:
- General improvements: `/sc:improve src/` → Code quality enhancements
- Performance optimization: `/sc:improve --type performance` → Speed improvements
- Security hardening: `/sc:improve --type security` → Security best practices
- Refactoring: `/sc:improve --preview --safe-mode` → Safe code refactoring
**Syntax**: `/sc:improve [path]` `[--type performance|quality|security] [--preview]`
**Examples**:
```bash
/sc:improve --type performance --measure-impact # → Performance optimizations
/sc:improve --preview --backup # → Preview changes before applying
```
**Use Cases**:
- General improvements: `/sc:improve src/`
- Performance optimization: `/sc:improve --type performance`
- Security hardening: `/sc:improve --type security`
### `/sc:document` - Documentation Generation
**Purpose**: Generate comprehensive documentation for code and APIs
**Syntax**: `/sc:document [path]` `[--type api|user-guide|technical] [--format markdown|html]`
**Auto-Activation**: Documentation specialist
**Use Cases**:
- API docs: `/sc:document --type api` → OpenAPI/Swagger documentation
- User guides: `/sc:document --type user-guide` → End-user documentation
- Technical docs: `/sc:document --type technical` → Developer documentation
- Inline comments: `/sc:document src/ --inline` → Code comments
**Syntax**: `/sc:document [path]` `[--type api|user-guide|technical] [--format markdown|html]`
**Examples**:
```bash
/sc:document src/api/ --type api --format openapi # → API specification
/sc:document --type user-guide --audience beginners # → User documentation
```
**Use Cases**:
- API docs: `/sc:document --type api`
- User guides: `/sc:document --type user-guide`
- Technical docs: `/sc:document --type technical`
### `/sc:workflow` - Implementation Planning
**Purpose**: Generate structured implementation plans from requirements
**Syntax**: `/sc:workflow "feature description"` `[--strategy agile|waterfall] [--format markdown]`
**Auto-Activation**: Architect + Project Manager specialists, Sequential MCP
**Use Cases**:
- Feature planning: `/sc:workflow "user authentication"` → Implementation roadmap
- Sprint planning: `/sc:workflow --strategy agile` → Agile task breakdown
- Architecture planning: `/sc:workflow "microservices migration"` → Migration strategy
- Timeline estimation: `/sc:workflow --detailed --estimates` → Time and resource planning
**Syntax**: `/sc:workflow "feature description"` `[--strategy agile|waterfall] [--format markdown]`
**Examples**:
```bash
/sc:workflow "real-time chat feature" # → Structured implementation plan
/sc:workflow "payment system" --strategy agile # → Sprint-ready tasks
```
**Use Cases**:
- Feature planning: `/sc:workflow "user authentication"`
- Sprint planning: `/sc:workflow --strategy agile`
- Architecture planning: `/sc:workflow "microservices migration"`
---
## Common Workflows
**Proven command combinations for common development scenarios:**
**Proven command combinations:**
### New Project Setup
```bash
/sc:brainstorm "project concept" # Define requirements
→ /sc:design "system architecture" # Create technical design
→ /sc:workflow "implementation plan" # Generate development roadmap
→ /sc:save "project-plan" # Save session context
/sc:brainstorm "project concept" # Define requirements
/sc:design "system architecture" # Create technical design
/sc:workflow "implementation plan" # Generate development roadmap
```
### Feature Development
```bash
/sc:load "project-context" # Load existing project
→ /sc:implement "feature name" # Build the feature
→ /sc:test --coverage # Validate with tests
→ /sc:document --type api # Generate documentation
/sc:implement "feature name" # Build the feature
/sc:test --coverage # Validate with tests
/sc:document --type api # Generate documentation
```
### Code Quality Improvement
```bash
/sc:analyze --focus quality # Assess current state
→ /sc:cleanup --comprehensive # Clean technical debt
→ /sc:improve --preview # Preview improvements
→ /sc:test --coverage # Validate changes
/sc:analyze --focus quality # Assess current state
/sc:improve --preview # Preview improvements
/sc:test --coverage # Validate changes
```
### Bug Investigation
```bash
/sc:troubleshoot "issue description" # Diagnose the problem
→ /sc:analyze --focus problem-area # Deep analysis of affected code
→ /sc:improve --fix --safe-mode # Apply targeted fixes
→ /sc:test --related-tests # Verify resolution
/sc:troubleshoot "issue description" # Diagnose the problem
/sc:analyze --focus problem-area # Deep analysis
/sc:improve --fix --safe-mode # Apply targeted fixes
```
### Pre-Production Checklist
```bash
/sc:analyze --focus security # Security audit
→ /sc:test --type e2e --comprehensive # Full E2E validation
→ /sc:build --optimize --target production # Production build
→ /sc:document --type deployment # Deployment documentation
```
---
## Full Command Reference
### Development Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **workflow** | Implementation planning | Project roadmaps, sprint planning |
| **implement** | Feature development | Full-stack features, API development |
| **build** | Project compilation | CI/CD, production builds |
| **design** | System architecture | API specs, database schemas |
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **workflow** | Implementation planning | Architect + PM, Sequential | Project roadmaps, sprint planning |
| **implement** | Feature development | Context specialists, Context7 + Magic | Full-stack features, API development |
| **build** | Project compilation | DevOps specialist | CI/CD, production builds |
| **design** | System architecture | Architect + UX, diagrams | API specs, database schemas |
#### `/sc:build` - Project Compilation
**Purpose**: Build and package projects with error handling
**Syntax**: `/sc:build` `[--optimize] [--target production] [--fix-errors]`
**Examples**: Production builds, dependency management, build optimization
**Common Issues**: Missing deps → auto-install, memory issues → optimized parameters
#### `/sc:design` - System Architecture
**Purpose**: Create technical designs and specifications
**Syntax**: `/sc:design "system description"` `[--type api|database|system] [--format openapi|mermaid]`
**Examples**: API specifications, database schemas, component architecture
**Output Formats**: Markdown, Mermaid diagrams, OpenAPI specs, ERD
### Analysis Commands
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **analyze** | Code assessment | Analyzer + domain experts | Quality audits, security reviews |
| **troubleshoot** | Problem diagnosis | Analyzer + DevOps, Sequential | Bug investigation, performance issues |
| **explain** | Code explanation | Educational focus | Learning, code reviews |
#### `/sc:explain` - Code & Concept Explanation
**Purpose**: Educational explanations with progressive detail
**Syntax**: `/sc:explain "topic or file"` `[--level beginner|intermediate|expert]`
**Examples**: Code walkthroughs, concept clarification, pattern explanation
**Teaching Styles**: Code-walkthrough, concept, pattern, comparison, tutorial
### Analysis Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **analyze** | Code assessment | Quality audits, security reviews |
| **troubleshoot** | Problem diagnosis | Bug investigation, performance issues |
| **explain** | Code explanation | Learning, code reviews |
### Quality Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **improve** | Code enhancement | Performance optimization, refactoring |
| **cleanup** | Technical debt | Dead code removal, organization |
| **test** | Quality assurance | Test automation, coverage analysis |
| **document** | Documentation | API docs, user guides |
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **improve** | Code enhancement | Analyzer, Morphllm | Performance optimization, refactoring |
| **cleanup** | Technical debt | Analyzer, Morphllm | Dead code removal, organization |
| **test** | Quality assurance | QA specialist, Playwright | Test automation, coverage analysis |
| **document** | Documentation | Documentation specialist | API docs, user guides |
#### `/sc:cleanup` - Technical Debt Reduction
**Purpose**: Remove dead code and optimize project structure
**Syntax**: `/sc:cleanup` `[--type imports|dead-code|formatting] [--confirm-before-delete]`
**Examples**: Import optimization, file organization, dependency cleanup
**Operations**: Dead code removal, import sorting, style formatting, file organization
### Project Management Commands
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **estimate** | Project estimation | Project Manager | Timeline planning, resource allocation |
| **task** | Task management | PM, Serena | Complex workflows, task tracking |
| **spawn** | Meta-orchestration | PM + multiple specialists | Large-scale projects, parallel execution |
#### `/sc:estimate` - Project Estimation
**Purpose**: Development estimates with complexity analysis
**Syntax**: `/sc:estimate "project description"` `[--detailed] [--team-size N]`
**Features**: Time estimates, complexity analysis, resource allocation, risk assessment
**Stability**: 🌱 Growing - Improving estimation accuracy with each release
#### `/sc:task` - Project Management
**Purpose**: Complex task workflow management
**Syntax**: `/sc:task "task description"` `[--breakdown] [--priority high|medium|low]`
**Features**: Task breakdown, priority management, cross-session tracking, dependency mapping
**Stability**: 🌱 Growing - Enhanced delegation patterns being refined
#### `/sc:spawn` - Meta-System Orchestration
**Purpose**: Large-scale project orchestration with parallel execution
**Syntax**: `/sc:spawn "complex project"` `[--parallel] [--monitor]`
**Features**: Workflow orchestration, parallel execution, progress monitoring, resource management
**Stability**: 🌱 Growing - Advanced orchestration capabilities under development
### Project Management
| Command | Purpose | Best For |
|---------|---------|----------|
| **estimate** | Project estimation | Timeline planning, resource allocation |
| **task** | Task management | Complex workflows, task tracking |
| **spawn** | Meta-orchestration | Large-scale projects, parallel execution |
### Utility Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **git** | Version control | Commit management, branch strategies |
| **index** | Command discovery | Exploring capabilities, finding commands |
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **git** | Version control | DevOps specialist | Commit management, branch strategies |
| **index** | Command discovery | Context analysis | Exploring capabilities, finding commands |
#### `/sc:git` - Version Control
**Purpose**: Intelligent Git operations with smart commit messages
**Syntax**: `/sc:git [operation]` `[--smart-messages] [--conventional]`
**Features**: Smart commit messages, branch management, conflict resolution, workflow optimization
**Stability**: ✅ Reliable - Proven commit message generation and workflow patterns
#### `/sc:index` - Command Discovery
**Purpose**: Explore available commands and capabilities
**Syntax**: `/sc:index` `[--category development|quality] [--search "keyword"]`
**Features**: Command discovery, capability exploration, contextual recommendations, usage patterns
**Stability**: 🧪 Testing - Command categorization and search being refined
### Session Commands
| Command | Purpose | Auto-Activation | Best For |
|---------|---------|-----------------|----------|
| **load** | Context loading | Context analysis, Serena | Session initialization, project onboarding |
| **save** | Session persistence | Session management, Serena | Checkpointing, context preservation |
| **reflect** | Task validation | Context analysis, Serena | Progress assessment, completion validation |
| **select-tool** | Tool optimization | Meta-analysis, all MCP | Performance optimization, tool selection |
#### `/sc:load` - Session Context Loading
**Purpose**: Initialize project context and session state
**Syntax**: `/sc:load [path]` `[--focus architecture|codebase] [--session "name"]`
**Features**: Project structure analysis, context restoration, session initialization, intelligent onboarding
**Stability**: 🔧 Functional - Core loading works, advanced context analysis improving
#### `/sc:save` - Session Persistence
**Purpose**: Save session context and progress
**Syntax**: `/sc:save "session-name"` `[--checkpoint] [--description "details"]`
**Features**: Session checkpointing, context preservation, progress tracking, cross-session continuity
**Stability**: 🔧 Functional - Basic persistence reliable, advanced features being enhanced
#### `/sc:reflect` - Task Reflection & Validation
**Purpose**: Analyze completion status and validate progress
**Syntax**: `/sc:reflect` `[--type completion|progress] [--task "task-name"]`
**Features**: Progress analysis, completion validation, quality assessment, next steps recommendation
**Stability**: 🌱 Growing - Analysis patterns being refined for better insights
#### `/sc:select-tool` - Intelligent Tool Selection
**Purpose**: Optimize MCP tool selection based on complexity analysis
**Syntax**: `/sc:select-tool "operation description"` `[--analyze-complexity] [--recommend]`
**Features**: Complexity analysis, tool recommendation, MCP coordination, optimization strategies, resource planning
**Stability**: 🌱 Growing - Tool selection algorithms being optimized
### Session Commands
| Command | Purpose | Best For |
|---------|---------|----------|
| **load** | Context loading | Session initialization, project onboarding |
| **save** | Session persistence | Checkpointing, context preservation |
| **reflect** | Task validation | Progress assessment, completion validation |
| **select-tool** | Tool optimization | Performance optimization, tool selection |
---
## Command Index
### By Category
**By Function:**
- **Planning**: brainstorm, design, workflow, estimate
- **Development**: implement, build, git
- **Analysis**: analyze, troubleshoot, explain
- **Quality**: improve, cleanup, test, document
- **Management**: task, spawn, load, save, reflect
- **Utility**: index, select-tool
**🚀 Project Initiation**
- `brainstorm` - Interactive discovery
- `design` - System architecture
- `workflow` - Implementation planning
**⚡ Development**
- `implement` - Feature development
- `build` - Project compilation
- `git` - Version control
**🔍 Analysis & Quality**
- `analyze` - Code assessment
- `troubleshoot` - Problem diagnosis
- `explain` - Code explanation
- `improve` - Code enhancement
- `cleanup` - Technical debt
- `test` - Quality assurance
**📝 Documentation**
- `document` - Documentation generation
**📊 Project Management**
- `estimate` - Project estimation
- `task` - Task management
- `spawn` - Meta-orchestration
**🧠 Session & Intelligence**
- `load` - Context loading
- `save` - Session persistence
- `reflect` - Task validation
- `select-tool` - Tool optimization
**🔧 Utility**
- `index` - Command discovery
### By Maturity Level
**🔥 Production Ready** (Consistent, reliable results)
- `brainstorm`, `analyze`, `implement`, `troubleshoot`
**✅ Reliable** (Well-tested, stable features)
- `workflow`, `design`, `test`, `document`, `git`
**🔧 Functional** (Core features work, enhancements ongoing)
- `improve`, `cleanup`, `build`, `load`, `save`
**🌱 Growing** (Rapid improvement, usable but evolving)
- `spawn`, `task`, `estimate`, `reflect`, `select-tool`
**🧪 Testing** (Experimental features, feedback welcome)
- `index`, `explain`
---
## 🚨 Quick Troubleshooting
### Common Issues (< 2 minutes)
- **Command not found**: Check `/sc:` prefix and SuperClaude installation
- **Invalid flag**: Verify flag against `python3 -m SuperClaude --help`
- **MCP server error**: Check Node.js installation and server configuration
- **Permission denied**: Run `chmod +x` or check file permissions
### Immediate Fixes
- **Reset session**: `/sc:load` to reinitialize
- **Clear cache**: Remove `~/.claude/cache/` directory
- **Restart Claude Code**: Exit and restart application
- **Check status**: `python3 -m SuperClaude --version`
**By Complexity:**
- **Beginner**: brainstorm, implement, analyze, test
- **Intermediate**: workflow, design, improve, document
- **Advanced**: spawn, task, select-tool, reflect
## Troubleshooting
### Command-Specific Issues
**Command Issues:**
- **Command not found**: Verify installation: `python3 -m SuperClaude --version`
- **No response**: Restart Claude Code session
- **Slow performance**: Use `--no-mcp` to test without MCP servers
**Command Not Recognized:**
```bash
# Problem: "/sc:analyze not found"
# Quick Fix: Check command spelling and prefix
/sc:help commands # List all available commands
python3 -m SuperClaude --help # Verify installation
```
**Quick Fixes:**
- Reset session: `/sc:load` to reinitialize
- Check status: `SuperClaude install --list-components`
- Get help: [Troubleshooting Guide](../Reference/troubleshooting.md)
**Command Hangs or No Response:**
```bash
# Problem: Command starts but never completes
# Quick Fix: Check for dependency issues
/sc:command --timeout 30 # Set explicit timeout
/sc:command --no-mcp # Try without MCP servers
ps aux | grep SuperClaude # Check for hung processes
```
**Invalid Flag Combinations:**
```bash
# Problem: "Flag conflict detected"
# Quick Fix: Check flag compatibility
/sc:help flags # List valid flags
/sc:command --help # Command-specific flags
# Use simpler flag combinations or single flags
```
### MCP Server Issues
**Server Connection Failures:**
```bash
# Problem: MCP servers not responding
# Quick Fix: Verify server status and restart
ls ~/.claude/.claude.json # Check MCP config exists
/sc:command --no-mcp # Bypass MCP temporarily
node --version # Verify Node.js v16+
npm cache clean --force # Clear NPM cache
```
**Magic/Morphllm API Key Issues:**
```bash
# Problem: "API key required" errors
# Expected: These servers need paid API keys
export TWENTYFIRST_API_KEY="your_key" # For Magic
export MORPH_API_KEY="your_key" # For Morphllm
# Or use: /sc:command --no-mcp to skip paid services
```
### Performance Issues
**Slow Command Execution:**
```bash
# Problem: Commands taking >30 seconds
# Quick Fix: Reduce scope and complexity
/sc:command --scope file # Limit to single file
/sc:command --concurrency 1 # Reduce parallel ops
/sc:command --uc # Use compressed output
/sc:command --no-mcp # Native execution only
```
**Memory/Resource Exhaustion:**
```bash
# Problem: System running out of memory
# Quick Fix: Resource management
/sc:command --memory-limit 1024 # Limit to 1GB
/sc:command --scope module # Reduce analysis scope
/sc:command --safe-mode # Conservative execution
killall node # Reset MCP servers
```
### Progressive Support Levels
**Level 1: Quick Fix (< 2 min)**
- Use the Common Issues section above
- Try immediate fixes like restart or flag changes
- Check basic installation and dependencies
**Level 2: Detailed Help (5-15 min)**
```bash
# Comprehensive diagnostics
SuperClaude install --diagnose
/sc:help troubleshoot
cat ~/.claude/logs/superclaude.log | tail -50
```
- See [Common Issues Guide](../Reference/common-issues.md) for detailed troubleshooting
**Level 3: Expert Support (30+ min)**
```bash
# Deep system analysis
SuperClaude install --diagnose
strace -e trace=file /sc:command 2>&1 | grep ENOENT
lsof | grep SuperClaude
# Check GitHub Issues for known problems
```
- See [Diagnostic Reference Guide](../Reference/diagnostic-reference.md) for advanced procedures
**Level 4: Community Support**
- Report issues at [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
- Include diagnostic output from Level 3
- Describe steps to reproduce the problem
### Success Validation
After applying fixes, test with:
- [ ] `python3 -m SuperClaude --version` (should show version)
- [ ] `/sc:analyze README.md` (should complete without errors)
- [ ] Check MCP servers installed: `SuperClaude install --list-components | grep mcp`
- [ ] Verify flags work: `/sc:help flags`
- [ ] Test basic workflow: `/sc:brainstorm "test"` → should ask questions
## Quick Troubleshooting (Legacy)
- **Command not found** → Check installation: `SuperClaude --version`
- **Flag error** → Verify against [FLAGS.md](flags.md)
- **MCP issue** → Check MCP server installation: `SuperClaude install --components mcp --dry-run`
- **No output** → Restart Claude Code session
- **Slow performance** → Use `--scope file` or `--no-mcp`
### Common Issues
**Command Not Recognized**
```bash
# Check SuperClaude installation
SuperClaude --version
# Verify component installation
SuperClaude install --list-components
# Restart Claude Code session
```
**Slow Performance**
```bash
# Limit analysis scope
/sc:analyze src/ --scope file
# Use specific MCP servers only
/sc:implement "feature" --c7 --seq # Instead of --all-mcp
# Reduce concurrency
/sc:improve . --concurrency 2
```
**MCP Server Connection Issues**
```bash
# Check server status
ls ~/.claude/.claude.json
# Reinstall MCP components
SuperClaude install --components mcp --force
# Use native execution fallback
/sc:analyze . --no-mcp
```
**Scope Management Issues**
```bash
# Control analysis depth
/sc:analyze . --scope project # Instead of system-wide
# Focus on specific areas
/sc:analyze --focus security # Instead of comprehensive
# Preview before execution
/sc:improve . --dry-run --preview
```
### Error Recovery Patterns
**Build Failures**
```bash
/sc:troubleshoot --type build --verbose
→ /sc:build --fix-errors --deps-install
→ /sc:test --smoke # Quick validation
```
**Test Failures**
```bash
/sc:analyze --focus testing # Identify test issues
→ /sc:test --fix --preview # Preview test fixes
→ /sc:test --coverage # Verify repairs
```
**Memory/Resource Issues**
```bash
/sc:select-tool "task" --analyze-complexity # Check resource needs
→ /sc:task "subtask" --scope module # Break into smaller pieces
→ /sc:spawn "large-task" --parallel --concurrency 2 # Controlled parallelism
```
---
## Getting Help
**In-Session Help**
- `/sc:index --help` - Command discovery and help
- `/sc:explain "command-name"` - Detailed command explanation
- `/sc:brainstorm --strategy systematic` - Systematic problem exploration
**Documentation**
- [Quick Start Guide](../Getting-Started/quick-start.md) - Essential setup and first steps
- [Best Practices](../Reference/quick-start-practices.md) - Optimization and workflow patterns
- [Examples Cookbook](../Reference/examples-cookbook.md) - Real-world usage patterns
**Community Support**
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues) - Bug reports and feature requests
- [Discussions](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions) - Community help and patterns
---
## 🎯 Comprehensive Testing Procedures
### Essential Commands Verification
Run these tests to ensure all essential commands work correctly:
```bash
# Test 1: Discovery and Planning
/sc:brainstorm "test mobile app"
# Expected: 3-5 discovery questions about users, features, platform
# Test 2: Implementation
/sc:implement "simple hello function"
# Expected: Working code that compiles/runs without errors
# Test 3: Analysis
/sc:analyze . --focus quality
# Expected: Quality assessment with specific recommendations
# Test 4: Troubleshooting
/sc:troubleshoot "simulated performance issue"
# Expected: Systematic investigation approach with hypotheses
# Test 5: Testing
/sc:test --coverage
# Expected: Test execution or test planning with coverage analysis
# Test 6: Code Enhancement
/sc:improve README.md --preview
# Expected: Improvement suggestions with preview of changes
# Test 7: Documentation
/sc:document . --type api
# Expected: API documentation or documentation planning
# Test 8: Workflow Planning
/sc:workflow "user authentication feature"
# Expected: Structured implementation plan with phases
```
### Success Benchmarks
- **Response Time**: Commands should respond within 10 seconds
- **Accuracy**: Domain specialists should activate for relevant requests
- **Completeness**: Outputs should include actionable next steps
- **Consistency**: Similar requests should produce consistent approaches
### Performance Validation
```bash
# Test resource usage
time /sc:analyze large-project/
# Expected: Completion within reasonable time based on project size
# Test MCP coordination
/sc:implement "React component" --verbose
# Expected: Magic + Context7 activation visible in output
# Test flag override
/sc:analyze . --no-mcp
# Expected: Native execution only, faster response
```
---
**Remember**: SuperClaude learns from your usage patterns. Start with the [Essential Commands](#essential-commands), explore [Common Workflows](#common-workflows), and gradually discover advanced capabilities. Use `/sc:index` whenever you need guidance.
## Next Steps
- [Flags Guide](flags.md) - Control command behavior
- [Agents Guide](agents.md) - Specialist activation
- [Examples Cookbook](../Reference/examples-cookbook.md) - Real usage patterns

1014
Docs/User-Guide/flags.md
View File

File diff suppressed because it is too large Load Diff

1252
Docs/User-Guide/mcp-servers.md
View File

File diff suppressed because it is too large Load Diff

53
Docs/User-Guide/modes.md
View File

@@ -1,30 +1,7 @@
# SuperClaude Behavioral Modes Guide 🧠
## ✅ Verification Status
- **SuperClaude Version**: v4.0+ Compatible
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Mode Activation**: ✅ All Verified
## 🧪 Testing Mode Activation
Before using this guide, verify modes activate correctly:
```bash
# Test Brainstorming mode
/sc:brainstorm "vague project idea"
# Expected: Should ask discovery questions, not give immediate solutions
# Test Task Management mode
/sc:implement "complex multi-file feature"
# Expected: Should break down into phases and coordinate steps
# Test Token Efficiency mode
/sc:analyze large-project/ --uc
# Expected: Should use symbols and compressed output format
```
**If tests fail**: Modes activate automatically based on request complexity - check behavior patterns below
## ✅ Quick Verification
Test modes by using `/sc:` commands - they activate automatically based on task complexity. For full command reference, see [Commands Guide](commands.md).
## Quick Reference Table
@@ -33,15 +10,15 @@ Before using this guide, verify modes activate correctly:
| **🧠 Brainstorming** | Interactive discovery | "brainstorm", "maybe", vague requests | Socratic questions, requirement elicitation | New project planning, unclear requirements |
| **🔍 Introspection** | Meta-cognitive analysis | Error recovery, "analyze reasoning" | Transparent thinking markers (🤔, 🎯, 💡) | Debugging, learning, optimization |
| **📋 Task Management** | Complex coordination | >3 steps, >2 directories | Phase breakdown, memory persistence | Multi-step operations, project management |
| **🎯 Orchestration** | Intelligent tool selection | Multi-tool ops, >75% resources | Optimal tool routing, parallel execution | Complex analysis, performance optimization |
| **⚡ Token Efficiency** | Compressed communication | >75% context usage, `--uc` flag | Symbol systems, 30-50% token reduction | Resource constraints, large operations |
| **🎯 Orchestration** | Intelligent tool selection | Multi-tool ops, high resource usage | Optimal tool routing, parallel execution | Complex analysis, performance optimization |
| **⚡ Token Efficiency** | Compressed communication | High context usage, `--uc` flag | Symbol systems, estimated 30-50% token reduction | Resource constraints, large operations |
| **🎨 Standard** | Balanced default | Simple tasks, no complexity triggers | Clear professional communication | General development, straightforward tasks |
---
## Getting Started (2-Minute Overview)
**Modes activate automatically** - you don't need to think about them. They adapt Claude Code's behavior based on your task complexity and context.
**Modes activate through behavioral instructions** - Claude Code reads context files to determine which mode behaviors to adopt based on your task patterns and complexity.
**Quick Examples:**
```bash
@@ -187,7 +164,7 @@ Task Management Approach:
**Auto-Activation Triggers:**
- Multi-tool operations requiring sophisticated coordination
- Performance constraints (>75% resource usage)
- Performance constraints (high resource usage)
- Parallel execution opportunities (>3 independent files/operations)
- Complex routing decisions with multiple valid tool approaches
@@ -219,10 +196,10 @@ Orchestration Approach:
### ⚡ Token Efficiency Mode - Compressed Communication
**Purpose**: Achieve 30-50% token reduction through symbol systems while preserving information quality.
**Purpose**: Achieve estimated 30-50% token reduction through symbol systems while preserving information quality.
**Auto-Activation Triggers:**
- Context usage >75% approaching limits
- High context usage approaching limits
- Large-scale operations requiring resource efficiency
- User explicit flags: `--uc`, `--ultracompressed`
- Complex analysis workflows with multiple outputs
@@ -331,7 +308,7 @@ Standard Approach: Consistent, professional baseline for all tasks
**When Modes Activate:**
1. **Complexity Threshold**: >3 files → Task Management
2. **Resource Pressure**: >75% usage → Token Efficiency
2. **Resource Pressure**: High context usage → Token Efficiency
3. **Multi-Tool Need**: Complex analysis → Orchestration
4. **Uncertainty**: Vague requirements → Brainstorming
5. **Error Recovery**: Problems → Introspection
@@ -405,7 +382,7 @@ Standard Approach: Consistent, professional baseline for all tasks
| **Complex Scope** | >3 files or >2 directories | 📋 Task Management | Phase coordination |
| **Multi-Tool Need** | Analysis + Implementation | 🎯 Orchestration | Tool optimization |
| **Error Recovery** | "This isn't working as expected" | 🔍 Introspection | Transparent reasoning |
| **Resource Pressure** | >75% context usage | ⚡ Token Efficiency | Symbol compression |
| **Resource Pressure** | High context usage | ⚡ Token Efficiency | Symbol compression |
| **Simple Task** | "Fix this function" | 🎨 Standard | Clear, direct approach |
### Manual Override Commands
@@ -425,7 +402,11 @@ Standard Approach: Consistent, professional baseline for all tasks
---
## 🚨 Quick Troubleshooting
## Troubleshooting
For troubleshooting help, see:
- [Common Issues](../Reference/common-issues.md) - Quick fixes for frequent problems
- [Troubleshooting Guide](../Reference/troubleshooting.md) - Comprehensive problem resolution
### Common Issues (< 2 minutes)
- **Mode not activating**: Use manual flags: `--brainstorm`, `--introspect`, `--uc`
@@ -610,7 +591,7 @@ SuperClaude's 6 behavioral modes create an **intelligent adaptation system** tha
**🌲 Advanced (Month 2+)**
- [MCP Servers](mcp-servers.md) - Mode integration with enhanced capabilities
- [Session Management](session-management.md) - Task Management mode workflows
- [Best Practices](../Reference/quick-start-practices.md) - Mode optimization strategies
- [Getting Started](../Getting-Started/quick-start.md) - Mode optimization strategies
**🔧 Expert**
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Mode implementation details
@@ -620,4 +601,4 @@ SuperClaude's 6 behavioral modes create an **intelligent adaptation system** tha
- **Brainstorming**: [Requirements Discovery Patterns](../Reference/examples-cookbook.md#requirements)
- **Task Management**: [Session Management Guide](session-management.md)
- **Orchestration**: [MCP Servers Guide](mcp-servers.md)
- **Token Efficiency**: [Performance Optimization](../Reference/quick-start-practices.md#efficiency)
- **Token Efficiency**: [Command Fundamentals](commands.md#token-efficiency)

1457
Docs/User-Guide/session-management.md
View File

File diff suppressed because it is too large Load Diff

360
Docs/User-Guide/socratic-learning.md
View File

@@ -1,360 +0,0 @@
# Socratic Learning Guide - SuperClaude Educational AI
> **Revolutionary Approach**: Learn programming principles through guided discovery rather than passive consumption
## ✅ Verification Status
- **SuperClaude Version**: v4.1+ Compatible (Socratic Learning Module)
- **Last Tested**: 2025-01-16
- **Test Environment**: All platforms
- **Learning Effectiveness**: ✅ 80% retention vs 20% traditional methods
## 🎯 What is Socratic Learning?
**Traditional AI Approach**:
```
User: "How do I write clean code?"
AI: "Here are 5 Clean Code principles: 1. Meaningful Names, 2. Small Functions..."
Result: User memorizes but doesn't deeply understand
```
**SuperClaude Socratic Approach**:
```
User: "How do I write clean code?"
AI: "What do you notice about this function when you first read it?"
User: "It's hard to understand what it does..."
AI: "What makes it hard to understand? Let's examine it together..."
Result: User discovers principles through guided exploration
```
## 🧠 Why Socratic Learning Works
### Learning Science Benefits
```yaml
retention_rates:
passive_consumption: "20% - traditional AI answers"
active_discovery: "80% - Socratic guided learning"
understanding_depth:
traditional: "Surface level - memorized facts"
socratic: "Deep comprehension - internalized wisdom"
application_ability:
traditional: "Low - requires constant lookup"
socratic: "High - principles become intuitive"
dependency_level:
traditional: "High - AI becomes answer machine"
socratic: "Low - AI becomes thinking partner"
```
### Educational Psychology
- **Active Construction**: Users build knowledge instead of receiving it
- **Metacognition**: Develops thinking about thinking skills
- **Transfer Learning**: Principles learned through discovery apply broadly
- **Intrinsic Motivation**: Discovery creates "aha moments" that stick
## 📚 Available Learning Domains
### Clean Code Mastery
**Command**: `/sc:socratic-clean-code`
#### Principle Discovery Areas
```yaml
meaningful_names:
discovery_focus: "Intention-revealing, self-documenting names"
typical_questions:
- "What does this variable name tell you about its purpose?"
- "How could you eliminate the need for this comment?"
learning_outcome: "Names that reveal intent without explanation"
functions:
discovery_focus: "Small functions with single responsibility"
typical_questions:
- "How many different things is this function doing?"
- "What would happen if each responsibility was its own function?"
learning_outcome: "Functions that do one thing well"
comments:
discovery_focus: "Self-documenting code vs compensatory comments"
typical_questions:
- "Why was this comment needed?"
- "What would make the code clear without explanation?"
learning_outcome: "Code that tells its own story"
error_handling:
discovery_focus: "Meaningful exceptions vs return codes"
typical_questions:
- "How would the caller know what went wrong?"
- "What information would help debug this failure?"
learning_outcome: "Robust error handling with context"
```
### Design Patterns Mastery
**Command**: `/sc:socratic-patterns`
#### Pattern Recognition Categories
```yaml
behavioral_patterns:
focus: "How objects interact and communicate"
key_patterns: ["Observer", "Strategy", "Command", "State"]
discovery_approach: "Analyze communication and responsibility"
structural_patterns:
focus: "How objects are composed and organized"
key_patterns: ["Decorator", "Adapter", "Facade", "Composite"]
discovery_approach: "Examine relationships and interfaces"
creational_patterns:
focus: "How objects are created and instantiated"
key_patterns: ["Factory Method", "Abstract Factory", "Builder", "Singleton"]
discovery_approach: "Understand creation decisions and flexibility"
```
## 🚀 Getting Started with Socratic Learning
### Quick Start: Clean Code Discovery
```bash
# Basic function analysis
/sc:socratic-clean-code "function getUserData(id, type, options) {
// validate input
if (!id) throw new Error('Invalid ID');
// fetch user
const user = database.findById(id);
// format response
return { name: user.name, email: user.email };
}"
# Expected interaction:
# AI: "What do you notice about this function when you read it?"
# You: "It does several different things..."
# AI: "Exactly! How many different responsibilities can you identify?"
# You: "Validation, fetching, and formatting"
# AI: "What would happen if each responsibility was its own function?"
# Discovery: Single Responsibility Principle
```
### Quick Start: Pattern Recognition
```bash
# Observer pattern discovery
/sc:socratic-patterns "class NewsAgency {
notifyAll() {
this.observers.forEach(obs => obs.update(this.news));
}
}" --category behavioral
# Expected interaction:
# AI: "What happens when the news changes?"
# You: "All the observers get notified..."
# AI: "How do the observers find out about the change?"
# You: "The NewsAgency calls update on each one"
# AI: "What kind of relationship does this create?"
# Discovery: One-to-many dependency (Observer Pattern)
```
## 🎓 Learning Session Types
### Interactive Discovery Sessions
```bash
# Guided learning with adaptive questioning
/sc:socratic-clean-code --interactive --level intermediate
/sc:socratic-patterns --interactive --level beginner
# Sessions adapt to your responses and experience level
# Progress tracking across multiple discovery sessions
# Personalized questioning based on your understanding gaps
```
### Code-Specific Analysis
```bash
# Analyze your actual code for learning opportunities
/sc:socratic-clean-code src/utils/validation.js --focus functions
/sc:socratic-patterns src/services/payment.js --category structural
# Real-world application to your codebase
# Contextual learning with immediate practical value
# Discovery opportunities in code you're already working on
```
### Principle-Focused Exploration
```bash
# Deep dive into specific areas
/sc:socratic-clean-code --principle naming [your-code]
/sc:socratic-patterns --pattern strategy [algorithm-code]
# Concentrated discovery in areas where you need growth
# Targeted learning for specific principle understanding
# Progressive mastery of individual concepts
```
## 📊 Learning Progression Tracking
### Discovery Milestones
```yaml
clean_code_mastery:
level_1_recognition:
- "Identifies unclear naming in code"
- "Recognizes functions doing multiple things"
- "Sees when comments compensate for poor code"
level_2_application:
- "Suggests meaningful name improvements"
- "Proposes function responsibility separation"
- "Designs self-documenting code approaches"
level_3_internalization:
- "Proactively applies principles to new code"
- "Recognizes principle violations immediately"
- "Teaches principles to others through examples"
pattern_mastery:
level_1_recognition:
- "Identifies pattern intent in code structures"
- "Recognizes common object relationship patterns"
- "Sees recurring design solutions"
level_2_application:
- "Suggests appropriate patterns for problems"
- "Designs pattern implementations"
- "Evaluates pattern trade-offs"
level_3_internalization:
- "Intuitively selects patterns for architecture"
- "Combines patterns effectively"
- "Creates pattern variations for specific contexts"
```
### Progress Indicators
```yaml
understanding_signals:
discovery_moments:
- "User independently identifies principles"
- "User makes connections between concepts"
- "User generates their own examples"
application_success:
- "User applies learning to different code"
- "User explains principles to others"
- "User creates principle-based improvements"
transfer_learning:
- "User recognizes principles in new contexts"
- "User adapts principles to different languages"
- "User synthesizes multiple principles"
```
## 🛠 Advanced Learning Techniques
### Cross-Domain Synthesis
```bash
# Connect Clean Code principles to Design Patterns
/sc:socratic-clean-code [strategy-pattern-code] --focus principles
# Discover how patterns exemplify Clean Code principles
# Learn architectural thinking through principle application
# Pattern-Clean Code integration
/sc:socratic-patterns [clean-function-code] --focus structure
# Understand how good code naturally leads to pattern recognition
# Synthesize code quality and architectural thinking
```
### Real-World Application
```bash
# Apply learning to your actual projects
/sc:socratic-clean-code src/ --interactive --level advanced
# Discovery-based code review of your real codebase
# Practical principle application with immediate value
# Architecture learning through pattern analysis
/sc:socratic-patterns src/components/ --category structural
# Understand existing architecture through pattern lens
# Improve system design through pattern discovery
```
### Collaborative Learning
```bash
# Team learning sessions
/sc:socratic-clean-code [team-code] --interactive
# Shared discovery experiences
# Consistent principle understanding across team
# Knowledge transfer through guided exploration
```
## 🎯 Learning Outcomes and Benefits
### Immediate Benefits (First Session)
- **Discovery Experience**: "Aha moments" that create lasting memory
- **Practical Application**: Apply principles to real code immediately
- **Confidence Building**: Understanding through personal discovery
- **Engagement**: Active learning maintains attention and interest
### Short-term Benefits (1-4 weeks)
- **Principle Internalization**: Principles become intuitive, not memorized
- **Code Quality Improvement**: Natural application to daily coding
- **Pattern Recognition**: Automatic identification of design opportunities
- **Teaching Ability**: Can explain principles through examples
### Long-term Benefits (1-6 months)
- **Architectural Thinking**: System-level design improvement
- **Independent Learning**: Ability to discover new principles independently
- **Code Review Skills**: Enhanced ability to guide others
- **Design Intuition**: Natural selection of appropriate patterns and principles
## 🔧 Troubleshooting Learning Issues
### Common Learning Challenges
```yaml
too_much_guidance:
symptoms: "AI provides answers too quickly"
solution: "Use --level advanced or request more challenging questions"
too_little_guidance:
symptoms: "Stuck without clear direction"
solution: "Use --level beginner or ask for hints"
principle_confusion:
symptoms: "Multiple principles seem to apply"
solution: "Focus on one principle at a time with --focus flag"
application_difficulty:
symptoms: "Understand principle but can't apply it"
solution: "Practice with simpler examples before complex code"
```
### Maximizing Learning Effectiveness
```yaml
best_practices:
preparation:
- "Have specific code examples ready for analysis"
- "Set aside focused time without distractions"
- "Prepare to think actively, not passively consume"
during_session:
- "Take time to really examine code before answering"
- "Ask for clarification if questions are unclear"
- "Connect discoveries to your existing knowledge"
after_session:
- "Apply discovered principles to other code immediately"
- "Teach what you learned to someone else"
- "Look for the principles in codebases you read"
```
## 📈 Success Metrics
### Personal Progress Tracking
- **Discovery Count**: How many principles you've discovered independently
- **Application Success**: Principles successfully applied to new code
- **Teaching Moments**: Instances where you've explained principles to others
- **Recognition Speed**: How quickly you identify principle opportunities
### Code Quality Improvement
- **Clarity Increase**: Code becomes more self-explanatory
- **Maintainability**: Easier modification and extension
- **Bug Reduction**: Fewer issues from unclear or complex code
- **Team Understanding**: Others comprehend your code more easily
---
**Remember**: Socratic learning transforms you from a passive consumer of programming knowledge into an active discoverer of programming wisdom. Each discovery session builds genuine understanding that becomes part of your intuitive programming knowledge.
**Start your discovery journey**: Try `/sc:socratic-clean-code --interactive` and experience the difference between being told principles and discovering them yourself.