mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 09:46:06 +00:00

refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434 )

* refactor(docs): rename directories to lowercase for PEP8 compliance

- Developer-Guide → developer-guide
- Getting-Started → getting-started
- Reference → reference
- Templates → templates
- User-Guide → user-guide
- User-Guide-jp → user-guide-jp
- User-Guide-kr → user-guide-kr
- User-Guide-zh → user-guide-zh

This change aligns with Python PEP8 package naming conventions.
All 43 files affected.

* refactor: rename root documentation files to lowercase

- CHANGELOG.md → changelog.md
- CODE_OF_CONDUCT.md → code_of_conduct.md
- CONTRIBUTING.md → contributing.md
- SECURITY.md → security.md

Aligns with Python package naming conventions (PEP8).
README files remain uppercase as per convention.

* refactor: move documentation files to docs/ for cleaner root

Moved OSS standard files to docs/:
- CHANGELOG.md → docs/CHANGELOG.md
- CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md
- CONTRIBUTING.md → docs/CONTRIBUTING.md
- SECURITY.md → docs/SECURITY.md

Root now contains only essential files:
✓ README files (表紙: en, ja, kr, zh)
✓ LICENSE (法的要件)
✓ Build configs (pyproject.toml, setup.py, MANIFEST.in)
✓ VERSION

Rationale:
Cleaner root structure following modern Python project conventions.
All detailed documentation consolidated in docs/ directory.

* refactor: update documentation links after restructure

Auto-updated internal documentation links to reflect new structure:
- docs/ subdirectories now lowercase (PEP8)
- Root files moved to docs/
- All cross-references updated

This commit includes linter-generated link updates.

* chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY)

* chore(docs): remove duplicated PR docs from repo root (moved under docs)

* docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity

* docs: update links to PM_AGENT.md after rename

---------

Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>

2025-10-15 21:07:39 +05:30

2.9 KiB

Raw Blame History

SuperClaude Troubleshooting Guide 🔧

Quick fixes to advanced diagnostics for SuperClaude Framework issues.

Quick Fixes (90% of problems)

Installation Verification:

python3 -m SuperClaude --version    # Should show 4.1.5
SuperClaude install --list-components

Command Issues:

# 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.1.5
/sc: commands respond in Claude Code
MCP servers listed: SuperClaude install --list-components | grep mcp

Common Issues

Installation Problems

Package Installation Fails:

# 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:

# 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:

python3 -m SuperClaude install --components core commands agents modes --force

Command Issues

Commands Not Recognized:

Restart Claude Code completely
Verify: python3 -m SuperClaude --version
Test: /sc:brainstorm "test"

Agents Not Activating:

Use specific keywords: /sc:implement "secure JWT authentication"
Manual activation: @agent-security "review auth code"

Slow Performance:

/sc:analyze . --no-mcp               # Test without MCP servers
/sc:analyze src/ --scope file        # Limit scope

MCP Server Issues

Server Connection Fails:

ls ~/.claude/.claude.json            # Check config exists
node --version                       # Verify Node.js 16+
SuperClaude install --components mcp --force

API Key Required (Magic/Morphllm):

export TWENTYFIRST_API_KEY="your_key"
export MORPH_API_KEY="your_key"
# Or use: /sc:command --no-mcp

Advanced Diagnostics

System Analysis:

SuperClaude install --diagnose
cat ~/.claude/logs/superclaude.log | tail -50

Component Analysis:

ls -la ~/.claude/                    # Check installed files
grep -r "@" ~/.claude/CLAUDE.md      # Verify imports

Reset Installation:

SuperClaude backup --create          # Backup first
SuperClaude uninstall
SuperClaude install --fresh

Get Help

Documentation:

Installation Guide - Setup issues
Commands Guide - Usage issues

Community:

GitHub Issues
Include: OS, Python version, error message, steps to reproduce

2.9 KiB Raw Blame History