system-setup

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. Use when user mentions setup, installation, dependencies, missing tools, or when SessionStart hook detects configuration issues.
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

<test_mode_protocol> IF --test=SCENARIO argument provided: MUST pass --test=$SCENARIO to ALL system-check.sh invocations MUST display test mode banner at start: [TEST MODE: $SCENARIO] Using mock data - no actual system changes will be made MUST NOT make actual system changes MUST use mock data from test scenarios </test_mode_protocol>

<precondition_gate> 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 </precondition_gate>

<delegation_rules> 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 </delegation_rules>

<cross_references> references/platform-requirements.md references/juce-setup-guide.md

</cross_references>

---

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	Behavior	Installation	User Actions
automated	Attempt automated installation with confirmation	Offers automatic install → falls back to manual if fails	Confirms installations, completes any GUI steps
guided	Show manual instructions only	NEVER automated - always manual instructions	Completes all installations manually, confirms when done
check-only	Report status without changes	NEVER offers installation	None - just review report

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.

---

<critical_sequence name="dependency-validation" enforcement="strict"> These dependencies MUST be validated in order. Each dependency may block on user input.

<execution_rules>

• Execute dependencies sequentially (1 → 2 → 3 → 4 → 5)
• Each dependency must complete or be explicitly skipped before proceeding
• Mode choice (automated/guided/check-only) persists across all dependencies unless changed
• Failed automated installs fall back to guided mode
• User can abort at any decision gate
• If TEST_MODE is set, append --test=$TEST_MODE to all system-check.sh invocations </execution_rules>

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

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

Dependency Validation

For detailed validation workflow, error handling, and dependency-specific variations, see:

• Validation pattern: references/validation-workflow.md
• Error recovery: references/error-recovery.md

High-level validation process:

1. Platform Detection - Detect macOS/Linux/Windows, confirm with user
2. Python 3.8+ - Required for build scripts
3. Build Tools - Xcode Command Line Tools (macOS), GCC/Clang (Linux), Visual Studio (Windows)
4. CMake 3.15+ - Build system for JUCE projects
5. JUCE 8.0.0+ - Audio plugin framework
6. pluginval - Plugin validation tool (optional)

For each dependency:

• Run detection via system-check.sh
• If found and version OK → save to config, continue
• If not found → offer installation based on MODE (automated/guided/check-only)
• After installation → verify and save to config

See validation-workflow.md for complete algorithm and dependency-specific handling.

---

---

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: Use Skill tool to invoke plugin-ideation: Skill("plugin-ideation")
• 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

<state_management> This skill is STANDALONE and does NOT:

• Update PLUGINS.md
• Create .continue-here.md
• Invoke other workflow skills (plugin-workflow, plugin-planning, etc.)
• Create or modify plugin directories

This skill ONLY:

• Creates/updates .claude/system-config.json
• Validates system dependencies
• Adds system-config.json to .gitignore
• Exits when validation complete

After setup completes successfully:

1. Configuration stored in .claude/system-config.json only
2. NO state file updates needed
3. NO plugin workflow initiated
4. User chooses next action from final menu </state_management>

---

Error Handling

For detailed error recovery procedures and failure scenarios, see references/error-recovery.md.

General principle: All errors offer recovery paths - automated installation failures fall back to guided mode, permission errors offer sudo or user-directory alternatives, and missing critical dependencies trigger warning menus.

---

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

---

Implementation Notes

For detailed execution notes, critical requirements, and anti-patterns, see references/execution-notes.md.

Key reminders:

• Check before installing (never install if already present and correct version)
• Respect MODE throughout entire session
• Use absolute paths in config
• Wait for user confirmation at all decision gates
• Append test mode to all system-check.sh calls if TEST_MODE set