name	system-setup
description	Validates and configures all dependencies required for the Plugin Freedom System. This is a STANDALONE skill that runs BEFORE plugin workflows begin. It checks for Python, build tools, CMake, JUCE, and pluginval, optionally installing missing dependencies with user approval. Configuration is saved to .claude/system-config.json for use by other skills.
allowed-tools	Bash, Read, Write, Edit
preconditions	None - this is the entry point for new users

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

This skill is STANDALONE - it does NOT delegate to other skills or subagents All validation logic is handled by system-check.sh bash script This skill is invoked BEFORE plugin workflows begin DO NOT invoke plugin-workflow, plugin-planning, or any other plugin skills from here references/platform-requirements.md references/juce-setup-guide.md

Required Dependencies

Python 3.8+

Purpose: Build scripts and automation
Check: python3 --version
Minimum version: 3.8
Auto-install (macOS): Homebrew (brew install python3) or download from python.org

Build Tools

macOS: Xcode Command Line Tools
- Check: xcode-select -p
- Auto-install: xcode-select --install
Linux: GCC/Clang, build-essential
Windows: Visual Studio 2019+

CMake 3.15+

Purpose: Build system for JUCE projects
Check: cmake --version
Minimum version: 3.15
Auto-install (macOS): Homebrew (brew install cmake)

JUCE 8.0.0+

Purpose: Audio plugin framework
Check: Search standard locations, validate version in modules/juce_core/juce_core.h
Standard locations:
- ~/JUCE
- /Applications/JUCE
- /usr/local/JUCE
Auto-install: Download from juce.com, extract to ~/JUCE

pluginval

Purpose: Plugin validation tool
Check: pluginval --version or check standard locations
Standard locations:
- /usr/local/bin/pluginval
- ~/bin/pluginval
Auto-install: Download from GitHub releases, install to /usr/local/bin

Skill Entry Point

When invoked via /setup command:

Check for test mode first:

If user provided --test=SCENARIO argument, set TEST_MODE variable
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

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): _

Store user choice and proceed to platform detection

After user selects mode, ALL subsequent dependency validations MUST respect this mode:

MODE: "automated"

Attempt installations with user confirmation
Fall back to guided instructions if automation fails
Present installation menus for missing dependencies
Wait for user choice at each menu

MODE: "guided"

NEVER attempt automated installation
Display manual instructions from references/
Wait for user to complete manual steps
Verify installation after user confirms completion

MODE: "check-only"

NEVER offer installation (automated or guided)
Report each dependency status (found/missing/wrong-version)
Continue through all dependencies regardless of failures
Generate report at end showing what needs attention

Platform Detection

Step 1: Detect platform

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

Note: If TEST_MODE is set, append --test=$TEST_MODE to ALL system-check.sh invocations throughout this skill.

The script returns JSON:

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

Step 2: Confirm with user

Detected platform: macOS 14.0 (arm64)

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

Choose (1-2): _

Dependency Validation Workflow

For each dependency (in order):

Check if already installed and functional
If found:
- Display version and path
- Validate it meets minimum requirements
- Save to config
- Continue to next dependency
If not found:
- Automated mode: Offer to install automatically
- Guided mode: Show manual installation instructions
- Check-only mode: Report as missing, continue

1. Python Validation

Check command:

bash .claude/skills/system-setup/assets/system-check.sh --check-python

Returns:

{
  "found": true,
  "version": "3.11.5",
  "path": "/usr/local/bin/python3",
  "meets_minimum": true
}

If found and valid:

✓ Python 3.11.5 found at /usr/local/bin/python3

If not found (automated mode):

✗ Python 3.8+ not found

Would you like me to install Python 3 via Homebrew?
1. Yes, install automatically
2. No, show me manual instructions
3. Skip Python (not recommended)

Choose (1-3): _

If user chooses automated install:

# Check if Homebrew is installed first
which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3

# Verify installation
python3 --version

If user chooses manual instructions: Display content from references/platform-requirements.md section on Python installation.

If not found (guided mode): Display manual installation instructions immediately, no automation offered.

2. Build Tools Validation

macOS:

bash .claude/skills/system-setup/assets/system-check.sh --check-xcode

Returns:

{
  "found": true,
  "path": "/Library/Developer/CommandLineTools",
  "version": "15.0"
}

If found:

✓ Xcode Command Line Tools found (version 15.0)

If not found (automated mode):

✗ Xcode Command Line Tools not found

These are required for compiling C++ code on macOS.

Would you like me to install them?
1. Yes, install automatically
2. No, show me manual instructions
3. Skip (build will fail)

Choose (1-3): _

Automated install:

xcode-select --install
# Wait for installation dialog
# User must complete the GUI installation
echo "⏳ Please complete the Xcode Command Line Tools installation dialog."
echo "Press Enter when installation is complete..."
read

