system-setup Skill

Purpose: Validate and configure all dependencies required for JUCE plugin development in the Plugin Freedom System.

Overview

This skill ensures new users can get started without friction by:

• Detecting the current platform (macOS, Linux, Windows)
• Checking for required dependencies (Python, build tools, CMake, JUCE, pluginval)
• Offering automated installation where possible
• Guiding manual installation when automation isn't available
• Validating that all tools are functional
• Saving validated configuration for build scripts

Target platform: macOS (extensible to Windows/Linux later)

User experience: Interactive, with clear choices between automated and guided setup

None required - this is the entry point skill Can be invoked anytime, creates system-config.json No dependencies on PLUGINS.md or .continue-here.md

Required Dependencies

For detailed dependency requirements and installation instructions, see references/platform-requirements.md.

Summary: Python 3.8+, Build Tools (Xcode Command Line Tools/GCC/MSVC), CMake 3.15+, JUCE 8.0.0+, pluginval (optional)

Skill Entry Point

When invoked via /setup command:

Check for existing configuration first:

1. Check if .claude/system-config.json exists and is recent (validated within last 30 days)
2. If valid config exists, offer quick menu:

   System Setup - Plugin Freedom System
   
   Existing configuration found (validated 5 days ago)
   
   What would you like to do?
   1. Re-validate all dependencies (full check)
   2. View current configuration
   3. Reconfigure specific dependency
   4. Exit
   
   Choose (1-4): _
   

3. Handle choice:
   • Choice 1: Proceed to full validation flow below (skip MODE selection, use "check-only" mode)
   • Choice 2: Display .claude/system-config.json contents and exit
   • Choice 3: Ask which dependency to reconfigure, then run validation for that dependency only
   • Choice 4: Exit
4. Only load full references if user chooses option 1 (full re-validation)

If no valid config exists, proceed with full setup:

Check for test mode:

• TEST_MODE is set if user provided --test=SCENARIO argument to /setup command
• Store in variable: TEST_MODE=SCENARIO (or empty if not in test mode)
• This variable persists throughout the entire setup session
• Pass test mode to all system-check.sh invocations via --test=$SCENARIO
• Show test mode banner if active:

  [TEST MODE: $SCENARIO]
  Using mock data - no actual system changes will be made
  

1. Welcome message:

   System Setup - Plugin Freedom System
   
   This will validate and configure all dependencies needed for JUCE plugin development.
   
   How would you like to proceed?
   1. Automated setup (install missing dependencies automatically)
   2. Guided setup (step-by-step instructions for manual installation)
   3. Check only (detect what's installed, no changes)
   4. Exit
   
   Choose (1-4): _
   

2. Store user choice in MODE variable and proceed to platform detection

   # Store user's mode choice (persists throughout entire setup)
   MODE="automated"  # or "guided" or "check-only"
   

   This MODE variable determines behavior for ALL dependency validations (Python, Build Tools, CMake, JUCE, pluginval).

Mode Definitions

Mode persistence: User's initial mode choice applies to ALL 5 dependency validations. Mode does NOT change mid-session.

Setup Progress Checklist

Copy this checklist at skill start to track your progress:

Setup Progress:
- [ ] Platform detected and confirmed
- [ ] Python 3.8+ installed and verified
- [ ] Build tools installed and verified (Xcode Command Line Tools / GCC / MSVC)
- [ ] CMake 3.15+ installed and verified
- [ ] JUCE 8.0.0+ installed and verified
- [ ] pluginval installed and verified (optional)
- [ ] Configuration saved to .claude/system-config.json
- [ ] Setup complete

Mark each item as you complete it.

State Management

Two variables persist throughout the entire setup session:

MODE Variable

Initialized: At skill entry when user selects from menu (lines 85-99) Values: "automated", "guided", "check-only" Scope: Used for ALL dependency validations (Python, Build Tools, CMake, JUCE, pluginval) Persistence: Does NOT change mid-session - user's initial choice applies to all 5 dependencies

Example:

# User selects option 1 at entry menu
MODE="automated"

# This MODE value is used for Python validation
# Then Build Tools validation
# Then CMake validation
# Then JUCE validation
# Then pluginval validation
# MODE never changes during session

TEST_MODE Variable

Initialized: At skill entry if user provided --test=SCENARIO argument to /setup command Values: Scenario name (e.g., "missing-cmake", "old-python") or empty if not in test mode Scope: Appended to ALL system-check.sh invocations throughout session Persistence: Does NOT change mid-session

Example:

# User invoked: /setup --test=missing-cmake
TEST_MODE="missing-cmake"

# All system-check.sh calls include test mode:
bash system-check.sh --check-python --test=missing-cmake
bash system-check.sh --check-xcode --test=missing-cmake
# etc.

# Run system check script (append --test=$SCENARIO if in test mode)
bash .claude/skills/system-setup/assets/system-check.sh --detect-platform ${TEST_MODE:+--test=$TEST_MODE}

{
  "platform": "darwin",
  "platform_version": "14.0",
  "arch": "arm64"
}

Detected platform: macOS 14.0 (arm64)

Is this correct?
1. Yes, continue
2. No, let me specify

Choose (1-2): _

# Generate config file
cat > .claude/system-config.json <<EOF
{
  "platform": "darwin",
  "platform_version": "14.0",
  "arch": "arm64",
  "python_path": "/usr/local/bin/python3",
  "python_version": "3.11.5",
  "xcode_path": "/Library/Developer/CommandLineTools",
  "cmake_path": "/usr/local/bin/cmake",
  "cmake_version": "3.27.4",
  "juce_path": "/Users/lex/JUCE",
  "juce_version": "8.0.3",
  "pluginval_path": "/usr/local/bin/pluginval",
  "pluginval_version": "1.0.3",
  "validated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

grep -q "system-config.json" .gitignore || echo ".claude/system-config.json" >> .gitignore

✓ System Setup Complete

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Platform: macOS 14.0 (arm64)

Dependencies validated:
✓ Python 3.11.5 (/usr/local/bin/python3)
✓ Xcode Command Line Tools 15.0
✓ CMake 3.27.4 (/usr/local/bin/cmake)
✓ JUCE 8.0.3 (/Users/lex/JUCE)
✓ pluginval 1.0.3 (/usr/local/bin/pluginval)

Configuration saved to:
.claude/system-config.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What's next?
1. Create your first plugin (/dream)
2. View available commands (type /? or press Tab)
3. Read the documentation (@README.md)
4. Run system check again (/setup)
5. Exit

Choose (1-5): _