system-setup

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

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

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

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

---

For detailed dependency requirements and installation instructions, see [references/platform-requirements.md](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)

---

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

```

1. 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

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

```

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

```bash

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

---

Copy this checklist at skill start to track your progress:

```text

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.

---

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:

```bash

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

```bash

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

```

---

These dependencies MUST be validated in order. Each dependency may block on user input.

• 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

Step 1: Detect platform

```bash

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

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

```

---

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

1. If not found:

- Automated mode: Offer to install automatically

- Guided mode: Show manual installation instructions

- Check-only mode: Report as missing, continue

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

• Validation pattern: [references/validation-workflow.md](references/validation-workflow.md)
• Error recovery: [references/error-recovery.md](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](references/validation-workflow.md) for complete algorithm and dependency-specific handling.

---

---

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

```bash

# Generate config file

cat > .claude/system-config.json <

{

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

```bash

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

```

---

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

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

---

For detailed error recovery procedures and failure scenarios, see [references/error-recovery.md](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.

---

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)

---

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

---

For detailed execution notes, critical requirements, and anti-patterns, see [references/execution-notes.md](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