3. CMake Validation

Check command:

bash .claude/skills/system-setup/assets/system-check.sh --check-cmake

Returns:

{
  "found": true,
  "version": "3.27.4",
  "path": "/usr/local/bin/cmake",
  "meets_minimum": true
}

If found and valid:

✓ CMake 3.27.4 found at /usr/local/bin/cmake

If not found (automated mode):

✗ CMake 3.15+ not found

CMake is required for building JUCE projects.

Would you like me to install CMake via Homebrew?
1. Yes, install automatically
2. No, download manually from cmake.org
3. Skip (build will fail)

Choose (1-3): _

Automated install:

brew install cmake
cmake --version

4. JUCE Validation

This is the most complex check due to multiple possible locations.

Step 1: Search standard locations

bash .claude/skills/system-setup/assets/system-check.sh --check-juce

Returns:

{
  "found": true,
  "path": "/Users/lex/JUCE",
  "version": "8.0.3",
  "meets_minimum": true
}

OR if not found in standard locations:

{
  "found": false,
  "checked_paths": [
    "/Users/lex/JUCE",
    "/Applications/JUCE",
    "/usr/local/JUCE"
  ]
}

If found in standard location:

✓ JUCE 8.0.3 found at /Users/lex/JUCE

If not found, ask about custom location:

✗ JUCE not found in standard locations

JUCE is required for plugin development.

Do you have JUCE 8.0+ installed in a custom location?
1. Yes, let me provide the path
2. No, install it for me (automated mode only)
3. No, show me how to install it manually

Choose (1-3): _

If user provides custom path:

Enter the full path to your JUCE installation:
(e.g., /Users/lex/Development/JUCE)

Path: _

Validate the provided path:

bash .claude/skills/system-setup/assets/system-check.sh --validate-juce-path "$USER_PROVIDED_PATH"

If path is valid:

✓ JUCE 8.0.3 found at /Users/lex/Development/JUCE

If path is invalid:

✗ Invalid JUCE installation at provided path

The path must contain JUCE modules (modules/juce_core/juce_core.h).

Would you like to:
1. Try a different path
2. Install JUCE to default location (~/JUCE)
3. Show manual installation instructions

Choose (1-3): _

Automated JUCE installation:

Installing JUCE 8.0.3 to ~/JUCE...

⏳ Downloading JUCE from juce.com...

# Download latest JUCE 8.x
cd ~
curl -L -o JUCE.zip "https://github.com/juce-framework/JUCE/releases/download/8.0.3/juce-8.0.3-osx.zip"

# Extract
unzip -q JUCE.zip
mv juce-8.0.3-osx JUCE

# Cleanup
rm JUCE.zip

# Verify
bash .claude/skills/system-setup/assets/system-check.sh --validate-juce-path ~/JUCE

If download fails: Fall back to manual instructions from references/juce-setup-guide.md.

5. pluginval Validation

Check command:

bash .claude/skills/system-setup/assets/system-check.sh --check-pluginval

Returns:

{
  "found": true,
  "version": "1.0.3",
  "path": "/usr/local/bin/pluginval"
}

If found:

✓ pluginval 1.0.3 found at /usr/local/bin/pluginval

If not found (automated mode):

✗ pluginval not found

pluginval is used to validate plugin compliance.

Would you like me to install it?
1. Yes, install automatically
2. No, show manual instructions
3. Skip (validation will be limited)

Choose (1-3): _

Automated install:

# Download latest pluginval for macOS
cd /tmp
curl -L -o pluginval.zip "https://github.com/Tracktion/pluginval/releases/latest/download/pluginval_macOS.zip"

# Extract
unzip -q pluginval.zip

# Install to /usr/local/bin
sudo mv pluginval.app/Contents/MacOS/pluginval /usr/local/bin/
sudo chmod +x /usr/local/bin/pluginval

# Cleanup
rm -rf pluginval.zip pluginval.app

# Verify
pluginval --version

Configuration Persistence

After all dependencies are validated, create .claude/system-config.json:

# 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

Add to .gitignore if not already present:

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

System Report

After configuration is saved, display comprehensive summary:

✓ 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): _

Handle user choice:

Choice 1: Invoke plugin-ideation skill (same as /dream)
Choice 2: Show command list via ls .claude/commands/
Choice 3: Display README.md
Choice 4: Re-run system-setup skill
Choice 5: Exit with message

After setup completes successfully:

NO state file updates needed (system-setup is standalone)
DO NOT update PLUGINS.md (no plugin created)
DO NOT update .continue-here.md (not part of workflow)
Configuration is stored in .claude/system-config.json only

Error Handling

Automated Installation Failures

If any automated installation fails:

Capture error output
Display error message
Fall back to guided mode

Example:

