mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
9e685b7326
* ✨ Enhance documentation with advanced markdown formatting Major improvements to documentation presentation and usability: README.md: - Added centered hero section with framework statistics dashboard - Created visual support section with donation cards - Enhanced What's New section with feature grid layout - Reorganized documentation links into categorized table - Added professional badges and visual separators installation.md: - Centered title with platform badges and quick navigation - Consolidated 4 installation methods into unified table - Created visual requirement cards (Required vs Optional) - Added collapsible troubleshooting sections - Removed 3 duplicate "What's Next" sections - Enhanced learning journey with progression tables quick-start.md: - Added visual framework architecture flow diagram - Created component statistics dashboard (21|14|6|6) - Built comparison table for SuperClaude vs Standard Claude - Added 4-week learning timeline with milestones - Enhanced workflow patterns with step-by-step tables - Created key insights cards explaining framework philosophy All documents now feature consistent styling with centered titles, organized tables, emojis for visual scanning, and improved navigation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * 🔥 Remove outdated publishing and release instruction files Cleaned up repository by removing: - PUBLISHING.md: Outdated publishing guidelines - RELEASE_INSTRUCTIONS.md: Old release process documentation These files are no longer needed as the project has evolved and the processes have been streamlined or moved elsewhere. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * 🐛 Fix component validation to check metadata file instead of settings.json Resolves #291 - Validation errors after V4 upgrade ## Changes - Fixed validation logic to check .superclaude-metadata.json instead of settings.json - Standardized all component versions to 4.0.4 across the framework - Fixed agent validation to check for correct filenames (architect vs specialist/engineer) - Cleaned up metadata file structure for consistency ## Technical Details The issue was caused by components registering in .superclaude-metadata.json but validation checking settings.json for component registration. This mismatch caused false validation errors even though components were properly installed. ## Testing All components now validate successfully with the corrected logic. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * 🔖 Bump version to 4.0.6 across entire project ## Summary Comprehensive version update from 4.0.4 to 4.0.6 with validation fixes ## Changes - Updated VERSION file, pyproject.toml, and package.json - Updated all Python __version__ declarations (8 occurrences) - Updated all component metadata versions (6 components, 25+ occurrences) - Updated documentation and README version badges (11 files) - Fixed package.json inconsistency (was 4.0.5) - Updated legacy backup.py version reference (was 3.0.0) - Added CHANGELOG entry for version 4.0.6 ## Files Modified (26 total) - Core: VERSION, pyproject.toml, package.json - Python: SuperClaude/__init__.py, __main__.py, setup/__init__.py, cli/base.py - Components: core.py, commands.py, agents.py, mcp.py, mcp_docs.py, modes.py - Docs: README.md, CONTRIBUTING.md, SECURITY.md, installation.md, quick-start.md - Config: features.json, backup.py, update.py - User: ~/.claude/.superclaude-metadata.json ## Verification All version references now consistently show 4.0.6 Historical references in CHANGELOG preserved as intended 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * 📝 Update README.md installation instructions --------- Signed-off-by: NomenAK <39598727+NomenAK@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
124 lines
2.9 KiB
Markdown
124 lines
2.9 KiB
Markdown
# SuperClaude Troubleshooting Guide 🔧
|
|
|
|
Quick fixes to advanced diagnostics for SuperClaude Framework issues.
|
|
|
|
## Quick Fixes (90% of problems)
|
|
|
|
**Installation Verification:**
|
|
```bash
|
|
python3 -m SuperClaude --version # Should show 4.0.6
|
|
SuperClaude install --list-components
|
|
```
|
|
|
|
**Command Issues:**
|
|
```bash
|
|
# Test in Claude Code:
|
|
/sc:brainstorm "test project" # Should ask discovery questions
|
|
|
|
# If no response: Restart Claude Code session
|
|
```
|
|
|
|
**Resolution Checklist:**
|
|
- [ ] Version commands work and show 4.0.6
|
|
- [ ] `/sc:` commands respond in Claude Code
|
|
- [ ] MCP servers listed: `SuperClaude install --list-components | grep mcp`
|
|
|
|
## Common Issues
|
|
|
|
### Installation Problems
|
|
|
|
**Package Installation Fails:**
|
|
```bash
|
|
# For pipx users
|
|
pipx uninstall SuperClaude
|
|
pipx install SuperClaude
|
|
|
|
# For pip users
|
|
pip uninstall SuperClaude
|
|
pip install --upgrade pip
|
|
pip install SuperClaude
|
|
```
|
|
|
|
**Permission Denied / PEP 668 Error:**
|
|
```bash
|
|
# Option 1: Use pipx (recommended)
|
|
pipx install SuperClaude
|
|
|
|
# Option 2: Use pip with --user flag
|
|
pip install --user SuperClaude
|
|
|
|
# Option 3: Fix permissions
|
|
sudo chown -R $USER ~/.claude
|
|
|
|
# Option 4: Force installation (use with caution)
|
|
pip install --break-system-packages SuperClaude
|
|
```
|
|
|
|
**Component Missing:**
|
|
```bash
|
|
python3 -m SuperClaude install --components core commands agents modes --force
|
|
```
|
|
|
|
### Command Issues
|
|
|
|
**Commands Not Recognized:**
|
|
1. Restart Claude Code completely
|
|
2. Verify: `python3 -m SuperClaude --version`
|
|
3. Test: `/sc:brainstorm "test"`
|
|
|
|
**Agents Not Activating:**
|
|
- Use specific keywords: `/sc:implement "secure JWT authentication"`
|
|
- Manual activation: `@agent-security "review auth code"`
|
|
|
|
**Slow Performance:**
|
|
```bash
|
|
/sc:analyze . --no-mcp # Test without MCP servers
|
|
/sc:analyze src/ --scope file # Limit scope
|
|
```
|
|
|
|
### MCP Server Issues
|
|
|
|
**Server Connection Fails:**
|
|
```bash
|
|
ls ~/.claude/.claude.json # Check config exists
|
|
node --version # Verify Node.js 16+
|
|
SuperClaude install --components mcp --force
|
|
```
|
|
|
|
**API Key Required (Magic/Morphllm):**
|
|
```bash
|
|
export TWENTYFIRST_API_KEY="your_key"
|
|
export MORPH_API_KEY="your_key"
|
|
# Or use: /sc:command --no-mcp
|
|
```
|
|
|
|
## Advanced Diagnostics
|
|
|
|
**System Analysis:**
|
|
```bash
|
|
SuperClaude install --diagnose
|
|
cat ~/.claude/logs/superclaude.log | tail -50
|
|
```
|
|
|
|
**Component Analysis:**
|
|
```bash
|
|
ls -la ~/.claude/ # Check installed files
|
|
grep -r "@" ~/.claude/CLAUDE.md # Verify imports
|
|
```
|
|
|
|
**Reset Installation:**
|
|
```bash
|
|
SuperClaude backup --create # Backup first
|
|
SuperClaude uninstall
|
|
SuperClaude install --fresh
|
|
```
|
|
|
|
## Get Help
|
|
|
|
**Documentation:**
|
|
- [Installation Guide](../Getting-Started/installation.md) - Setup issues
|
|
- [Commands Guide](../User-Guide/commands.md) - Usage issues
|
|
|
|
**Community:**
|
|
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
|
- Include: OS, Python version, error message, steps to reproduce |