Update installation scripts and documentation

- Enhanced install.sh with better error handling and multi-shell support
- Updated configuration files (CLAUDE.md, MCP.md, RULES.md) to latest version
- Added comprehensive CONTRIBUTING.md guidelines
- Improved README.md formatting and clarity
- Fixed Commands_Cheat_Sheet.md formatting
- Updated .gitignore with better exclusions
- Minor LICENSE and CHANGELOG.md updates

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

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -11,13 +11,26 @@ logs/
 # System files
 .DS_Store
 Thumbs.db
+desktop.ini
+.Spotlight-V100
+.Trashes
 
 # IDE files
 .vscode/
 .idea/
 *.swp
 *.swo
+*~
+.project
+.settings/
 
 # Temporary files
 *.tmp
-*.temp
+*.temp
+*.bak
+*.backup
+*.old
+.cache/
+
+# Backup files from install script
+superclaude-backup.*

CHANGELOG.md

@@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - GitHub issue & PR templates
 - Contributing guidelines
 
-## [4.0.0] - 2025-06-22
+## [4.0.0] - 2024-06-22
 ### Added
 - **Core Configuration Framework**
   - CLAUDE.md → Main cfg + ops rules

CLAUDE.md

@@ -1,14 +1,14 @@
 # CLAUDE.md - SuperClaude Cfg
 
-## Legend  
+## Legend
 | Symbol | Meaning | | Abbrev | Meaning |
 |--------|---------|---|--------|---------|
 | → | leads to | | cfg | configuration |
 | & | and/with | | docs | documentation |
 | > | greater than | | ops | operations |
 
-@RULES.md 
+@RULES.md
-@MCP.md 
+@MCP.md
 @PERSONAS.md
 
 ## Core Cfg
@@ -26,7 +26,7 @@ Commands: /user:<command> [flags] | /task:<action> | Ex: /user:build --init
 ```yaml
 Activation: Natural language OR command flags
 Flags: --think | --think-hard | --ultrathink
-none: Single file|Basic | think: Multi-file|Standard  
+none: Single file|Basic | think: Multi-file|Standard
 think hard: Architecture|Complex | ultrathink: Redesign|Critical
 Examples: /user:analyze --code --think | /user:design --api --ultrathink
 ```

CONTRIBUTING.md

@@ -195,6 +195,18 @@ Description & purpose
 - Use discussions for questions
 - Tag maintainers for urgent issues
 
+## Developer Certificate of Origin (DCO)
+
+By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.
+
+The DCO is legally binding statement that assures contributors have the right to submit their work under the project's license. All commits must be signed off with:
+
+```
+git commit -s -m "Your commit message"
+```
+
+This adds a `Signed-off-by` line to your commit message.
+
 ## Recognition
 
 Contributors are recognized through:
@@ -203,6 +215,9 @@ Contributors are recognized through:
 - Issue/PR acknowledgments
 - Community discussions
 
+### Notable Contributors
+- @amgiiine - Commands Cheat Sheet and documentation improvements
+
 ---
 
 **Ready to contribute?** Create an issue or submit a PR!

Commands_Cheat_Sheet.md

@@ -4,7 +4,7 @@
 
 ### `/user:analyze` - Multi-dimensional code analysis
 - `--code` - Code quality review
-- `--arch` - Architecture analysis  
+- `--arch` - Architecture analysis
 - `--profile` - Performance profiling
 - `--security` - Security assessment
 - `--perf` - Performance bottlenecks
@@ -158,5 +158,3 @@
 - Documentation: `/docs/[category]/`
 
 Version: SuperClaude v4.0.0
-
-Credit @amgiiine

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 NomenAK
+Copyright (c) 2024 NomenAK
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MCP.md

@@ -20,10 +20,10 @@ User Triggers (no flags):
   "need button/form/component" → Magic(builder) → integrate
   "why slow/broken" → Sequential(analysis) → impl fix
   "design architecture" → Sequential(system design) → C7(patterns)
-  
+
 Context Triggers (flags override):
   Import errors → C7(resolve-library-id) → verify docs