✗ Failed to install CMake via Homebrew

Error: Homebrew is not installed and automatic installation failed.

Falling back to manual instructions...

[Display manual CMake installation steps from references/platform-requirements.md]

Press Enter to continue with manual installation...

Missing Critical Dependencies

If critical dependencies are missing and user skips them:

⚠ Warning: Critical dependencies are missing

The following required dependencies were not installed:
- CMake 3.15+ (required for building)
- JUCE 8.0+ (required for plugin development)

You will not be able to build plugins until these are installed.

Would you like to:
1. Go back and install missing dependencies
2. Save current configuration anyway (not recommended)
3. Exit without saving

Choose (1-3): _

Version Too Old

If a dependency is found but version is too old:

✗ CMake 3.10.2 found, but version 3.15+ is required

Would you like to:
1. Update CMake via Homebrew (automated)
2. Show manual update instructions
3. Continue anyway (build may fail)

Choose (1-3): _

Permission Errors

If installation fails due to permissions:

✗ Failed to install pluginval: Permission denied

This usually means you need sudo access.

Would you like to:
1. Retry with sudo (will prompt for password)
2. Install to ~/bin instead (no sudo required)
3. Show manual instructions

Choose (1-3): _

Checkpoint Protocol Integration

This skill follows the checkpoint protocol:

After each major validation step:

Display what was found/installed
Present numbered decision menu
Wait for user response
Execute chosen action

Major checkpoint moments:

After platform detection
After each dependency validation
After configuration is saved
At final system report

Always use inline numbered menus, never AskUserQuestion tool.

Integration Points

Invoked by:

/setup command (primary entry point)
New user onboarding
When build scripts detect missing dependencies

Reads:

.claude/system-config.json (if exists, to show current config)
references/platform-requirements.md (platform-specific installation guides)
references/juce-setup-guide.md (detailed JUCE installation)

Creates:

.claude/system-config.json (validated dependency paths)

Uses:

assets/system-check.sh (bash validation script)

May invoke:

plugin-ideation skill (if user chooses to create plugin after setup)

Success Criteria

Setup is successful when:

All required dependencies are detected or installed
All versions meet minimum requirements
All tools are validated as functional (not just present)
Configuration is saved to .claude/system-config.json
User receives clear system report
Decision menus presented at appropriate points
Errors are handled gracefully with fallback options

Notes for Claude

Check before installing (NEVER install if exists) Validate versions meet minimums (don't assume) Test functionality (not just presence) Get confirmation before automated installation Provide fallback if automation fails Use absolute paths (expand ~, validate existence) Mode-specific behavior (respect user's choice) Append test mode to all system-check.sh calls if TEST_MODE set Installing without checking first Not validating version requirements Proceeding when critical dependencies missing Using relative paths in config Not testing executables actually run Auto-proceeding without user confirmation Using AskUserQuestion tool instead of inline menus Forgetting to append test mode to system-check.sh calls Not respecting MODE throughout execution

Automated vs Guided Mode:

Automated mode: Attempt installation with confirmation, fall back to guided if fails
Guided mode: Show manual instructions immediately, no automation
Check-only mode: Report what's found, make no changes

Path handling:

Convert all paths to absolute paths
Validate paths exist before saving to config
Expand ~ to actual home directory path
Check that JUCE path contains expected files (modules/juce_core/juce_core.h)

macOS-specific notes:

Xcode CLI Tools installation requires GUI interaction
Homebrew installation may require user interaction
Some installations may need sudo (get permission first)
/usr/local/bin may need sudo for writing

Common pitfalls to AVOID:

Installing without checking if already present
Not validating versions meet minimums
Proceeding when critical dependencies missing
Using relative paths in configuration
Not testing if executables actually run
Auto-proceeding without user confirmation
Using AskUserQuestion instead of inline menus

This skill is complete when:

✓ Platform detected and confirmed by user
✓ All 5 dependencies validated (or user explicitly skipped)
✓ Configuration saved to .claude/system-config.json
✓ Configuration file added to .gitignore
✓ Final system report displayed
✓ User selected action from final menu (exit, start new plugin, resume existing)

DO NOT auto-proceed to next action after final menu - user decides what's next.

system-setup

Install Skill

SKILL.md

system-setup Skill

Overview

Required Dependencies

Python 3.8+

Build Tools

CMake 3.15+

JUCE 8.0.0+

pluginval

Skill Entry Point

Platform Detection

Dependency Validation Workflow

1. Python Validation

2. Build Tools Validation

3. CMake Validation

4. JUCE Validation

5. pluginval Validation

Configuration Persistence

System Report

Error Handling

Automated Installation Failures

Missing Critical Dependencies

Version Too Old

Permission Errors

Checkpoint Protocol Integration

Integration Points

Success Criteria

Notes for Claude