mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
📚 Major documentation cleanup: Fix CLI confusion and streamline content
## 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
127
Docs/README.md
Normal file
127
Docs/README.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# SuperClaude Documentation
|
||||
|
||||
## 🎯 Essential Understanding
|
||||
|
||||
**SuperClaude is a Context Framework for Claude Code** - it installs behavioral instruction files that Claude Code reads to enhance its capabilities.
|
||||
|
||||
### How It Works
|
||||
1. **Installation**: Python CLI installs context files to `~/.claude/`
|
||||
2. **Commands**: Type `/sc:analyze` → Claude Code reads `analyze.md` instruction file
|
||||
3. **Behavior**: Claude adopts behaviors defined in context files
|
||||
4. **Result**: Enhanced development workflows through context switching
|
||||
|
||||
## 🚀 Quick Start (5 Minutes)
|
||||
|
||||
**New Users**: [Quick Start Guide →](Getting-Started/quick-start.md)
|
||||
```bash
|
||||
pip install SuperClaude && SuperClaude install
|
||||
# Then try: /sc:brainstorm "web app idea" in Claude Code
|
||||
```
|
||||
|
||||
**Having Issues**: [Quick Fixes →](Reference/common-issues.md) | [Troubleshooting →](Reference/troubleshooting.md)
|
||||
|
||||
## 📚 Documentation Structure
|
||||
|
||||
### 🌱 Start Here (New Users)
|
||||
| Guide | Purpose | Time |
|
||||
|-------|---------|------|
|
||||
| **[Quick Start](Getting-Started/quick-start.md)** | 5-minute setup and first commands | 5 min |
|
||||
| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions | 10 min |
|
||||
| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands | 20 min |
|
||||
|
||||
### 🌿 Daily Usage (Regular Users)
|
||||
| Guide | Purpose | Use For |
|
||||
|-------|---------|---------|
|
||||
| **[Commands Guide](User-Guide/commands.md)** | Master all `/sc:` commands | Daily development |
|
||||
| **[Agents Guide](User-Guide/agents.md)** | 15 domain specialists (`@agents-*`) | Expert assistance |
|
||||
| **[Flags Guide](User-Guide/flags.md)** | Command behavior modification | Optimization |
|
||||
| **[Modes Guide](User-Guide/modes.md)** | 6 behavioral modes | Workflow optimization |
|
||||
|
||||
### 🌲 Reference & Advanced (Power Users)
|
||||
| Guide | Purpose | Use For |
|
||||
|-------|---------|---------|
|
||||
| **[Troubleshooting](Reference/troubleshooting.md)** | Problem resolution | When things break |
|
||||
| **[Examples Cookbook](Reference/examples-cookbook.md)** | Practical usage patterns | Learning workflows |
|
||||
| **[MCP Servers](User-Guide/mcp-servers.md)** | 6 enhanced capabilities | Advanced features |
|
||||
|
||||
### 🔧 Development & Contributing
|
||||
| Guide | Purpose | Audience |
|
||||
|-------|---------|----------|
|
||||
| **[Technical Architecture](Developer-Guide/technical-architecture.md)** | System design | Contributors |
|
||||
| **[Contributing](Developer-Guide/contributing-code.md)** | Development workflow | Developers |
|
||||
|
||||
## 🔑 Key Concepts
|
||||
|
||||
### What Gets Installed
|
||||
- **Python CLI Tool** - Manages framework installation
|
||||
- **Context Files** - `.md` behavioral instructions in `~/.claude/`
|
||||
- **MCP Configurations** - Optional external tool settings
|
||||
|
||||
### Framework Components
|
||||
- **21 Commands** (`/sc:*`) - Workflow automation patterns
|
||||
- **15 Agents** (`@agents-*`) - Domain specialists
|
||||
- **6 Modes** - Behavioral modification patterns
|
||||
- **6 MCP Servers** - Optional external tools
|
||||
|
||||
## 🚀 Quick Command Reference
|
||||
|
||||
### In Your Terminal (Installation)
|
||||
```bash
|
||||
pip install SuperClaude # Install framework
|
||||
SuperClaude install # Configure Claude Code
|
||||
SuperClaude update # Update framework
|
||||
python3 -m SuperClaude --version # Check installation
|
||||
```
|
||||
|
||||
### In Claude Code (Usage)
|
||||
```bash
|
||||
/sc:brainstorm "project idea" # Start new project
|
||||
/sc:implement "feature" # Build features
|
||||
/sc:analyze src/ # Analyze code
|
||||
@agents-python-expert "optimize this" # Manual specialist
|
||||
@agents-security "review authentication" # Security review
|
||||
```
|
||||
|
||||
## 📊 Framework vs Software Comparison
|
||||
|
||||
| Component | Type | Where It Runs | What It Does |
|
||||
|-----------|------|---------------|--------------|
|
||||
| **SuperClaude Framework** | Context Files | Read by Claude Code | Modifies AI behavior |
|
||||
| **Claude Code** | Software | Your computer | Executes everything |
|
||||
| **MCP Servers** | Software | Node.js processes | Provide tools |
|
||||
| **Python CLI** | Software | Python runtime | Manages installation |
|
||||
|
||||
## 🔄 How Everything Connects
|
||||
|
||||
```
|
||||
User Input → Claude Code → Reads SuperClaude Context → Modified Behavior → Enhanced Output
|
||||
↓
|
||||
May use MCP Servers
|
||||
(if configured)
|
||||
```
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
**Quick Issues** (< 2 min): [Common Issues →](Reference/common-issues.md)
|
||||
**Complex Problems**: [Full Troubleshooting Guide →](Reference/troubleshooting.md)
|
||||
**Installation Issues**: [Installation Guide →](Getting-Started/installation.md)
|
||||
**Command Help**: [Commands Guide →](User-Guide/commands.md)
|
||||
**Community Support**: [GitHub Discussions](https://github.com/SuperClaude-Org/SuperClaude_Framework/discussions)
|
||||
|
||||
## 🤔 Common Misconceptions Clarified
|
||||
|
||||
❌ **"SuperClaude is an AI assistant"**
|
||||
✅ SuperClaude is a configuration framework that enhances Claude Code
|
||||
|
||||
❌ **"I'm running SuperClaude"**
|
||||
✅ You're running Claude Code with SuperClaude context loaded
|
||||
|
||||
❌ **"Claude Code executes; SuperClaude provides context my commands"**
|
||||
✅ Claude Code executes everything; SuperClaude provides the instructions
|
||||
|
||||
❌ **"The .md files are documentation"**
|
||||
✅ The .md files ARE the framework - active instruction sets
|
||||
|
||||
---
|
||||
|
||||
*Remember: SuperClaude enhances Claude Code through context - it doesn't replace it or run alongside it. Everything happens within Claude Code itself.*
|
||||
Reference in New Issue
Block a user