-  Complex debugging → Sequential(root cause) → native impl  
+  Complex debugging → Sequential(root cause) → native impl
   UI requests → Magic(builder/refiner) → Puppeteer(test)
   Perf issues → Sequential(analysis) → optimize impl
 
@@ -33,7 +33,7 @@ Research-First (shared/research-first.yml):
   API integration → WebSearch REQUIRED for official docs
   Unknown pattern → Sequential thinking + research REQUIRED
   Confidence < 90% → Impl BLOCKED until research complete
-  
+
 Task Complexity:
   Simple queries → Native tools only (unless flagged)
   Lib questions → C7 progressive loading (or --c7)
@@ -69,7 +69,7 @@ UltraCompressed: --uc flag|High context|Token budget | ~70% reduction | Clarity
 
 ```yaml
 C7: ✓Relevant docs→Proceed | ⚠Partial→Try different terms | ✗No match→Sequential alternatives
-Sequential: ✓Clear analysis+steps→Impl | ⚠Partial→Continue thoughts | ✗Unclear/timeout→Native+user questions  
+Sequential: ✓Clear analysis+steps→Impl | ⚠Partial→Continue thoughts | ✗Unclear/timeout→Native+user questions
 Magic: ✓Component matches→Integrate | ⚠Close needs changes→Refiner | ✗Poor→Try different terms
 Multi-MCP: Results enhance each other | Conflict→Most authoritative | Redundant→Stop calls
 ```

README.md

