mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
Initial commit: SuperClaude v3 Beta clean architecture
Complete foundational restructure with: - Simplified project architecture - Comprehensive documentation system - Modern installation framework - Clean configuration management - Updated profiles and settings 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
657
Docs/commands-guide.md
Normal file
657
Docs/commands-guide.md
Normal file
@@ -0,0 +1,657 @@
|
||||
# SuperClaude Commands Guide 🛠️
|
||||
|
||||
A practical guide to all 15 SuperClaude slash commands. We'll be honest about what works well and what's still rough around the edges.
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
| Command | Purpose | Best For |
|
||||
|---------|---------|----------|
|
||||
| `/analyze` | Code analysis | Finding issues, understanding codebases |
|
||||
| `/build` | Project building | Compilation, bundling, deployment prep |
|
||||
| `/cleanup` | Technical debt | Removing dead code, organizing files |
|
||||
| `/design` | System design | Architecture planning, API design |
|
||||
| `/document` | Documentation | README files, code comments, guides |
|
||||
| `/estimate` | Project estimation | Time/effort planning, complexity analysis |
|
||||
| `/explain` | Educational help | Learning concepts, understanding code |
|
||||
| `/git` | Git operations | Smart commits, branch management |
|
||||
| `/improve` | Code enhancement | Refactoring, optimization, quality fixes |
|
||||
| `/index` | Command help | Finding the right command for your task |
|
||||
| `/load` | Context loading | Project analysis, codebase understanding |
|
||||
| `/spawn` | Complex orchestration | Multi-step operations, workflow automation |
|
||||
| `/task` | Project management | Long-term feature planning, task tracking |
|
||||
| `/test` | Testing | Running tests, coverage analysis |
|
||||
| `/troubleshoot` | Problem solving | Debugging, issue investigation |
|
||||
|
||||
## Development Commands 🔨
|
||||
|
||||
### `/build` - Project Building
|
||||
**What it does**: Builds, compiles, and packages projects with smart error handling.
|
||||
|
||||
**When to use it**:
|
||||
- You need to compile/bundle your project
|
||||
- Build process is failing and you want help debugging
|
||||
- Setting up build optimization
|
||||
- Preparing for deployment
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/build # Build current project
|
||||
/build --type prod # Production build
|
||||
/build --clean # Clean build (remove old artifacts)
|
||||
/build --optimize # Enable optimizations
|
||||
/build src/ # Build specific directory
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type dev|prod|test` - Build type
|
||||
- `--clean` - Clean before building
|
||||
- `--optimize` - Enable build optimizations
|
||||
- `--verbose` - Show detailed build output
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/build --type prod --optimize # Production build with optimizations
|
||||
/build --clean --verbose # Clean build with detailed output
|
||||
/build src/components # Build just the components folder
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Works best with common build tools (npm, webpack, etc.)
|
||||
- May struggle with very custom build setups
|
||||
- Check your build tool is in PATH
|
||||
|
||||
---
|
||||
|
||||
### `/design` - System & Component Design
|
||||
**What it does**: Creates system architecture, API designs, and component specifications.
|
||||
|
||||
**When to use it**:
|
||||
- Planning new features or systems
|
||||
- Need API or database design
|
||||
- Creating component architecture
|
||||
- Documenting system relationships
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/design user-auth-system # Design a user authentication system
|
||||
/design --type api auth # Design just the API part
|
||||
/design --format spec payment # Create formal specification
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type architecture|api|component|database` - Design focus
|
||||
- `--format diagram|spec|code` - Output format
|
||||
- `--iterative` - Refine design through iterations
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/design --type api user-management # Design user management API
|
||||
/design --format spec chat-system # Create chat system specification
|
||||
/design --type database ecommerce # Design database schema
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- More conceptual than code-generating
|
||||
- Output quality depends on how clearly you describe requirements
|
||||
- Great for planning phase, less for implementation details
|
||||
|
||||
## Analysis Commands 🔍
|
||||
|
||||
### `/analyze` - Code Analysis
|
||||
**What it does**: Comprehensive analysis of code quality, security, performance, and architecture.
|
||||
|
||||
**When to use it**:
|
||||
- Understanding unfamiliar codebases
|
||||
- Finding security vulnerabilities
|
||||
- Performance bottleneck hunting
|
||||
- Code quality assessment
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/analyze src/ # Analyze entire src directory
|
||||
/analyze --focus security # Focus on security issues
|
||||
/analyze --depth deep app.js # Deep analysis of specific file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--focus quality|security|performance|architecture` - Analysis focus
|
||||
- `--depth quick|deep` - Analysis thoroughness
|
||||
- `--format text|json|report` - Output format
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/analyze --focus security --depth deep # Deep security analysis
|
||||
/analyze --focus performance src/api/ # Performance analysis of API
|
||||
/analyze --format report . # Generate analysis report
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can take a while on large codebases
|
||||
- Security analysis is pretty good, performance analysis varies
|
||||
- Works best with common languages (JS, Python, etc.)
|
||||
|
||||
---
|
||||
|
||||
### `/troubleshoot` - Problem Investigation
|
||||
**What it does**: Systematic debugging and problem investigation.
|
||||
|
||||
**When to use it**:
|
||||
- Something's broken and you're not sure why
|
||||
- Need systematic debugging approach
|
||||
- Error messages are confusing
|
||||
- Performance issues investigation
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/troubleshoot "login not working" # Investigate login issue
|
||||
/troubleshoot --logs error.log # Analyze error logs
|
||||
/troubleshoot performance # Performance troubleshooting
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--logs <file>` - Include log file analysis
|
||||
- `--systematic` - Use structured debugging approach
|
||||
- `--focus network|database|frontend` - Focus area
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/troubleshoot "API returning 500" --logs server.log
|
||||
/troubleshoot --focus database "slow queries"
|
||||
/troubleshoot "build failing" --systematic
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Works better with specific error descriptions
|
||||
- Include relevant error messages and logs when possible
|
||||
- May suggest obvious things first (that's usually good!)
|
||||
|
||||
---
|
||||
|
||||
### `/explain` - Educational Explanations
|
||||
**What it does**: Explains code, concepts, and technologies in an educational way.
|
||||
|
||||
**When to use it**:
|
||||
- Learning new technologies or patterns
|
||||
- Understanding complex code
|
||||
- Need clear explanations for team members
|
||||
- Documenting tricky concepts
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/explain async/await # Explain async/await concept
|
||||
/explain --code src/utils.js # Explain specific code file
|
||||
/explain --beginner React hooks # Beginner-friendly explanation
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--beginner` - Simpler explanations
|
||||
- `--advanced` - Technical depth
|
||||
- `--code <file>` - Explain specific code
|
||||
- `--examples` - Include practical examples
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/explain --beginner "what is REST API"
|
||||
/explain --code src/auth.js --advanced
|
||||
/explain --examples "React context patterns"
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Great for well-known concepts, may struggle with very niche topics
|
||||
- Better with specific questions than vague "explain this codebase"
|
||||
- Include context about your experience level
|
||||
|
||||
## Quality Commands ✨
|
||||
|
||||
### `/improve` - Code Enhancement
|
||||
**What it does**: Systematic improvements to code quality, performance, and maintainability.
|
||||
|
||||
**When to use it**:
|
||||
- Refactoring messy code
|
||||
- Performance optimization
|
||||
- Applying best practices
|
||||
- Modernizing old code
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/improve src/legacy/ # Improve legacy code
|
||||
/improve --type performance # Focus on performance
|
||||
/improve --safe src/utils.js # Safe, low-risk improvements only
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type quality|performance|maintainability|style` - Improvement focus
|
||||
- `--safe` - Only apply low-risk changes
|
||||
- `--preview` - Show what would be changed without doing it
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/improve --type performance --safe src/api/
|
||||
/improve --preview src/components/LegacyComponent.js
|
||||
/improve --type style . --safe
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Always use `--preview` first to see what it wants to change
|
||||
- `--safe` is your friend - prevents risky refactoring
|
||||
- Works best on smaller files/modules rather than entire codebases
|
||||
|
||||
---
|
||||
|
||||
### `/cleanup` - Technical Debt Reduction
|
||||
**What it does**: Removes dead code, unused imports, and organizes file structure.
|
||||
|
||||
**When to use it**:
|
||||
- Codebase feels cluttered
|
||||
- Lots of unused imports/variables
|
||||
- File organization is messy
|
||||
- Before major refactoring
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/cleanup src/ # Clean up src directory
|
||||
/cleanup --dead-code # Focus on dead code removal
|
||||
/cleanup --imports package.js # Clean up imports in specific file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--dead-code` - Remove unused code
|
||||
- `--imports` - Clean up import statements
|
||||
- `--files` - Reorganize file structure
|
||||
- `--safe` - Conservative cleanup only
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/cleanup --dead-code --safe src/utils/
|
||||
/cleanup --imports src/components/
|
||||
/cleanup --files . --safe
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can be aggressive - always review changes carefully
|
||||
- May not catch all dead code (especially dynamic imports)
|
||||
- Better to run on smaller sections than entire projects
|
||||
|
||||
---
|
||||
|
||||
### `/test` - Testing & Quality Assurance
|
||||
**What it does**: Runs tests, generates coverage reports, and maintains test quality.
|
||||
|
||||
**When to use it**:
|
||||
- Running test suites
|
||||
- Checking test coverage
|
||||
- Generating test reports
|
||||
- Setting up continuous testing
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/test # Run all tests
|
||||
/test --type unit # Run only unit tests
|
||||
/test --coverage # Generate coverage report
|
||||
/test --watch src/ # Watch mode for development
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type unit|integration|e2e|all` - Test type
|
||||
- `--coverage` - Generate coverage reports
|
||||
- `--watch` - Run tests in watch mode
|
||||
- `--fix` - Try to fix failing tests automatically
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/test --type unit --coverage
|
||||
/test --watch src/components/
|
||||
/test --type e2e --fix
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Needs your test framework to be properly configured
|
||||
- Coverage reports depend on your existing test setup
|
||||
- `--fix` is experimental - review what it changes
|
||||
|
||||
## Documentation Commands 📝
|
||||
|
||||
### `/document` - Focused Documentation
|
||||
**What it does**: Creates documentation for specific components, functions, or features.
|
||||
|
||||
**When to use it**:
|
||||
- Need README files
|
||||
- Writing API documentation
|
||||
- Adding code comments
|
||||
- Creating user guides
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/document src/api/auth.js # Document authentication module
|
||||
/document --type api # API documentation
|
||||
/document --style brief README # Brief README file
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--type inline|external|api|guide` - Documentation type
|
||||
- `--style brief|detailed` - Level of detail
|
||||
- `--template` - Use specific documentation template
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/document --type api src/controllers/
|
||||
/document --style detailed --type guide user-onboarding
|
||||
/document --type inline src/utils/helpers.js
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Better with specific files/functions than entire projects
|
||||
- Quality depends on how well-structured your code is
|
||||
- May need some editing to match your project's documentation style
|
||||
|
||||
## Project Management Commands 📊
|
||||
|
||||
### `/estimate` - Project Estimation
|
||||
**What it does**: Estimates time, effort, and complexity for development tasks.
|
||||
|
||||
**When to use it**:
|
||||
- Planning new features
|
||||
- Sprint planning
|
||||
- Understanding project complexity
|
||||
- Resource allocation
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/estimate "add user authentication" # Estimate auth feature
|
||||
/estimate --detailed shopping-cart # Detailed breakdown
|
||||
/estimate --complexity user-dashboard # Complexity analysis
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--detailed` - Detailed breakdown of tasks
|
||||
- `--complexity` - Focus on technical complexity
|
||||
- `--team-size <n>` - Consider team size in estimates
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/estimate --detailed "implement payment system"
|
||||
/estimate --complexity --team-size 3 "migrate to microservices"
|
||||
/estimate "add real-time chat" --detailed
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Estimates are rough - use as starting points, not gospel
|
||||
- Works better with clear, specific feature descriptions
|
||||
- Consider your team's experience with the tech stack
|
||||
|
||||
---
|
||||
|
||||
### `/task` - Long-term Project Management
|
||||
**What it does**: Manages complex, multi-session development tasks and features.
|
||||
|
||||
**When to use it**:
|
||||
- Planning features that take days/weeks
|
||||
- Breaking down large projects
|
||||
- Tracking progress across sessions
|
||||
- Coordinating team work
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/task create "implement user dashboard" # Create new task
|
||||
/task status # Check task status
|
||||
/task breakdown "payment integration" # Break down into subtasks
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `create` - Create new long-term task
|
||||
- `status` - Check current task status
|
||||
- `breakdown` - Break large task into smaller ones
|
||||
- `--priority high|medium|low` - Set task priority
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/task create "migrate from REST to GraphQL" --priority high
|
||||
/task breakdown "e-commerce checkout flow"
|
||||
/task status
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Still experimental - may not persist perfectly across sessions
|
||||
- Better for planning than actual project management
|
||||
- Works best when you're specific about requirements
|
||||
|
||||
---
|
||||
|
||||
### `/spawn` - Complex Operation Orchestration
|
||||
**What it does**: Coordinates complex, multi-step operations and workflows.
|
||||
|
||||
**When to use it**:
|
||||
- Operations involving multiple tools/systems
|
||||
- Coordinating parallel workflows
|
||||
- Complex deployment processes
|
||||
- Multi-stage data processing
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/spawn deploy-pipeline # Orchestrate deployment
|
||||
/spawn --parallel migrate-data # Parallel data migration
|
||||
/spawn setup-dev-environment # Complex environment setup
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--parallel` - Run operations in parallel when possible
|
||||
- `--sequential` - Force sequential execution
|
||||
- `--monitor` - Monitor operation progress
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/spawn --parallel "test and deploy to staging"
|
||||
/spawn setup-ci-cd --monitor
|
||||
/spawn --sequential database-migration
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Most complex command - expect some rough edges
|
||||
- Better for well-defined workflows than ad-hoc operations
|
||||
- May need multiple iterations to get right
|
||||
|
||||
## Version Control Commands 🔄
|
||||
|
||||
### `/git` - Enhanced Git Operations
|
||||
**What it does**: Git operations with intelligent commit messages and workflow optimization.
|
||||
|
||||
**When to use it**:
|
||||
- Making commits with better messages
|
||||
- Branch management
|
||||
- Complex git workflows
|
||||
- Git troubleshooting
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/git commit # Smart commit with auto-generated message
|
||||
/git --smart-commit add . # Add and commit with smart message
|
||||
/git branch feature/new-auth # Create and switch to new branch
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--smart-commit` - Generate intelligent commit messages
|
||||
- `--branch-strategy` - Apply branch naming conventions
|
||||
- `--interactive` - Interactive mode for complex operations
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/git --smart-commit "fixed login bug"
|
||||
/git branch feature/user-dashboard --branch-strategy
|
||||
/git merge develop --interactive
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Smart commit messages are pretty good but review them
|
||||
- Assumes you're following common git workflows
|
||||
- Won't fix bad git habits - just makes them easier
|
||||
|
||||
## Utility Commands 🔧
|
||||
|
||||
### `/index` - Command Navigation
|
||||
**What it does**: Helps you find the right command for your task.
|
||||
|
||||
**When to use it**:
|
||||
- Not sure which command to use
|
||||
- Exploring available commands
|
||||
- Learning about command capabilities
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/index # List all commands
|
||||
/index testing # Find commands related to testing
|
||||
/index --category analysis # Commands in analysis category
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--category <cat>` - Filter by command category
|
||||
- `--search <term>` - Search command descriptions
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/index --search "performance"
|
||||
/index --category quality
|
||||
/index git
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Simple but useful for discovery
|
||||
- Better than trying to remember all 15 commands
|
||||
|
||||
---
|
||||
|
||||
### `/load` - Project Context Loading
|
||||
**What it does**: Loads and analyzes project context for better understanding.
|
||||
|
||||
**When to use it**:
|
||||
- Starting work on unfamiliar project
|
||||
- Need to understand project structure
|
||||
- Before making major changes
|
||||
- Onboarding team members
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/load # Load current project context
|
||||
/load src/ # Load specific directory context
|
||||
/load --deep # Deep analysis of project structure
|
||||
```
|
||||
|
||||
**Useful flags**:
|
||||
- `--deep` - Comprehensive project analysis
|
||||
- `--focus <area>` - Focus on specific project area
|
||||
- `--summary` - Generate project summary
|
||||
|
||||
**Real examples**:
|
||||
```bash
|
||||
/load --deep --summary
|
||||
/load src/components/ --focus architecture
|
||||
/load . --focus dependencies
|
||||
```
|
||||
|
||||
**Gotchas**:
|
||||
- Can take time on large projects
|
||||
- More useful at project start than during development
|
||||
- Helps with onboarding but not a replacement for good docs
|
||||
|
||||
## Command Tips & Patterns 💡
|
||||
|
||||
### Effective Flag Combinations
|
||||
```bash
|
||||
# Safe improvement workflow
|
||||
/improve --preview src/component.js # See what would change
|
||||
/improve --safe src/component.js # Apply safe changes only
|
||||
|
||||
# Comprehensive analysis
|
||||
/analyze --focus security --depth deep
|
||||
/test --coverage
|
||||
/document --type api
|
||||
|
||||
# Smart git workflow
|
||||
/git add .
|
||||
/git --smart-commit --branch-strategy
|
||||
|
||||
# Project understanding workflow
|
||||
/load --deep --summary
|
||||
/analyze --focus architecture
|
||||
/document --type guide
|
||||
```
|
||||
|
||||
### Common Workflows
|
||||
|
||||
**New Project Onboarding**:
|
||||
```bash
|
||||
/load --deep --summary
|
||||
/analyze --focus architecture
|
||||
/test --coverage
|
||||
/document README
|
||||
```
|
||||
|
||||
**Bug Investigation**:
|
||||
```bash
|
||||
/troubleshoot "specific error message" --logs
|
||||
/analyze --focus security
|
||||
/test --type unit affected-component
|
||||
```
|
||||
|
||||
**Code Quality Improvement**:
|
||||
```bash
|
||||
/analyze --focus quality
|
||||
/improve --preview src/
|
||||
/cleanup --safe
|
||||
/test --coverage
|
||||
```
|
||||
|
||||
**Pre-deployment Checklist**:
|
||||
```bash
|
||||
/test --type all --coverage
|
||||
/analyze --focus security
|
||||
/build --type prod --optimize
|
||||
/git --smart-commit
|
||||
```
|
||||
|
||||
### Troubleshooting Command Issues
|
||||
|
||||
**Command not working as expected?**
|
||||
- Try adding `--help` to see all options
|
||||
- Use `--preview` or `--safe` flags when available
|
||||
- Start with smaller scope (single file vs. entire project)
|
||||
|
||||
**Analysis taking too long?**
|
||||
- Use `--focus` to narrow scope
|
||||
- Try `--depth quick` instead of deep analysis
|
||||
- Analyze smaller directories first
|
||||
|
||||
**Build/test commands failing?**
|
||||
- Make sure your tools are in PATH
|
||||
- Check that config files are in expected locations
|
||||
- Try running the underlying commands directly first
|
||||
|
||||
**Not sure which command to use?**
|
||||
- Use `/index` to browse available commands
|
||||
- Look at the Quick Reference table above
|
||||
- Try the most specific command first, then broader ones
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**Remember:**
|
||||
- Commands work best when you're specific about what you want
|
||||
- Use `--preview` and `--safe` flags liberally
|
||||
- Start small (single files) before running on entire projects
|
||||
- These commands enhance your workflow, they don't replace understanding your tools
|
||||
|
||||
**Still rough around the edges:**
|
||||
- Complex orchestration (spawn, task) may not work perfectly
|
||||
- Some analysis depends heavily on your project setup
|
||||
- Error handling could be better in some commands
|
||||
|
||||
**Getting better all the time:**
|
||||
- We actively improve commands based on user feedback
|
||||
- Newer commands (analyze, improve) tend to work better
|
||||
- Documentation and examples are constantly being updated
|
||||
|
||||
**Need help?** Check the GitHub issues or create a new one if you're stuck! 🚀
|
||||
|
||||
---
|
||||
|
||||
*Happy coding! We hope these commands make your development workflow a bit smoother. 🙂*
|
||||
503
Docs/flags-guide.md
Normal file
503
Docs/flags-guide.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# SuperClaude Flags User Guide 🏁
|
||||
|
||||
A practical guide to SuperClaude's flag system. Flags are like command-line options that change how SuperClaude behaves - think of them as superpowers for your commands.
|
||||
|
||||
## What Are Flags? 🤔
|
||||
|
||||
**Flags are modifiers** that change how SuperClaude processes your requests. They come after commands and start with `--`.
|
||||
|
||||
**Basic syntax**:
|
||||
```bash
|
||||
/command --flag-name
|
||||
/command --flag-name value
|
||||
/analyze src/ --focus security --depth deep
|
||||
```
|
||||
|
||||
**Two ways flags work**:
|
||||
1. **Manual** - You add them explicitly: `/analyze --think --focus security`
|
||||
2. **Auto-activation** - SuperClaude adds them based on context (this happens a lot!)
|
||||
|
||||
**Why use flags?**
|
||||
- Get better, more focused results
|
||||
- Control SuperClaude's thinking depth
|
||||
- Enable special capabilities (MCP servers)
|
||||
- Optimize for speed or detail
|
||||
- Direct attention to specific areas
|
||||
|
||||
## Flag Categories 📂
|
||||
|
||||
### Planning & Analysis Flags 🧠
|
||||
|
||||
These control how deeply SuperClaude thinks about your request.
|
||||
|
||||
#### `--plan`
|
||||
**What it does**: Shows execution plan before doing anything
|
||||
**When to use**: When you want to see what SuperClaude will do first
|
||||
**Example**: `/build --plan` - See build steps before running
|
||||
|
||||
#### `--think`
|
||||
**What it does**: Multi-file analysis (~4K tokens)
|
||||
**When to use**: Complex problems involving several files
|
||||
**Auto-activates**: Import chains >5 files, cross-module calls >10 references
|
||||
**Example**: `/analyze complex-system/ --think`
|
||||
|
||||
#### `--think-hard`
|
||||
**What it does**: Deep architectural analysis (~10K tokens)
|
||||
**When to use**: System-wide problems, architectural decisions
|
||||
**Auto-activates**: System refactoring, bottlenecks >3 modules
|
||||
**Example**: `/improve legacy-system/ --think-hard`
|
||||
|
||||
#### `--ultrathink`
|
||||
**What it does**: Maximum depth analysis (~32K tokens)
|
||||
**When to use**: Critical system redesign, complex debugging
|
||||
**Auto-activates**: Legacy modernization, critical vulnerabilities
|
||||
**Example**: `/troubleshoot "entire auth system broken" --ultrathink`
|
||||
|
||||
**💡 Tip**: Start with `--think`, only go deeper if needed. More thinking = slower but more thorough.
|
||||
|
||||
---
|
||||
|
||||
### Efficiency & Control Flags ⚡
|
||||
|
||||
Control output style, safety, and performance.
|
||||
|
||||
#### `--uc` / `--ultracompressed`
|
||||
**What it does**: 60-80% token reduction using symbols
|
||||
**When to use**: Large operations, when context is getting full
|
||||
**Auto-activates**: Context usage >75%, large-scale operations
|
||||
**Example**: `/analyze huge-codebase/ --uc`
|
||||
|
||||
#### `--safe-mode`
|
||||
**What it does**: Maximum validation, conservative execution
|
||||
**When to use**: Production environments, risky operations
|
||||
**Auto-activates**: Resource usage >85%, production environment
|
||||
**Example**: `/improve production-code/ --safe-mode`
|
||||
|
||||
#### `--validate`
|
||||
**What it does**: Pre-operation validation and risk assessment
|
||||
**When to use**: Want to check before making changes
|
||||
**Auto-activates**: Risk score >0.7
|
||||
**Example**: `/cleanup legacy/ --validate`
|
||||
|
||||
#### `--verbose`
|
||||
**What it does**: Maximum detail and explanation
|
||||
**When to use**: Learning, debugging, need full context
|
||||
**Example**: `/build --verbose` - See every build step
|
||||
|
||||
#### `--answer-only`
|
||||
**What it does**: Direct response without task creation
|
||||
**When to use**: Quick questions, don't want workflow automation
|
||||
**Example**: `/explain React hooks --answer-only`
|
||||
|
||||
**💡 Tip**: `--uc` is great for big operations. `--safe-mode` for anything important. `--verbose` when you're learning.
|
||||
|
||||
---
|
||||
|
||||
### MCP Server Flags 🔧
|
||||
|
||||
Enable specialized capabilities through MCP servers.
|
||||
|
||||
#### `--c7` / `--context7`
|
||||
**What it does**: Enables Context7 for official library documentation
|
||||
**When to use**: Working with frameworks, need official docs
|
||||
**Auto-activates**: External library imports, framework questions
|
||||
**Example**: `/build react-app/ --c7` - Get React best practices
|
||||
|
||||
#### `--seq` / `--sequential`
|
||||
**What it does**: Enables Sequential for complex multi-step analysis
|
||||
**When to use**: Complex debugging, system design
|
||||
**Auto-activates**: Complex debugging, `--think` flags
|
||||
**Example**: `/troubleshoot "auth flow broken" --seq`
|
||||
|
||||
#### `--magic`
|
||||
**What it does**: Enables Magic for UI component generation
|
||||
**When to use**: Creating UI components, design systems
|
||||
**Auto-activates**: UI component requests, frontend persona
|
||||
**Example**: `/build dashboard --magic` - Get modern UI components
|
||||
|
||||
#### `--play` / `--playwright`
|
||||
**What it does**: Enables Playwright for browser automation and testing
|
||||
**When to use**: E2E testing, performance monitoring
|
||||
**Auto-activates**: Test workflows, QA persona
|
||||
**Example**: `/test e2e --play`
|
||||
|
||||
#### `--all-mcp`
|
||||
**What it does**: Enables all MCP servers simultaneously
|
||||
**When to use**: Complex multi-domain problems
|
||||
**Auto-activates**: Problem complexity >0.8, multi-domain indicators
|
||||
**Example**: `/analyze entire-app/ --all-mcp`
|
||||
|
||||
#### `--no-mcp`
|
||||
**What it does**: Disables all MCP servers, native tools only
|
||||
**When to use**: Faster execution, don't need specialized features
|
||||
**Example**: `/analyze simple-script.js --no-mcp`
|
||||
|
||||
**💡 Tip**: MCP servers add capabilities but use more tokens. `--c7` for docs, `--seq` for thinking, `--magic` for UI.
|
||||
|
||||
---
|
||||
|
||||
### Advanced Orchestration Flags 🎭
|
||||
|
||||
For complex operations and workflows.
|
||||
|
||||
#### `--delegate [files|folders|auto]`
|
||||
**What it does**: Enables sub-agent delegation for parallel processing
|
||||
**When to use**: Large codebases, complex analysis
|
||||
**Auto-activates**: >7 directories or >50 files
|
||||
**Options**:
|
||||
- `files` - Delegate individual file analysis
|
||||
- `folders` - Delegate directory-level analysis
|
||||
- `auto` - Smart delegation strategy
|
||||
|
||||
**Example**: `/analyze monorepo/ --delegate auto`
|
||||
|
||||
#### `--wave-mode [auto|force|off]`
|
||||
**What it does**: Multi-stage execution with compound intelligence
|
||||
**When to use**: Complex improvements, systematic analysis
|
||||
**Auto-activates**: Complexity >0.8 AND files >20 AND operation types >2
|
||||
**Example**: `/improve legacy-system/ --wave-mode force`
|
||||
|
||||
#### `--loop`
|
||||
**What it does**: Iterative improvement mode
|
||||
**When to use**: Quality improvement, refinement operations
|
||||
**Auto-activates**: Polish, refine, enhance keywords
|
||||
**Example**: `/improve messy-code.js --loop`
|
||||
|
||||
#### `--concurrency [n]`
|
||||
**What it does**: Control max concurrent sub-agents (1-15)
|
||||
**When to use**: Controlling resource usage
|
||||
**Example**: `/analyze --delegate auto --concurrency 3`
|
||||
|
||||
**💡 Tip**: These are powerful but complex. Start with `--delegate auto` for big projects, `--loop` for improvements.
|
||||
|
||||
---
|
||||
|
||||
### Focus & Scope Flags 🎯
|
||||
|
||||
Direct SuperClaude's attention to specific areas.
|
||||
|
||||
#### `--scope [level]`
|
||||
**Options**: file, module, project, system
|
||||
**What it does**: Sets analysis scope
|
||||
**Example**: `/analyze --scope module auth/`
|
||||
|
||||
#### `--focus [domain]`
|
||||
**Options**: performance, security, quality, architecture, accessibility, testing
|
||||
**What it does**: Focuses analysis on specific domain
|
||||
**Example**: `/analyze --focus security --scope project`
|
||||
|
||||
#### Persona Flags
|
||||
**Available personas**: architect, frontend, backend, analyzer, security, mentor, refactorer, performance, qa, devops, scribe
|
||||
**What they do**: Activates specialist behavior patterns
|
||||
**Example**: `/analyze --persona-security` - Security-focused analysis
|
||||
|
||||
**💡 Tip**: `--focus` is great for targeted analysis. Personas auto-activate but manual control helps.
|
||||
|
||||
---
|
||||
|
||||
## Common Flag Patterns 🔄
|
||||
|
||||
### Quick Analysis
|
||||
```bash
|
||||
/analyze src/ --focus quality # Quick quality check
|
||||
/analyze --uc --focus security # Fast security scan
|
||||
```
|
||||
|
||||
### Deep Investigation
|
||||
```bash
|
||||
/troubleshoot "bug" --think --seq # Systematic debugging
|
||||
/analyze --think-hard --focus architecture # Architectural analysis
|
||||
```
|
||||
|
||||
### Large Project Work
|
||||
```bash
|
||||
/analyze monorepo/ --delegate auto --uc # Efficient large analysis
|
||||
/improve legacy/ --wave-mode auto --safe-mode # Safe systematic improvement
|
||||
```
|
||||
|
||||
### Learning & Documentation
|
||||
```bash
|
||||
/explain React hooks --c7 --verbose # Detailed explanation with docs
|
||||
/document api/ --persona-scribe # Professional documentation
|
||||
```
|
||||
|
||||
### Performance-Focused
|
||||
```bash
|
||||
/analyze --focus performance --play # Performance analysis with testing
|
||||
/build --uc --no-mcp # Fast build without extra features
|
||||
```
|
||||
|
||||
### Security-Focused
|
||||
```bash
|
||||
/analyze --focus security --think --validate # Thorough security analysis
|
||||
/scan --persona-security --safe-mode # Conservative security scan
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
|
||||
### Before/After: Basic Analysis
|
||||
**Before** (basic):
|
||||
```bash
|
||||
/analyze auth.js
|
||||
# → Simple file analysis
|
||||
```
|
||||
|
||||
**After** (with flags):
|
||||
```bash
|
||||
/analyze auth.js --focus security --think --c7
|
||||
# → Security-focused analysis with deep thinking and official docs
|
||||
# → Much more thorough, finds security patterns, checks against best practices
|
||||
```
|
||||
|
||||
### Before/After: Large Project
|
||||
**Before** (slow):
|
||||
```bash
|
||||
/analyze huge-monorepo/
|
||||
# → Tries to analyze everything at once, may timeout or use too many tokens
|
||||
```
|
||||
|
||||
**After** (efficient):
|
||||
```bash
|
||||
/analyze huge-monorepo/ --delegate auto --uc --focus architecture
|
||||
# → Delegates work to sub-agents, compresses output, focuses on architecture
|
||||
# → Faster, more focused, better results
|
||||
```
|
||||
|
||||
### Before/After: Improvement Work
|
||||
**Before** (risky):
|
||||
```bash
|
||||
/improve legacy-system/
|
||||
# → May make too many changes, could break things
|
||||
```
|
||||
|
||||
**After** (safe):
|
||||
```bash
|
||||
/improve legacy-system/ --safe-mode --loop --validate --preview
|
||||
# → Safe changes only, iterative approach, validates first, shows preview
|
||||
# → Much safer, progressive improvement
|
||||
```
|
||||
|
||||
## Auto-Activation Examples 🤖
|
||||
|
||||
SuperClaude automatically adds flags based on context. Here's when:
|
||||
|
||||
### Complexity-Based
|
||||
```bash
|
||||
/analyze huge-codebase/
|
||||
# Auto-adds: --delegate auto --uc
|
||||
# Why: >50 files detected, context management needed
|
||||
|
||||
/troubleshoot "complex system issue"
|
||||
# Auto-adds: --think --seq
|
||||
# Why: Multi-component problem detected
|
||||
```
|
||||
|
||||
### Domain-Based
|
||||
```bash
|
||||
/build react-app/
|
||||
# Auto-adds: --c7 --persona-frontend
|
||||
# Why: Frontend framework detected
|
||||
|
||||
/analyze --focus security
|
||||
# Auto-adds: --persona-security --validate
|
||||
# Why: Security focus triggers security specialist
|
||||
```
|
||||
|
||||
### Performance-Based
|
||||
```bash
|
||||
# When context usage >75%
|
||||
/analyze large-project/
|
||||
# Auto-adds: --uc
|
||||
# Why: Token optimization needed
|
||||
|
||||
# When risk score >0.7
|
||||
/improve production-code/
|
||||
# Auto-adds: --safe-mode --validate
|
||||
# Why: High-risk operation detected
|
||||
```
|
||||
|
||||
## Advanced Usage 🚀
|
||||
|
||||
### Complex Flag Combinations
|
||||
|
||||
**Comprehensive Code Review**:
|
||||
```bash
|
||||
/review codebase/ --persona-qa --think-hard --focus quality --validate --c7
|
||||
# → QA specialist + deep thinking + quality focus + validation + docs
|
||||
```
|
||||
|
||||
**Legacy System Modernization**:
|
||||
```bash
|
||||
/improve legacy/ --wave-mode force --persona-architect --safe-mode --loop --c7
|
||||
# → Wave orchestration + architect perspective + safety + iteration + docs
|
||||
```
|
||||
|
||||
**Security Audit**:
|
||||
```bash
|
||||
/scan --persona-security --ultrathink --focus security --validate --seq
|
||||
# → Security specialist + maximum thinking + security focus + validation + systematic analysis
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
**For Speed**:
|
||||
```bash
|
||||
/analyze --no-mcp --uc --scope file
|
||||
# → Disable extra features, compress output, limit scope
|
||||
```
|
||||
|
||||
**For Thoroughness**:
|
||||
```bash
|
||||
/analyze --all-mcp --think-hard --delegate auto
|
||||
# → All capabilities, deep thinking, parallel processing
|
||||
```
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
**Bug Investigation Workflow**:
|
||||
```bash
|
||||
/troubleshoot "specific error" --seq --think --validate
|
||||
/analyze affected-files/ --focus quality --persona-analyzer
|
||||
/test --play --coverage
|
||||
```
|
||||
|
||||
**Feature Development Workflow**:
|
||||
```bash
|
||||
/design new-feature --persona-architect --c7
|
||||
/build --magic --persona-frontend --validate
|
||||
/test --play --coverage
|
||||
/document --persona-scribe --c7
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Most Useful Flags
|
||||
| Flag | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| `--think` | Deeper analysis | Complex problems |
|
||||
| `--uc` | Compress output | Large operations |
|
||||
| `--safe-mode` | Conservative execution | Important code |
|
||||
| `--c7` | Official docs | Framework work |
|
||||
| `--seq` | Systematic analysis | Debugging |
|
||||
| `--focus security` | Security focus | Security concerns |
|
||||
| `--delegate auto` | Parallel processing | Large codebases |
|
||||
| `--validate` | Check before action | Risky operations |
|
||||
|
||||
### Flag Combinations That Work Well
|
||||
```bash
|
||||
# Safe improvement
|
||||
--safe-mode --validate --preview
|
||||
|
||||
# Deep analysis
|
||||
--think --seq --c7
|
||||
|
||||
# Large project
|
||||
--delegate auto --uc --focus
|
||||
|
||||
# Learning
|
||||
--verbose --c7 --persona-mentor
|
||||
|
||||
# Security work
|
||||
--persona-security --focus security --validate
|
||||
|
||||
# Performance work
|
||||
--persona-performance --focus performance --play
|
||||
```
|
||||
|
||||
### Auto-Activation Triggers
|
||||
- **--think**: Complex imports, cross-module calls
|
||||
- **--uc**: Context >75%, large operations
|
||||
- **--safe-mode**: Resource usage >85%, production
|
||||
- **--delegate**: >7 directories or >50 files
|
||||
- **--c7**: Framework imports, documentation requests
|
||||
- **--seq**: Debugging keywords, --think flags
|
||||
- **Personas**: Domain-specific keywords and patterns
|
||||
|
||||
## Troubleshooting Flag Issues 🚨
|
||||
|
||||
### Common Problems
|
||||
|
||||
**"Flags don't seem to work"**
|
||||
- Check spelling (common typos: `--ultracompresed`, `--persona-fronted`)
|
||||
- Some flags need values: `--scope project`, `--focus security`
|
||||
- Flag conflicts: `--no-mcp` overrides `--c7`, `--seq`, etc.
|
||||
|
||||
**"Operation too slow"**
|
||||
- Try `--uc` for compression
|
||||
- Use `--no-mcp` to disable extra features
|
||||
- Limit scope: `--scope file` instead of `--scope project`
|
||||
|
||||
**"Too much output"**
|
||||
- Add `--uc` for compression
|
||||
- Remove `--verbose` if present
|
||||
- Use `--answer-only` for simple questions
|
||||
|
||||
**"Not thorough enough"**
|
||||
- Add `--think` or `--think-hard`
|
||||
- Enable relevant MCP servers: `--seq`, `--c7`
|
||||
- Use appropriate persona: `--persona-analyzer`
|
||||
|
||||
**"Changes too risky"**
|
||||
- Always use `--safe-mode` for important code
|
||||
- Add `--validate` to check first
|
||||
- Use `--preview` to see changes before applying
|
||||
|
||||
### Flag Conflicts
|
||||
|
||||
**These override others**:
|
||||
- `--no-mcp` overrides all MCP flags (`--c7`, `--seq`, etc.)
|
||||
- `--safe-mode` overrides optimization flags
|
||||
- Last persona flag wins: `--persona-frontend --persona-backend` → backend
|
||||
|
||||
**Precedence order**:
|
||||
1. Safety flags (`--safe-mode`) beat optimization
|
||||
2. Explicit flags beat auto-activation
|
||||
3. Thinking depth: `--ultrathink` > `--think-hard` > `--think`
|
||||
4. Scope: system > project > module > file
|
||||
|
||||
## Tips for Effective Flag Usage 💡
|
||||
|
||||
### Starting Out
|
||||
1. **Begin simple**: Try basic flags like `--think` and `--focus`
|
||||
2. **Watch auto-activation**: See what SuperClaude adds automatically
|
||||
3. **Use `--help`**: Many commands show available flags
|
||||
4. **Start safe**: Use `--safe-mode` and `--validate` for important work
|
||||
|
||||
### Getting Advanced
|
||||
1. **Learn combinations**: `--think --seq --c7` works great together
|
||||
2. **Understand auto-activation**: Know when flags get added automatically
|
||||
3. **Use personas**: They're like having specialists on your team
|
||||
4. **Optimize for your workflow**: Fast (`--uc --no-mcp`) vs thorough (`--think-hard --all-mcp`)
|
||||
|
||||
### Performance Tips
|
||||
- **For speed**: `--uc --no-mcp --scope file`
|
||||
- **For thoroughness**: `--think-hard --all-mcp --delegate auto`
|
||||
- **For safety**: `--safe-mode --validate --preview`
|
||||
- **For learning**: `--verbose --c7 --persona-mentor`
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**Remember:**
|
||||
- Flags make SuperClaude more powerful but also more complex
|
||||
- Start simple and add flags as you learn what they do
|
||||
- Auto-activation usually gets it right - trust it until you know better
|
||||
- `--safe-mode` and `--validate` are your friends for important work
|
||||
|
||||
**Still evolving:**
|
||||
- Some advanced flags (wave, delegation) are still experimental
|
||||
- Auto-activation keeps getting smarter
|
||||
- New flags and capabilities are added regularly
|
||||
|
||||
**When in doubt:**
|
||||
- Start with basic commands and see what auto-activates
|
||||
- Use `--safe-mode` for anything important
|
||||
- Check the commands guide for flag suggestions per command
|
||||
- GitHub issues are great for flag-related questions
|
||||
|
||||
**Happy flagging!** 🚩 These flags can really supercharge your SuperClaude experience once you get the hang of them.
|
||||
|
||||
---
|
||||
|
||||
*Flags are like spices - a little goes a long way, and the right combination can make everything better! 🌶️*
|
||||
466
Docs/installation-guide.md
Normal file
466
Docs/installation-guide.md
Normal file
@@ -0,0 +1,466 @@
|
||||
# SuperClaude Installation Guide 📦
|
||||
|
||||
A comprehensive guide to installing SuperClaude v3. We'll be honest - this might seem a bit complex at first, but we've tried to make it as straightforward as possible.
|
||||
|
||||
## Before You Start 🔍
|
||||
|
||||
### What You Need 💻
|
||||
|
||||
SuperClaude works on **Windows**, **macOS**, and **Linux**. Here's what you need:
|
||||
|
||||
**Required:**
|
||||
- **Python 3.8 or newer** - The framework is written in Python
|
||||
- **Claude CLI** - SuperClaude enhances Claude Code, so you need it installed first
|
||||
|
||||
**Optional (but recommended):**
|
||||
- **Node.js 16+** - Only needed if you want MCP server integration
|
||||
- **Git** - Helpful for development workflows
|
||||
|
||||
### Quick Check 🔍
|
||||
|
||||
Before installing, let's make sure you have the basics:
|
||||
|
||||
```bash
|
||||
# Check Python version (should be 3.8+)
|
||||
python3 --version
|
||||
|
||||
# Check if Claude CLI is installed
|
||||
claude --version
|
||||
|
||||
# Check Node.js (optional, for MCP servers)
|
||||
node --version
|
||||
```
|
||||
|
||||
If any of these fail, see the [Prerequisites Setup](#prerequisites-setup-🛠️) section below.
|
||||
|
||||
## Quick Start 🚀
|
||||
|
||||
**TL;DR for the impatient:**
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone <repository-url>
|
||||
cd SuperClaude
|
||||
|
||||
# Install with recommended settings
|
||||
python3 SuperClaude.py install --quick
|
||||
|
||||
# That's it! 🎉
|
||||
```
|
||||
|
||||
This installs SuperClaude with the most commonly used features. Takes about 2 minutes and uses ~50MB of disk space.
|
||||
|
||||
**Want to see what would happen first?**
|
||||
```bash
|
||||
python3 SuperClaude.py install --quick --dry-run
|
||||
```
|
||||
|
||||
## Installation Options 🎯
|
||||
|
||||
We have three installation profiles to choose from:
|
||||
|
||||
### 🎯 Minimal Installation
|
||||
```bash
|
||||
python3 SuperClaude.py install --minimal
|
||||
```
|
||||
- **What**: Just the core framework files
|
||||
- **Time**: ~1 minute
|
||||
- **Space**: ~20MB
|
||||
- **Good for**: Testing, basic enhancement, minimal setups
|
||||
- **Includes**: Core behavior documentation that guides Claude
|
||||
|
||||
### 🚀 Quick Installation (Recommended)
|
||||
```bash
|
||||
python3 SuperClaude.py install --quick
|
||||
```
|
||||
- **What**: Core framework + 15 slash commands
|
||||
- **Time**: ~2 minutes
|
||||
- **Space**: ~50MB
|
||||
- **Good for**: Most users, general development
|
||||
- **Includes**: Everything in minimal + specialized commands like `/analyze`, `/build`, `/improve`
|
||||
|
||||
### 🔧 Developer Installation
|
||||
```bash
|
||||
python3 SuperClaude.py install --profile developer
|
||||
```
|
||||
- **What**: Everything including MCP server integration
|
||||
- **Time**: ~5 minutes
|
||||
- **Space**: ~100MB
|
||||
- **Good for**: Power users, contributors, advanced workflows
|
||||
- **Includes**: Everything + Context7, Sequential, Magic, Playwright servers
|
||||
|
||||
### 🎛️ Interactive Installation
|
||||
```bash
|
||||
python3 SuperClaude.py install
|
||||
```
|
||||
- Lets you pick and choose components
|
||||
- Shows detailed descriptions of what each component does
|
||||
- Good if you want control over what gets installed
|
||||
|
||||
## Step-by-Step Installation 📋
|
||||
|
||||
### Prerequisites Setup 🛠️
|
||||
|
||||
**Missing Python?**
|
||||
```bash
|
||||
# Linux (Ubuntu/Debian)
|
||||
sudo apt update && sudo apt install python3 python3-pip
|
||||
|
||||
# macOS
|
||||
brew install python3
|
||||
|
||||
# Windows
|
||||
# Download from https://python.org/downloads/
|
||||
```
|
||||
|
||||
**Missing Claude CLI?**
|
||||
- Visit https://claude.ai/code for installation instructions
|
||||
- SuperClaude enhances Claude Code, so you need it first
|
||||
|
||||
**Missing Node.js? (Optional)**
|
||||
```bash
|
||||
# Linux (Ubuntu/Debian)
|
||||
sudo apt update && sudo apt install nodejs npm
|
||||
|
||||
# macOS
|
||||
brew install node
|
||||
|
||||
# Windows
|
||||
# Download from https://nodejs.org/
|
||||
```
|
||||
|
||||
### Getting SuperClaude 📥
|
||||
|
||||
**Option 1: Download the latest release**
|
||||
```bash
|
||||
# Download and extract the latest release
|
||||
# (Replace URL with actual release URL)
|
||||
curl -L <release-url> -o superclaude-v3.zip
|
||||
unzip superclaude-v3.zip
|
||||
cd superclaude-v3
|
||||
```
|
||||
|
||||
**Option 2: Clone from Git**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd SuperClaude
|
||||
```
|
||||
|
||||
### Running the Installer 🎬
|
||||
|
||||
The installer is pretty smart and will guide you through the process:
|
||||
|
||||
```bash
|
||||
# See all available options
|
||||
python3 SuperClaude.py install --help
|
||||
|
||||
# Quick installation (recommended)
|
||||
python3 SuperClaude.py install --quick
|
||||
|
||||
# Want to see what would happen first?
|
||||
python3 SuperClaude.py install --quick --dry-run
|
||||
|
||||
# Install everything
|
||||
python3 SuperClaude.py install --profile developer
|
||||
|
||||
# Quiet installation (minimal output)
|
||||
python3 SuperClaude.py install --quick --quiet
|
||||
|
||||
# Force installation (skip confirmations)
|
||||
python3 SuperClaude.py install --quick --force
|
||||
```
|
||||
|
||||
### During Installation 📱
|
||||
|
||||
Here's what happens when you install:
|
||||
|
||||
1. **System Check** - Verifies you have required dependencies
|
||||
2. **Directory Setup** - Creates `~/.claude/` directory structure
|
||||
3. **Core Files** - Copies framework documentation files
|
||||
4. **Commands** - Installs slash command definitions (if selected)
|
||||
5. **MCP Servers** - Downloads and configures MCP servers (if selected)
|
||||
6. **Configuration** - Sets up `settings.json` with your preferences
|
||||
7. **Validation** - Tests that everything works
|
||||
|
||||
The installer shows progress and will tell you if anything goes wrong.
|
||||
|
||||
## After Installation ✅
|
||||
|
||||
### Quick Test 🧪
|
||||
|
||||
Let's make sure everything worked:
|
||||
|
||||
```bash
|
||||
# Check if files were installed
|
||||
ls ~/.claude/
|
||||
|
||||
# Should show: CLAUDE.md, COMMANDS.md, settings.json, etc.
|
||||
```
|
||||
|
||||
**Test with Claude Code:**
|
||||
1. Open Claude Code
|
||||
2. Try typing `/help` - you should see SuperClaude commands
|
||||
3. Try `/analyze --help` - should show command options
|
||||
|
||||
### What Got Installed 📂
|
||||
|
||||
SuperClaude installs to `~/.claude/` by default. Here's what you'll find:
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── CLAUDE.md # Main framework entry point
|
||||
├── COMMANDS.md # Available slash commands
|
||||
├── FLAGS.md # Command flags and options
|
||||
├── PERSONAS.md # Smart persona system
|
||||
├── PRINCIPLES.md # Development principles
|
||||
├── RULES.md # Operational rules
|
||||
├── MCP.md # MCP server integration
|
||||
├── MODES.md # Operational modes
|
||||
├── ORCHESTRATOR.md # Intelligent routing
|
||||
├── settings.json # Configuration file
|
||||
└── commands/ # Individual command definitions
|
||||
├── analyze.md
|
||||
├── build.md
|
||||
├── improve.md
|
||||
└── ... (13 more)
|
||||
```
|
||||
|
||||
**What each file does:**
|
||||
- **CLAUDE.md** - Tells Claude Code about SuperClaude and loads other files
|
||||
- **settings.json** - Configuration (MCP servers, hooks, etc.)
|
||||
- **commands/** - Detailed definitions for each slash command
|
||||
|
||||
### First Steps 🎯
|
||||
|
||||
Try these commands to get started:
|
||||
|
||||
```bash
|
||||
# In Claude Code, try these:
|
||||
/help # See available commands
|
||||
/analyze README.md # Analyze a file
|
||||
/build --help # See build options
|
||||
/improve --help # See improvement options
|
||||
```
|
||||
|
||||
**Don't worry if it seems overwhelming** - SuperClaude enhances Claude Code gradually. You can use as much or as little as you want.
|
||||
|
||||
## Managing Your Installation 🛠️
|
||||
|
||||
### Updates 📅
|
||||
|
||||
Keep SuperClaude up to date:
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
python3 SuperClaude.py update
|
||||
|
||||
# Force update (overwrite local changes)
|
||||
python3 SuperClaude.py update --force
|
||||
|
||||
# Update specific components only
|
||||
python3 SuperClaude.py update --components core,commands
|
||||
|
||||
# See what would be updated
|
||||
python3 SuperClaude.py update --dry-run
|
||||
```
|
||||
|
||||
**When to update:**
|
||||
- When new SuperClaude versions are released
|
||||
- If you're having issues (updates often include fixes)
|
||||
- When new MCP servers become available
|
||||
|
||||
### Backups 💾
|
||||
|
||||
Create backups before major changes:
|
||||
|
||||
```bash
|
||||
# Create a backup
|
||||
python3 SuperClaude.py backup --create
|
||||
|
||||
# List existing backups
|
||||
python3 SuperClaude.py backup --list
|
||||
|
||||
# Restore from backup
|
||||
python3 SuperClaude.py backup --restore
|
||||
|
||||
# Create backup with custom name
|
||||
python3 SuperClaude.py backup --create --name "before-update"
|
||||
```
|
||||
|
||||
**When to backup:**
|
||||
- Before updating SuperClaude
|
||||
- Before experimenting with settings
|
||||
- Before uninstalling
|
||||
- Periodically if you've customized heavily
|
||||
|
||||
### Uninstallation 🗑️
|
||||
|
||||
If you need to remove SuperClaude:
|
||||
|
||||
```bash
|
||||
# Remove SuperClaude (keeps backups)
|
||||
python3 SuperClaude.py uninstall
|
||||
|
||||
# Complete removal (removes everything)
|
||||
python3 SuperClaude.py uninstall --complete
|
||||
|
||||
# See what would be removed
|
||||
python3 SuperClaude.py uninstall --dry-run
|
||||
```
|
||||
|
||||
**What gets removed:**
|
||||
- All files in `~/.claude/`
|
||||
- MCP server configurations
|
||||
- SuperClaude settings from Claude Code
|
||||
|
||||
**What stays:**
|
||||
- Your backups (unless you use `--complete`)
|
||||
- Claude Code itself (SuperClaude doesn't touch it)
|
||||
- Your projects and other files
|
||||
|
||||
## Troubleshooting 🔧
|
||||
|
||||
### Common Issues 🚨
|
||||
|
||||
**"Python not found"**
|
||||
```bash
|
||||
# Try python instead of python3
|
||||
python --version
|
||||
|
||||
# Or check if it's installed but not in PATH
|
||||
which python3
|
||||
```
|
||||
|
||||
**"Claude CLI not found"**
|
||||
- Make sure Claude Code is installed first
|
||||
- Try `claude --version` to verify
|
||||
- Visit https://claude.ai/code for installation help
|
||||
|
||||
**"Permission denied"**
|
||||
```bash
|
||||
# Try with explicit Python path
|
||||
/usr/bin/python3 SuperClaude.py install --quick
|
||||
|
||||
# Or check if you need different permissions
|
||||
ls -la ~/.claude/
|
||||
```
|
||||
|
||||
**"MCP servers won't install"**
|
||||
- Check that Node.js is installed: `node --version`
|
||||
- Check that npm is available: `npm --version`
|
||||
- Try installing without MCP first: `--minimal` or `--quick`
|
||||
|
||||
**"Installation fails partway through"**
|
||||
```bash
|
||||
# Try with verbose output to see what's happening
|
||||
python3 SuperClaude.py install --quick --verbose
|
||||
|
||||
# Or try a dry run first
|
||||
python3 SuperClaude.py install --quick --dry-run
|
||||
```
|
||||
|
||||
### Platform-Specific Issues 🖥️
|
||||
|
||||
**Windows:**
|
||||
- Use `python` instead of `python3` if you get "command not found"
|
||||
- Run Command Prompt as Administrator if you get permission errors
|
||||
- Make sure Python is in your PATH
|
||||
|
||||
**macOS:**
|
||||
- You might need to approve SuperClaude in Security & Privacy settings
|
||||
- Use `brew install python3` if you don't have Python 3.8+
|
||||
- Try using `python3` explicitly instead of `python`
|
||||
|
||||
**Linux:**
|
||||
- Make sure you have `python3-pip` installed
|
||||
- You might need `sudo` for some package installations
|
||||
- Check that `~/.local/bin` is in your PATH
|
||||
|
||||
### Still Having Issues? 🤔
|
||||
|
||||
**Check our troubleshooting resources:**
|
||||
- GitHub Issues: https://github.com/your-repo/SuperClaude/issues
|
||||
- Look for existing issues similar to yours
|
||||
- Create a new issue if you can't find a solution
|
||||
|
||||
**When reporting bugs, please include:**
|
||||
- Your operating system and version
|
||||
- Python version (`python3 --version`)
|
||||
- Claude CLI version (`claude --version`)
|
||||
- The exact command you ran
|
||||
- The complete error message
|
||||
- What you expected to happen
|
||||
|
||||
**Getting Help:**
|
||||
- GitHub Discussions for general questions
|
||||
- Check the README.md for latest updates
|
||||
- Look at the ROADMAP.md to see if your issue is known
|
||||
|
||||
## Advanced Options ⚙️
|
||||
|
||||
### Custom Installation Directory
|
||||
|
||||
```bash
|
||||
# Install to custom location
|
||||
python3 SuperClaude.py install --quick --install-dir /custom/path
|
||||
|
||||
# Use environment variable
|
||||
export SUPERCLAUDE_DIR=/custom/path
|
||||
python3 SuperClaude.py install --quick
|
||||
```
|
||||
|
||||
### Component Selection
|
||||
|
||||
```bash
|
||||
# See available components
|
||||
python3 SuperClaude.py install --list-components
|
||||
|
||||
# Install specific components only
|
||||
python3 SuperClaude.py install --components core,commands
|
||||
|
||||
# Skip certain components
|
||||
python3 SuperClaude.py install --quick --skip mcp
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
If you're planning to contribute or modify SuperClaude:
|
||||
|
||||
```bash
|
||||
# Developer installation with all components
|
||||
python3 SuperClaude.py install --profile developer
|
||||
|
||||
# Install in development mode (symlinks instead of copies)
|
||||
python3 SuperClaude.py install --profile developer --dev-mode
|
||||
|
||||
# Install with git hooks for development
|
||||
python3 SuperClaude.py install --profile developer --dev-hooks
|
||||
```
|
||||
|
||||
## What's Next? 🚀
|
||||
|
||||
**Now that SuperClaude is installed:**
|
||||
|
||||
1. **Try the basic commands** - Start with `/help` and `/analyze`
|
||||
2. **Read the user guides** - Check `Docs/` for more detailed guides
|
||||
3. **Experiment** - SuperClaude is designed to enhance your existing workflow
|
||||
4. **Give feedback** - Let us know what works and what doesn't
|
||||
5. **Stay updated** - Check for updates occasionally
|
||||
|
||||
**Remember:** SuperClaude is designed to make Claude Code more useful, not to replace your existing tools. Start small and gradually use more features as you get comfortable.
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
- **Installation takes 1-5 minutes** depending on what you choose
|
||||
- **Disk space needed: 20-100MB** (not much!)
|
||||
- **Works alongside existing tools** - doesn't interfere with your setup
|
||||
- **Easy to uninstall** if you change your mind
|
||||
- **Community supported** - we actually read and respond to issues
|
||||
|
||||
Thanks for trying SuperClaude! We hope it makes your development workflow a bit smoother. 🙂
|
||||
|
||||
---
|
||||
|
||||
*Last updated: July 2024 - Let us know if anything in this guide is wrong or confusing!*
|
||||
834
Docs/personas-guide.md
Normal file
834
Docs/personas-guide.md
Normal file
@@ -0,0 +1,834 @@
|
||||
# SuperClaude Personas User Guide 🎭
|
||||
|
||||
Think of SuperClaude personas as having a team of specialists on demand. Each persona brings different expertise, priorities, and perspectives to help you with specific types of work.
|
||||
|
||||
## What Are Personas? 🤔
|
||||
|
||||
**Personas are AI specialists** that change how SuperClaude approaches your requests. Instead of one generic assistant, you get access to 11 different experts who think and work differently.
|
||||
|
||||
**How they work:**
|
||||
- **Auto-activation** - SuperClaude picks the right persona based on your request
|
||||
- **Manual control** - You can explicitly choose with `--persona-name` flags
|
||||
- **Different priorities** - Each persona values different things (security vs speed, etc.)
|
||||
- **Specialized knowledge** - Each has deep expertise in their domain
|
||||
- **Cross-collaboration** - Personas can work together on complex tasks
|
||||
|
||||
**Why use personas?**
|
||||
- Get expert-level advice for specific domains
|
||||
- Better decision-making aligned with your goals
|
||||
- More focused and relevant responses
|
||||
- Access to specialized workflows and best practices
|
||||
|
||||
## The SuperClaude Team 👥
|
||||
|
||||
### Technical Specialists 🔧
|
||||
|
||||
#### 🏗️ `architect` - Systems Design Specialist
|
||||
**What they do**: Long-term architecture planning, system design, scalability decisions
|
||||
|
||||
**Priority**: Long-term maintainability > scalability > performance > quick fixes
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "architecture", "design", "scalability", "system structure"
|
||||
- Complex system modifications involving multiple modules
|
||||
- Planning large features or system changes
|
||||
|
||||
**Great for**:
|
||||
- Planning new systems or major features
|
||||
- Architectural reviews and improvements
|
||||
- Technical debt assessment
|
||||
- Design pattern recommendations
|
||||
- Scalability planning
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/design microservices-migration --persona-architect
|
||||
/analyze --focus architecture large-system/
|
||||
/estimate "redesign auth system" --persona-architect
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Maintainable, understandable code
|
||||
- Loose coupling, high cohesion
|
||||
- Future-proof design decisions
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
#### 🎨 `frontend` - UI/UX & Accessibility Expert
|
||||
**What they do**: User experience, accessibility, frontend performance, design systems
|
||||
|
||||
**Priority**: User needs > accessibility > performance > technical elegance
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "component", "responsive", "accessibility", "UI", "UX"
|
||||
- Frontend development work
|
||||
- User interface related tasks
|
||||
|
||||
**Great for**:
|
||||
- Building UI components
|
||||
- Accessibility compliance (WCAG 2.1 AA)
|
||||
- Frontend performance optimization
|
||||
- Design system work
|
||||
- User experience improvements
|
||||
|
||||
**Performance budgets they enforce**:
|
||||
- Load time: <3s on 3G, <1s on WiFi
|
||||
- Bundle size: <500KB initial, <2MB total
|
||||
- Accessibility: 90%+ WCAG compliance
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/build dashboard --persona-frontend
|
||||
/improve --focus accessibility components/
|
||||
/analyze --persona-frontend --focus performance
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Intuitive, user-friendly interfaces
|
||||
- Accessibility for all users
|
||||
- Real-world performance on mobile/3G
|
||||
- Clean, maintainable CSS/JS
|
||||
|
||||
---
|
||||
|
||||
#### ⚙️ `backend` - API & Infrastructure Specialist
|
||||
**What they do**: Server-side development, APIs, databases, reliability engineering
|
||||
|
||||
**Priority**: Reliability > security > performance > features > convenience
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "API", "database", "service", "server", "reliability"
|
||||
- Backend development work
|
||||
- Infrastructure or data-related tasks
|
||||
|
||||
**Great for**:
|
||||
- API design and implementation
|
||||
- Database schema and optimization
|
||||
- Security implementation
|
||||
- Reliability and error handling
|
||||
- Backend performance tuning
|
||||
|
||||
**Reliability budgets they enforce**:
|
||||
- Uptime: 99.9% (8.7h/year downtime)
|
||||
- Error rate: <0.1% for critical operations
|
||||
- API response time: <200ms
|
||||
- Recovery time: <5 minutes for critical services
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/design user-api --persona-backend
|
||||
/analyze --focus security api/
|
||||
/improve --persona-backend database-layer/
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Rock-solid reliability and uptime
|
||||
- Security by default (zero trust)
|
||||
- Data integrity and consistency
|
||||
- Graceful error handling
|
||||
|
||||
---
|
||||
|
||||
#### 🛡️ `security` - Threat Modeling & Vulnerability Expert
|
||||
**What they do**: Security analysis, threat modeling, vulnerability assessment, compliance
|
||||
|
||||
**Priority**: Security > compliance > reliability > performance > convenience
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "security", "vulnerability", "auth", "compliance"
|
||||
- Security scanning or assessment work
|
||||
- Authentication/authorization tasks
|
||||
|
||||
**Great for**:
|
||||
- Security audits and vulnerability scanning
|
||||
- Threat modeling and risk assessment
|
||||
- Secure coding practices
|
||||
- Compliance requirements (OWASP, etc.)
|
||||
- Authentication and authorization systems
|
||||
|
||||
**Threat assessment levels**:
|
||||
- Critical: Immediate action required
|
||||
- High: Fix within 24 hours
|
||||
- Medium: Fix within 7 days
|
||||
- Low: Fix within 30 days
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/scan --persona-security --focus security
|
||||
/analyze auth-system/ --persona-security
|
||||
/improve --focus security --persona-security
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Security by default, fail-safe mechanisms
|
||||
- Zero trust architecture principles
|
||||
- Defense in depth strategies
|
||||
- Clear security documentation
|
||||
|
||||
---
|
||||
|
||||
#### ⚡ `performance` - Optimization & Bottleneck Specialist
|
||||
**What they do**: Performance optimization, bottleneck identification, metrics analysis
|
||||
|
||||
**Priority**: Measure first > optimize critical path > user experience > avoid premature optimization
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "performance", "optimization", "speed", "bottleneck"
|
||||
- Performance analysis or optimization work
|
||||
- When speed/efficiency is mentioned
|
||||
|
||||
**Great for**:
|
||||
- Performance bottleneck identification
|
||||
- Code optimization with metrics validation
|
||||
- Database query optimization
|
||||
- Frontend performance tuning
|
||||
- Load testing and capacity planning
|
||||
|
||||
**Performance budgets they track**:
|
||||
- API responses: <500ms
|
||||
- Database queries: <100ms
|
||||
- Bundle size: <500KB initial
|
||||
- Memory usage: <100MB mobile, <500MB desktop
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/analyze --focus performance --persona-performance
|
||||
/improve --type performance slow-endpoints/
|
||||
/test --benchmark --persona-performance
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Measurement-driven optimization
|
||||
- Real user experience improvements
|
||||
- Critical path performance
|
||||
- Systematic optimization methodology
|
||||
|
||||
### Process & Quality Experts ✨
|
||||
|
||||
#### 🔍 `analyzer` - Root Cause Investigation Specialist
|
||||
**What they do**: Systematic debugging, root cause analysis, evidence-based investigation
|
||||
|
||||
**Priority**: Evidence > systematic approach > thoroughness > speed
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "analyze", "investigate", "debug", "root cause"
|
||||
- Debugging or troubleshooting sessions
|
||||
- Complex problem investigation
|
||||
|
||||
**Great for**:
|
||||
- Debugging complex issues
|
||||
- Root cause analysis
|
||||
- System investigation
|
||||
- Evidence-based problem solving
|
||||
- Understanding unknown codebases
|
||||
|
||||
**Investigation methodology**:
|
||||
1. Evidence collection before conclusions
|
||||
2. Pattern recognition in data
|
||||
3. Hypothesis testing and validation
|
||||
4. Root cause confirmation through tests
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/troubleshoot "auth randomly fails" --persona-analyzer
|
||||
/analyze --persona-analyzer mysterious-bug/
|
||||
/explain --detailed "why is this slow" --persona-analyzer
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Evidence-based conclusions
|
||||
- Systematic investigation methods
|
||||
- Complete analysis before solutions
|
||||
- Reproducible findings
|
||||
|
||||
---
|
||||
|
||||
#### 🧪 `qa` - Quality Assurance & Testing Expert
|
||||
**What they do**: Testing strategy, quality gates, edge case detection, risk assessment
|
||||
|
||||
**Priority**: Prevention > detection > correction > comprehensive coverage
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "test", "quality", "validation", "coverage"
|
||||
- Testing or quality assurance work
|
||||
- Quality gates or edge cases mentioned
|
||||
|
||||
**Great for**:
|
||||
- Test strategy and planning
|
||||
- Quality assurance processes
|
||||
- Edge case identification
|
||||
- Risk-based testing
|
||||
- Test automation
|
||||
|
||||
**Quality risk assessment**:
|
||||
- Critical path analysis for user journeys
|
||||
- Failure impact evaluation
|
||||
- Defect probability assessment
|
||||
- Recovery difficulty estimation
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/test --persona-qa comprehensive-suite
|
||||
/analyze --focus quality --persona-qa
|
||||
/review --persona-qa critical-features/
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Preventing defects over finding them
|
||||
- Comprehensive test coverage
|
||||
- Risk-based testing priorities
|
||||
- Quality built into the process
|
||||
|
||||
---
|
||||
|
||||
#### 🔄 `refactorer` - Code Quality & Cleanup Specialist
|
||||
**What they do**: Code quality improvement, technical debt management, clean code practices
|
||||
|
||||
**Priority**: Simplicity > maintainability > readability > performance > cleverness
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "refactor", "cleanup", "quality", "technical debt"
|
||||
- Code improvement or cleanup work
|
||||
- Maintainability concerns
|
||||
|
||||
**Great for**:
|
||||
- Code refactoring and cleanup
|
||||
- Technical debt reduction
|
||||
- Code quality improvements
|
||||
- Design pattern application
|
||||
- Legacy code modernization
|
||||
|
||||
**Code quality metrics they track**:
|
||||
- Cyclomatic complexity
|
||||
- Code readability scores
|
||||
- Technical debt ratio
|
||||
- Test coverage
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/improve --type quality --persona-refactorer
|
||||
/cleanup legacy-module/ --persona-refactorer
|
||||
/analyze --focus maintainability --persona-refactorer
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Simple, readable solutions
|
||||
- Consistent patterns and conventions
|
||||
- Maintainable code structure
|
||||
- Technical debt management
|
||||
|
||||
---
|
||||
|
||||
#### 🚀 `devops` - Infrastructure & Deployment Expert
|
||||
**What they do**: Infrastructure automation, deployment, monitoring, reliability engineering
|
||||
|
||||
**Priority**: Automation > observability > reliability > scalability > manual processes
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "deploy", "infrastructure", "CI/CD", "monitoring"
|
||||
- Deployment or infrastructure work
|
||||
- DevOps or automation tasks
|
||||
|
||||
**Great for**:
|
||||
- Deployment automation and CI/CD
|
||||
- Infrastructure as code
|
||||
- Monitoring and alerting setup
|
||||
- Performance monitoring
|
||||
- Container and cloud infrastructure
|
||||
|
||||
**Infrastructure automation priorities**:
|
||||
- Zero-downtime deployments
|
||||
- Automated rollback capabilities
|
||||
- Infrastructure as code
|
||||
- Comprehensive monitoring
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/deploy production --persona-devops
|
||||
/analyze infrastructure/ --persona-devops
|
||||
/improve deployment-pipeline --persona-devops
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Automated over manual processes
|
||||
- Comprehensive observability
|
||||
- Reliable, repeatable deployments
|
||||
- Infrastructure as code practices
|
||||
|
||||
### Knowledge & Communication 📚
|
||||
|
||||
#### 👨🏫 `mentor` - Educational Guidance Specialist
|
||||
**What they do**: Teaching, knowledge transfer, educational explanations, learning facilitation
|
||||
|
||||
**Priority**: Understanding > knowledge transfer > teaching > task completion
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "explain", "learn", "understand", "teach"
|
||||
- Educational or knowledge transfer tasks
|
||||
- Step-by-step guidance requests
|
||||
|
||||
**Great for**:
|
||||
- Learning new technologies
|
||||
- Understanding complex concepts
|
||||
- Code explanations and walkthroughs
|
||||
- Best practices education
|
||||
- Team knowledge sharing
|
||||
|
||||
**Learning optimization approach**:
|
||||
- Skill level assessment
|
||||
- Progressive complexity building
|
||||
- Learning style adaptation
|
||||
- Knowledge retention reinforcement
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/explain React hooks --persona-mentor
|
||||
/document --type guide --persona-mentor
|
||||
/analyze complex-algorithm.js --persona-mentor
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Clear, accessible explanations
|
||||
- Complete conceptual understanding
|
||||
- Engaging learning experiences
|
||||
- Practical skill development
|
||||
|
||||
---
|
||||
|
||||
#### ✍️ `scribe` - Professional Documentation Expert
|
||||
**What they do**: Professional writing, documentation, localization, cultural communication
|
||||
|
||||
**Priority**: Clarity > audience needs > cultural sensitivity > completeness > brevity
|
||||
|
||||
**When they auto-activate**:
|
||||
- Keywords: "document", "write", "guide", "README"
|
||||
- Documentation or writing tasks
|
||||
- Professional communication needs
|
||||
|
||||
**Great for**:
|
||||
- Technical documentation
|
||||
- User guides and tutorials
|
||||
- README files and wikis
|
||||
- API documentation
|
||||
- Professional communications
|
||||
|
||||
**Language support**: English (default), Spanish, French, German, Japanese, Chinese, Portuguese, Italian, Russian, Korean
|
||||
|
||||
**Content types**: Technical docs, user guides, API docs, commit messages, PR descriptions
|
||||
|
||||
**Example workflows**:
|
||||
```bash
|
||||
/document api/ --persona-scribe
|
||||
/git commit --persona-scribe
|
||||
/explain --persona-scribe=es complex-feature
|
||||
```
|
||||
|
||||
**What they prioritize**:
|
||||
- Clear, professional communication
|
||||
- Audience-appropriate language
|
||||
- Cultural sensitivity and adaptation
|
||||
- High writing standards
|
||||
|
||||
## When Each Persona Shines ⭐
|
||||
|
||||
### Development Phase Mapping
|
||||
|
||||
**Planning & Design Phase**:
|
||||
- 🏗️ `architect` - System design and architecture planning
|
||||
- 🎨 `frontend` - UI/UX design and user experience
|
||||
- ✍️ `scribe` - Requirements documentation and specifications
|
||||
|
||||
**Implementation Phase**:
|
||||
- 🎨 `frontend` - UI component development
|
||||
- ⚙️ `backend` - API and service implementation
|
||||
- 🛡️ `security` - Security implementation and hardening
|
||||
|
||||
**Testing & Quality Phase**:
|
||||
- 🧪 `qa` - Test strategy and quality assurance
|
||||
- ⚡ `performance` - Performance testing and optimization
|
||||
- 🔍 `analyzer` - Bug investigation and root cause analysis
|
||||
|
||||
**Maintenance & Improvement Phase**:
|
||||
- 🔄 `refactorer` - Code cleanup and refactoring
|
||||
- ⚡ `performance` - Performance optimization
|
||||
- 👨🏫 `mentor` - Knowledge transfer and documentation
|
||||
|
||||
**Deployment & Operations Phase**:
|
||||
- 🚀 `devops` - Deployment automation and infrastructure
|
||||
- 🛡️ `security` - Security monitoring and compliance
|
||||
- ✍️ `scribe` - Operations documentation and runbooks
|
||||
|
||||
### Problem Type Mapping
|
||||
|
||||
**"My code is slow"** → ⚡ `performance`
|
||||
**"Something's broken and I don't know why"** → 🔍 `analyzer`
|
||||
**"Need to design a new system"** → 🏗️ `architect`
|
||||
**"UI looks terrible"** → 🎨 `frontend`
|
||||
**"Is this secure?"** → 🛡️ `security`
|
||||
**"Code is messy"** → 🔄 `refactorer`
|
||||
**"Need better tests"** → 🧪 `qa`
|
||||
**"Deployment keeps failing"** → 🚀 `devops`
|
||||
**"I don't understand this"** → 👨🏫 `mentor`
|
||||
**"Need documentation"** → ✍️ `scribe`
|
||||
|
||||
## Persona Combinations 🤝
|
||||
|
||||
Personas often work together automatically. Here are common collaboration patterns:
|
||||
|
||||
### Design & Implementation
|
||||
```bash
|
||||
/design user-dashboard
|
||||
# Auto-activates: 🏗️ architect (system design) + 🎨 frontend (UI design)
|
||||
```
|
||||
|
||||
### Security Review
|
||||
```bash
|
||||
/analyze --focus security api/
|
||||
# Auto-activates: 🛡️ security (primary) + ⚙️ backend (API expertise)
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
```bash
|
||||
/improve --focus performance slow-app/
|
||||
# Auto-activates: ⚡ performance (primary) + 🎨 frontend (if UI) or ⚙️ backend (if API)
|
||||
```
|
||||
|
||||
### Quality Improvement
|
||||
```bash
|
||||
/improve --focus quality legacy-code/
|
||||
# Auto-activates: 🔄 refactorer (primary) + 🧪 qa (testing) + 🏗️ architect (design)
|
||||
```
|
||||
|
||||
### Documentation & Learning
|
||||
```bash
|
||||
/document complex-feature --type guide
|
||||
# Auto-activates: ✍️ scribe (writing) + 👨🏫 mentor (educational approach)
|
||||
```
|
||||
|
||||
## Practical Examples 💡
|
||||
|
||||
### Before/After: Generic vs Persona-Specific
|
||||
|
||||
**Before** (generic):
|
||||
```bash
|
||||
/analyze auth.js
|
||||
# → Basic analysis, generic advice
|
||||
```
|
||||
|
||||
**After** (security persona):
|
||||
```bash
|
||||
/analyze auth.js --persona-security
|
||||
# → Security-focused analysis
|
||||
# → Threat modeling perspective
|
||||
# → OWASP compliance checking
|
||||
# → Vulnerability pattern detection
|
||||
```
|
||||
|
||||
### Auto-Activation in Action
|
||||
|
||||
**Frontend work detection**:
|
||||
```bash
|
||||
/build react-components/
|
||||
# Auto-activates: 🎨 frontend
|
||||
# → UI-focused build optimization
|
||||
# → Accessibility checking
|
||||
# → Performance budgets
|
||||
# → Bundle size analysis
|
||||
```
|
||||
|
||||
**Complex debugging**:
|
||||
```bash
|
||||
/troubleshoot "payment processing randomly fails"
|
||||
# Auto-activates: 🔍 analyzer
|
||||
# → Systematic investigation approach
|
||||
# → Evidence collection methodology
|
||||
# → Pattern analysis
|
||||
# → Root cause identification
|
||||
```
|
||||
|
||||
### Manual Override Examples
|
||||
|
||||
**Force security perspective**:
|
||||
```bash
|
||||
/analyze react-app/ --persona-security
|
||||
# Even though it's frontend code, analyze from security perspective
|
||||
# → XSS vulnerability checking
|
||||
# → Authentication flow analysis
|
||||
# → Data exposure risks
|
||||
```
|
||||
|
||||
**Get architectural advice on small changes**:
|
||||
```bash
|
||||
/improve small-utility.js --persona-architect
|
||||
# Apply architectural thinking to small code
|
||||
# → Design pattern opportunities
|
||||
# → Future extensibility
|
||||
# → Coupling analysis
|
||||
```
|
||||
|
||||
## Advanced Usage 🚀
|
||||
|
||||
### Manual Persona Control
|
||||
|
||||
**When to override auto-activation**:
|
||||
- You want a different perspective on the same problem
|
||||
- Auto-activation chose wrong persona for your specific needs
|
||||
- You're learning and want to see how different experts approach problems
|
||||
|
||||
**How to override**:
|
||||
```bash
|
||||
# Explicit persona selection
|
||||
/analyze frontend-code/ --persona-security # Security view of frontend
|
||||
/improve backend-api/ --persona-performance # Performance view of backend
|
||||
|
||||
# Multiple persona flags (last one wins)
|
||||
/analyze --persona-frontend --persona-security # Uses security persona
|
||||
```
|
||||
|
||||
### Persona-Specific Flags and Settings
|
||||
|
||||
**Security persona + validation**:
|
||||
```bash
|
||||
/analyze --persona-security --focus security --validate
|
||||
# → Maximum security focus with validation
|
||||
```
|
||||
|
||||
**Performance persona + benchmarking**:
|
||||
```bash
|
||||
/test --persona-performance --benchmark --focus performance
|
||||
# → Performance-focused testing with metrics
|
||||
```
|
||||
|
||||
**Mentor persona + detailed explanations**:
|
||||
```bash
|
||||
/explain complex-concept --persona-mentor --verbose
|
||||
# → Educational explanation with full detail
|
||||
```
|
||||
|
||||
### Cross-Domain Expertise
|
||||
|
||||
**When you need multiple perspectives**:
|
||||
```bash
|
||||
# Sequential analysis with different personas
|
||||
/analyze --persona-security api/auth.js
|
||||
/analyze --persona-performance api/auth.js
|
||||
/analyze --persona-refactorer api/auth.js
|
||||
|
||||
# Or let SuperClaude coordinate automatically
|
||||
/analyze --focus quality api/auth.js
|
||||
# Auto-coordinates: security + performance + refactorer insights
|
||||
```
|
||||
|
||||
## Common Workflows by Persona 💼
|
||||
|
||||
### 🏗️ Architect Workflows
|
||||
```bash
|
||||
# System design
|
||||
/design microservices-architecture --persona-architect
|
||||
/estimate "migrate monolith to microservices" --persona-architect
|
||||
|
||||
# Architecture review
|
||||
/analyze --focus architecture --persona-architect large-system/
|
||||
/review --persona-architect critical-components/
|
||||
```
|
||||
|
||||
### 🎨 Frontend Workflows
|
||||
```bash
|
||||
# Component development
|
||||
/build dashboard-components/ --persona-frontend
|
||||
/improve --focus accessibility --persona-frontend ui/
|
||||
|
||||
# Performance optimization
|
||||
/analyze --focus performance --persona-frontend bundle/
|
||||
/test --persona-frontend --focus performance
|
||||
```
|
||||
|
||||
### ⚙️ Backend Workflows
|
||||
```bash
|
||||
# API development
|
||||
/design rest-api --persona-backend
|
||||
/build api-endpoints/ --persona-backend
|
||||
|
||||
# Reliability improvements
|
||||
/improve --focus reliability --persona-backend services/
|
||||
/analyze --persona-backend --focus security api/
|
||||
```
|
||||
|
||||
### 🛡️ Security Workflows
|
||||
```bash
|
||||
# Security assessment
|
||||
/scan --persona-security --focus security entire-app/
|
||||
/analyze --persona-security auth-flow/
|
||||
|
||||
# Vulnerability fixing
|
||||
/improve --focus security --persona-security vulnerable-code/
|
||||
/review --persona-security --focus security critical-paths/
|
||||
```
|
||||
|
||||
### 🔍 Analyzer Workflows
|
||||
```bash
|
||||
# Bug investigation
|
||||
/troubleshoot "intermittent failures" --persona-analyzer
|
||||
/analyze --persona-analyzer --focus debugging problem-area/
|
||||
|
||||
# System understanding
|
||||
/explain --persona-analyzer complex-system/
|
||||
/load --persona-analyzer unfamiliar-codebase/
|
||||
```
|
||||
|
||||
## Quick Reference 📋
|
||||
|
||||
### Persona Cheat Sheet
|
||||
|
||||
| Persona | Best For | Auto-Activates On | Manual Flag |
|
||||
|---------|----------|-------------------|-------------|
|
||||
| 🏗️ architect | System design, architecture | "architecture", "design", "scalability" | `--persona-architect` |
|
||||
| 🎨 frontend | UI/UX, accessibility | "component", "responsive", "UI" | `--persona-frontend` |
|
||||
| ⚙️ backend | APIs, databases, reliability | "API", "database", "service" | `--persona-backend` |
|
||||
| 🛡️ security | Security, compliance | "security", "vulnerability", "auth" | `--persona-security` |
|
||||
| ⚡ performance | Optimization, speed | "performance", "optimization", "slow" | `--persona-performance` |
|
||||
| 🔍 analyzer | Debugging, investigation | "analyze", "debug", "investigate" | `--persona-analyzer` |
|
||||
| 🧪 qa | Testing, quality | "test", "quality", "validation" | `--persona-qa` |
|
||||
| 🔄 refactorer | Code cleanup, refactoring | "refactor", "cleanup", "quality" | `--persona-refactorer` |
|
||||
| 🚀 devops | Deployment, infrastructure | "deploy", "infrastructure", "CI/CD" | `--persona-devops` |
|
||||
| 👨🏫 mentor | Learning, explanation | "explain", "learn", "understand" | `--persona-mentor` |
|
||||
| ✍️ scribe | Documentation, writing | "document", "write", "guide" | `--persona-scribe` |
|
||||
|
||||
### Most Useful Combinations
|
||||
|
||||
**Security-focused development**:
|
||||
```bash
|
||||
--persona-security --focus security --validate
|
||||
```
|
||||
|
||||
**Performance optimization**:
|
||||
```bash
|
||||
--persona-performance --focus performance --benchmark
|
||||
```
|
||||
|
||||
**Learning and understanding**:
|
||||
```bash
|
||||
--persona-mentor --verbose --explain
|
||||
```
|
||||
|
||||
**Quality improvement**:
|
||||
```bash
|
||||
--persona-refactorer --focus quality --safe-mode
|
||||
```
|
||||
|
||||
**Professional documentation**:
|
||||
```bash
|
||||
--persona-scribe --type guide --detailed
|
||||
```
|
||||
|
||||
### Auto-Activation Triggers
|
||||
|
||||
**High confidence triggers** (90%+ activation):
|
||||
- "security audit" → 🛡️ security
|
||||
- "UI component" → 🎨 frontend
|
||||
- "API design" → ⚙️ backend
|
||||
- "system architecture" → 🏗️ architect
|
||||
- "debug issue" → 🔍 analyzer
|
||||
|
||||
**Medium confidence triggers** (70-90% activation):
|
||||
- "improve performance" → ⚡ performance
|
||||
- "write tests" → 🧪 qa
|
||||
- "clean up code" → 🔄 refactorer
|
||||
- "deployment issue" → 🚀 devops
|
||||
|
||||
**Context-dependent triggers** (varies):
|
||||
- "document this" → ✍️ scribe or 👨🏫 mentor (depends on audience)
|
||||
- "analyze this" → 🔍 analyzer, 🏗️ architect, or domain specialist (depends on content)
|
||||
|
||||
## Troubleshooting Persona Issues 🚨
|
||||
|
||||
### Common Problems
|
||||
|
||||
**"Wrong persona activated"**
|
||||
- Use explicit persona flags: `--persona-security`
|
||||
- Check if your keywords triggered auto-activation
|
||||
- Try more specific language in your request
|
||||
|
||||
**"Persona doesn't seem to work"**
|
||||
- Verify persona name spelling: `--persona-frontend` not `--persona-fronted`
|
||||
- Some personas work better with specific commands
|
||||
- Try combining with relevant flags: `--focus security --persona-security`
|
||||
|
||||
**"Want multiple perspectives"**
|
||||
- Run same command with different personas manually
|
||||
- Use broader focus flags: `--focus quality` (activates multiple personas)
|
||||
- Let SuperClaude coordinate automatically with complex requests
|
||||
|
||||
**"Persona is too focused"**
|
||||
- Try a different persona that's more general
|
||||
- Use mentor persona for broader explanations
|
||||
- Combine with `--verbose` for more context
|
||||
|
||||
### When to Override Auto-Activation
|
||||
|
||||
**Override when**:
|
||||
- Auto-activation chose the wrong specialist
|
||||
- You want to learn from a different perspective
|
||||
- Working outside typical domain boundaries
|
||||
- Need specific expertise for edge cases
|
||||
|
||||
**How to override effectively**:
|
||||
```bash
|
||||
# Force specific perspective
|
||||
/analyze frontend-code/ --persona-security # Security view of frontend
|
||||
|
||||
# Combine multiple perspectives
|
||||
/analyze api/ --persona-security
|
||||
/analyze api/ --persona-performance # Run separately for different views
|
||||
|
||||
# Use general analysis
|
||||
/analyze --no-persona # Disable persona auto-activation
|
||||
```
|
||||
|
||||
## Tips for Effective Persona Usage 💡
|
||||
|
||||
### Getting Started
|
||||
1. **Let auto-activation work** - It's usually right
|
||||
2. **Try manual activation** - Experiment with `--persona-*` flags
|
||||
3. **Watch the differences** - See how different personas approach the same problem
|
||||
4. **Use appropriate commands** - Some personas work better with specific commands
|
||||
|
||||
### Getting Advanced
|
||||
1. **Learn persona priorities** - Understand what each values most
|
||||
2. **Use persona combinations** - Different perspectives on complex problems
|
||||
3. **Override when needed** - Don't be afraid to choose different personas
|
||||
4. **Match personas to phases** - Use different personas for different project phases
|
||||
|
||||
### Best Practices
|
||||
- **Match persona to problem type** - Security persona for security issues
|
||||
- **Consider project phase** - Architect for planning, QA for testing
|
||||
- **Use multiple perspectives** - Complex problems benefit from multiple viewpoints
|
||||
- **Trust auto-activation** - It learns from patterns and usually gets it right
|
||||
|
||||
---
|
||||
|
||||
## Final Notes 📝
|
||||
|
||||
**Remember:**
|
||||
- Personas are like having specialists on your team
|
||||
- Auto-activation works well, but manual control gives you flexibility
|
||||
- Different personas have different priorities and perspectives
|
||||
- Complex problems often benefit from multiple personas
|
||||
|
||||
**Still evolving:**
|
||||
- Persona auto-activation is getting smarter over time
|
||||
- Collaboration patterns between personas are improving
|
||||
- New specialized knowledge is being added regularly
|
||||
|
||||
**When in doubt:**
|
||||
- Let auto-activation do its thing first
|
||||
- Try the mentor persona for learning and understanding
|
||||
- Use specific personas when you know what expertise you need
|
||||
- Experiment with different personas on the same problem
|
||||
|
||||
**Happy persona-ing!** 🎭 Having specialists available makes development so much more effective when you know how to work with them.
|
||||
|
||||
---
|
||||
|
||||
*It's like having a whole development team in your pocket - just way less coffee consumption! ☕*
|
||||
2985
Docs/superclaude-user-guide.md
Normal file
2985
Docs/superclaude-user-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user