@@ -1,7 +1,7 @@
 # Meet SuperClaude – The Missing Power-Up for Claude Code
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/NomenAK/SuperClaude/releases)
+[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/NomenAK/SuperClaude)
 [![GitHub issues](https://img.shields.io/github/issues/NomenAK/SuperClaude)](https://github.com/NomenAK/SuperClaude/issues)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/NomenAK/SuperClaude/blob/master/CONTRIBUTING.md)
 
@@ -49,7 +49,7 @@ Switch Claude's entire mindset with one command:
 
 ```bash
 /persona:architect    # Big-picture system design mode
-/persona:frontend     # Pixel-perfect UI obsession mode  
+/persona:frontend     # Pixel-perfect UI obsession mode
 /persona:security     # Paranoid threat-modeling mode
 /persona:analyzer     # Sherlock Holmes debugging mode
 ```
@@ -91,7 +91,7 @@ Our UltraCompressed mode strips unnecessary tokens without losing clarity. More
 /persona:analyzer
 /user:troubleshoot --investigate --prod
 /user:analyze --profile      # Find the real bottleneck
-/persona:performance  
+/persona:performance
 /user:improve --performance --threshold 90%
 ```
 
@@ -114,7 +114,7 @@ SuperClaude is pure configuration – no code, no external dependencies. It work
 
 The framework includes:
 - **CLAUDE.md** – Core configuration and behaviors
-- **RULES.md** – Engineering standards and practices  
+- **RULES.md** – Engineering standards and practices
 - **PERSONAS.md** – 9 specialized thinking modes
 - **MCP.md** – Smart tool orchestration
 - **18 Commands** – Ready-made workflows
@@ -164,7 +164,7 @@ No more "this is better" without proof. SuperClaude enforces:
 
 SuperClaude is MIT-licensed and built by developers, for developers. We welcome:
 - New personas for specialized workflows
-- Commands that solve your daily pain points  
+- Commands that solve your daily pain points
 - Patterns that make Claude Code smarter
 - Ideas that push the boundaries
 

RULES.md

@@ -197,7 +197,7 @@ Risk: HIGH→More Qs | LOW→Safe defaults | Flow: Detect→CRIT block|HIGH opti
 Design: KISS[H:7]: Simple>clever | YAGNI[M:6]: Immediate only | SOLID[H:8]: Single resp|Open/closed
 DRY[M:6]: Extract common|cfg>duplicate | Clean Code[C:9]: <20lines|<5cyclo|<3nest
 Code Gen[C:10]: NO comments unless asked | Short>long names | Minimal boilerplate
-Docs[C:9]: Bullets>paragraphs | Essential only | No "Overview"|"Introduction" 
+Docs[C:9]: Bullets>paragraphs | Essential only | No "Overview"|"Introduction"
 UltraCompressed[C:10]: --uc flag | Context>70% | ~70% reduction | Legend REQUIRED
 Architecture[H:8]: DDD: Bounded contexts|Aggregates|Events | Event→Pub/Sub | Microservices→APIs
 Testing[H:8]: TDD cycle|AAA pattern|Unit>Integration>E2E | Test all|Mock deps|Edge cases

install.sh

@@ -13,6 +13,9 @@ NC='\033[0m' # No Color
 
 # Default installation directory
 INSTALL_DIR="$HOME/.claude"
+FORCE_INSTALL=false
+UPDATE_MODE=false
+UNINSTALL_MODE=false
 
 # Function to show usage
 show_usage() {
@@ -20,12 +23,18 @@ show_usage() {
     echo ""
     echo "Options:"
     echo "  --dir <directory>    Install to custom directory (default: $HOME/.claude)"
+    echo "  --force              Skip confirmation prompts (for automation)"
+    echo "  --update             Update existing installation (preserves customizations)"
+    echo "  --uninstall          Remove SuperClaude from specified directory"
     echo "  -h, --help          Show this help message"
     echo ""
     echo "Examples:"
     echo "  $0                          # Install to default location"
     echo "  $0 --dir /opt/claude        # Install to /opt/claude"
     echo "  $0 --dir ./local-claude     # Install to ./local-claude"
+    echo "  $0 --force                  # Install without prompts"
+    echo "  $0 --update                 # Update existing installation"
+    echo "  $0 --uninstall              # Remove SuperClaude"
 }
 
 # Parse command line arguments
@@ -35,6 +44,18 @@ while [[ $# -gt 0 ]]; do
             INSTALL_DIR="$2"
             shift 2
             ;;
+        --force)
+            FORCE_INSTALL=true
+            shift
+            ;;
+        --update)
+            UPDATE_MODE=true
+            shift
+            ;;
+        --uninstall)
+            UNINSTALL_MODE=true
+            shift
+            ;;
         -h|--help)
             show_usage
             exit 0
@@ -49,7 +70,41 @@ done
 
 # Convert to absolute path if relative
 if [[ ! "$INSTALL_DIR" = /* ]]; then
-    INSTALL_DIR="$(cd "$(dirname "$INSTALL_DIR")" && pwd)/$(basename "$INSTALL_DIR")"
+    # Check if parent directory exists
+    parent_dir=$(dirname "$INSTALL_DIR")
+    if [[ ! -d "$parent_dir" ]]; then
+        echo -e "${RED}Error: Parent directory '$parent_dir' does not exist${NC}"
+        exit 1
+    fi
+    INSTALL_DIR="$(cd "$parent_dir" && pwd)/$(basename "$INSTALL_DIR")"
+fi
+
+# Handle uninstall mode
+if [[ "$UNINSTALL_MODE" = true ]]; then
+    echo -e "${GREEN}SuperClaude Uninstaller${NC}"
+    echo "========================"
+    echo -e "Target directory: ${YELLOW}$INSTALL_DIR${NC}"
+    echo ""
+    
+    if [[ ! -d "$INSTALL_DIR" ]]; then
+        echo -e "${RED}Error: SuperClaude not found at $INSTALL_DIR${NC}"
+        exit 1
+    fi
+    
+    if [[ "$FORCE_INSTALL" != true ]]; then
+        echo -e "${YELLOW}This will remove SuperClaude from $INSTALL_DIR${NC}"
+        echo -n "Are you sure you want to continue? (y/n): "
+        read -r confirm_uninstall
+        if [ "$confirm_uninstall" != "y" ]; then
+            echo "Uninstall cancelled."
+            exit 0
+        fi
+    fi
+    
+    echo "Removing SuperClaude..."
+    rm -rf "$INSTALL_DIR"
+    echo -e "${GREEN}✓ SuperClaude uninstalled successfully!${NC}"
+    exit 0
 fi
 
 echo -e "${GREEN}SuperClaude Installer${NC}"
@@ -57,31 +112,62 @@ echo "======================"
 echo -e "Installation directory: ${YELLOW}$INSTALL_DIR${NC}"
 echo ""
 
-# Confirmation prompt
+# Check write permissions
-echo -e "${YELLOW}This will install SuperClaude in $INSTALL_DIR${NC}"
+parent_for_write=$(dirname "$INSTALL_DIR")
-echo -n "Are you sure you want to continue? (y/n): "
+if [[ -d "$INSTALL_DIR" ]]; then
-read -r confirm_install
+    # Directory exists, check if we can write to it
-if [ "$confirm_install" != "y" ]; then
+    if [[ ! -w "$INSTALL_DIR" ]]; then
-    echo "Installation cancelled."
+        echo -e "${RED}Error: No write permission for $INSTALL_DIR${NC}"
-    exit 0
+        exit 1
+    fi
+elif [[ ! -w "$parent_for_write" ]]; then
+    # Directory doesn't exist, check if we can create it
+    echo -e "${RED}Error: No write permission to create $INSTALL_DIR${NC}"
+    exit 1
+fi
+
+# Confirmation prompt (skip if --force)
+if [[ "$FORCE_INSTALL" != true ]]; then
+    if [[ "$UPDATE_MODE" = true ]]; then
+        echo -e "${YELLOW}This will update SuperClaude in $INSTALL_DIR${NC}"
+    else
+        echo -e "${YELLOW}This will install SuperClaude in $INSTALL_DIR${NC}"
+    fi
+    echo -n "Are you sure you want to continue? (y/n): "
+    read -r confirm_install
+    if [ "$confirm_install" != "y" ]; then
+        echo "Installation cancelled."
+        exit 0
+    fi
 fi
 echo ""
 
 # Check if we're in SuperClaude directory
 if [ ! -f "CLAUDE.md" ] || [ ! -d ".claude/commands" ]; then
     echo -e "${RED}Error: This script must be run from the SuperClaude directory${NC}"
-    echo "Please cd into the SuperClaude directory and try again."
+    echo ""
+    echo "Expected files not found. Please ensure you are in the root SuperClaude directory."
+    echo "Missing: $([ ! -f "CLAUDE.md" ] && echo "CLAUDE.md ")$([ ! -d ".claude/commands" ] && echo ".claude/commands/")"
+    echo ""
+    echo "Solution: cd to the SuperClaude directory and run: ./install.sh"
     exit 1
 fi
 
 # Check if existing directory exists and has files
 if [ -d "$INSTALL_DIR" ] && [ "$(ls -A "$INSTALL_DIR" 2>/dev/null)" ]; then
     echo -e "${YELLOW}Existing configuration found at $INSTALL_DIR${NC}"
-    echo -n "Backup existing configuration? (y/n): "
+    
-    read -r backup_choice
+    # In update mode, always backup
+    if [[ "$UPDATE_MODE" = true ]] || [[ "$FORCE_INSTALL" = true ]]; then
+        backup_choice="y"
+    else
+        echo -n "Backup existing configuration? (y/n): "
+        read -r backup_choice
+    fi
+    
     if [ "$backup_choice" = "y" ]; then
-        # Create backup directory inside installation directory
+        # Create backup directory in parent directory to avoid conflicts
-        backup_dir="$INSTALL_DIR/backup.$(date +%Y%m%d_%H%M%S)"
+        backup_dir="$(dirname "$INSTALL_DIR")/superclaude-backup.$(date +%Y%m%d_%H%M%S)"
         mkdir -p "$backup_dir"
         
         # Backup ALL existing files
@@ -105,7 +191,11 @@ elif [ -d "$INSTALL_DIR" ]; then
 fi
 
 echo ""
-echo "Installing SuperClaude..."
+if [[ "$UPDATE_MODE" = true ]]; then
+    echo "Updating SuperClaude..."
+else
+    echo "Installing SuperClaude..."
+fi
 
 # Create directory structure
 echo "Creating directories..."
@@ -113,7 +203,24 @@ mkdir -p "$INSTALL_DIR/commands/shared"
 
 # Copy main configuration files
 echo "Copying configuration files..."
-cp CLAUDE.md RULES.md PERSONAS.md MCP.md "$INSTALL_DIR/"
+if [[ "$UPDATE_MODE" = true ]]; then
+    # In update mode, preserve user modifications
+    for file in CLAUDE.md RULES.md PERSONAS.md MCP.md; do
+        if [[ -f "$INSTALL_DIR/$file" ]]; then
+            # Check if file differs from source
+            if ! cmp -s "$file" "$INSTALL_DIR/$file"; then
+                echo "  Preserving customized $file (new version: $file.new)"
+                cp "$file" "$INSTALL_DIR/$file.new"
+            else
+                cp "$file" "$INSTALL_DIR/"
+            fi
+        else
+            cp "$file" "$INSTALL_DIR/"
+        fi
+    done
+else
+    cp CLAUDE.md RULES.md PERSONAS.md MCP.md "$INSTALL_DIR/"
+fi
 
 # Copy command files
 echo "Copying slash commands..."
@@ -139,13 +246,30 @@ echo -e "Shared resources: ${GREEN}$shared_files${NC} (expected: 31)"
 # Check if installation was successful
 if [ "$main_files" -ge 4 ] && [ "$command_files" -ge 19 ] && [ "$shared_files" -ge 31 ]; then
     echo ""
-    echo -e "${GREEN}✓ SuperClaude installed successfully!${NC}"
+    if [[ "$UPDATE_MODE" = true ]]; then
-    echo ""
+        echo -e "${GREEN}✓ SuperClaude updated successfully!${NC}"
-    echo "Next steps:"
+        echo ""
-    echo "1. Open any project with Claude Code"
+        # Check for .new files
-    echo "2. Try a command: /user:analyze --code"
+        new_files=$(find "$INSTALL_DIR" -name "*.new" 2>/dev/null)
-    echo "3. Activate a persona: /persona:architect"
+        if [[ -n "$new_files" ]]; then
-    echo ""
+            echo -e "${YELLOW}Note: The following files have updates available:${NC}"
+            echo "$new_files" | while read -r file; do
+                echo "  - $file"
+            done
+            echo ""
+            echo "To review changes: diff <file> <file>.new"
+            echo "To apply update: mv <file>.new <file>"
+            echo ""
+        fi
+    else
+        echo -e "${GREEN}✓ SuperClaude installed successfully!${NC}"
+        echo ""
+        echo "Next steps:"
+        echo "1. Open any project with Claude Code"
+        echo "2. Try a command: /user:analyze --code"
+        echo "3. Activate a persona: /persona:architect"
+        echo ""
+    fi
     if [ -n "$backup_dir" ] && [ -d "$backup_dir" ]; then
         echo -e "${YELLOW}Note: Your previous configuration was backed up to:${NC}"
         echo "$backup_dir"
@@ -155,7 +279,18 @@ if [ "$main_files" -ge 4 ] && [ "$command_files" -ge 19 ] && [ "$shared_files" -
 else
     echo ""
     echo -e "${RED}✗ Installation may be incomplete${NC}"
-    echo "Please check the error messages above or install manually."
+    echo ""
-    echo "See README.md for manual installation instructions."
+    echo "Expected vs Actual file counts:"
+    echo "  Main config files: $main_files/4$([ "$main_files" -lt 4 ] && echo " ❌" || echo " ✓")"
+    echo "  Command files: $command_files/19$([ "$command_files" -lt 19 ] && echo " ❌" || echo " ✓")"
+    echo "  Shared resources: $shared_files/31$([ "$shared_files" -lt 31 ] && echo " ❌" || echo " ✓")"
+    echo ""
+    echo "Troubleshooting steps:"
+    echo "1. Check for error messages above"
+    echo "2. Ensure you have write permissions to $INSTALL_DIR"
+    echo "3. Verify all source files exist in the current directory"
+    echo "4. Try running with sudo if permission errors occur"
+    echo ""
+    echo "For manual installation, see README.md"
     exit 1
 fi