Setup

---
name: setup
description: Initial workspace setup — configures modules and verification profiles based on user selections from the admin panel
user_invocable: false
tools_required:
  - Bash
  - Read
  - Edit
  - Write
---

# Setup — Workspace Configuration Assistant

This skill is invoked automatically by the admin panel's setup wizard. It receives a configuration payload describing which modules to install and which verification profiles to configure.

## Input

The setup configuration is passed as the initial prompt. It contains:
- **modules to enable**: List of module IDs to enable (e.g., `["telegram"]`)
- **modules to disable**: List of module IDs to disable (e.g., `["other_module"]`)
- **languages**: List of language profile configurations to set up

## Execution Flow

### Phase 1: Module Configuration

For each module in the `modules to enable` list:

1. Read the module's skill file at `<repo>/claude/modules/<module_id>/SKILL.md`
2. Read the skill thoroughly — understand its `enable` section before doing anything
3. Follow the `enable` instructions exactly as written in the skill (the `enable` command handles install if needed, then activates the integration)
4. If the skill defines a `status` command, run it after enabling to verify success
5. If enabling fails:
   - Capture the full error output
   - Report it clearly: what failed, what the error was, what the user can do
   - Continue to the next module — do not abort the entire setup

For each module in the `modules to disable` list:

1. Read the module's skill file at `<repo>/claude/modules/<module_id>/SKILL.md`
2. Read the skill thoroughly — understand its `disable` section before doing anything
3. Follow the `disable` instructions exactly as written in the skill
4. If disabling fails:
   - Capture the full error output
   - Report it clearly: what failed, what the error was, what the user can do
   - Continue to the next module — do not abort the entire setup

### Phase 2: Verification Profile Validation and Setup

Detect the device environment before processing any profiles:
- Run `uname -s` to determine OS (Darwin = macOS, Linux = Linux)
- On macOS, check if `brew` is available (`which brew`)
- On Linux, identify the package manager (`which apt`, `which dnf`, `which pacman`)
- Note the detected environment — it will affect install commands throughout this phase

#### For Preset / System Profiles

For each selected preset language profile:

1. Check if a matching verification profile already exists via MCP workspace tools
2. If it exists, do not recreate it — proceed to validate it
3. **Validate each step in the profile actually works on this device:**
   - Run the step's `install_check_command` (e.g., `which java`, `which python3`)
   - If the check fails (tool not found):
     - Run the step's `install_command` to install it
     - If the install command fails, inform the user clearly: what tool is missing, what command was attempted, what they need to do manually (e.g., download from official site, accept a license, log in)
   - After installation (or if already present), run a quick smoke test of the main command to confirm it works:
     - e.g., `java --version`, `python3 --version`, `node --version`, `go version`
   - If the smoke test fails despite the tool being "installed", report the specific output and warn the user
4. Check whether the profile's commands are compatible with this device:
   - Watch for hardcoded paths that may not exist (e.g., `/usr/local/bin/...` on macOS with Apple Silicon vs Intel)
   - Watch for Linux-only or macOS-only commands
   - If a command references a path or tool that doesn't exist on this device, warn the user and suggest what needs to be adjusted
5. Assign the profile to the workspace after validation

#### For Custom Language Configurations

For each custom language configuration:

1. Create the verification profile via `workspace_create_verification_profile` MCP tool.
   **If the configuration includes LSP settings**, pass them in the same call:
   ```
   workspace_create_verification_profile(
     name="Go",
     language="go",
     description="Go compilation, lint, and test",
     lsp_command="gopls",
     lsp_args='["serve"]',
     lsp_install_check_command="which gopls",
     lsp_install_command="go install golang.org/x/tools/gopls@latest"
   )
   ```
   The `lsp_command` parameter is **required** for the LSP button to appear in the admin panel header. If omitted, the profile will work for verification but LSP integration will be missing.
2. For each tool specified in the configuration:
   - If `install_check_command` is not provided, auto-detect it: use `which <tool>` as the default
   - If `install_command` is not provided, auto-detect based on OS and package manager:
     - macOS with brew: `brew install <tool>`
     - Debian/Ubuntu: `sudo apt install -y <tool>`
     - Fedora/RHEL: `sudo dnf install -y <tool>`
   - Add the tool as a verification step via `workspace_add_verification_step` MCP tool
   - Run the `install_check_command` to verify the tool is present
   - If the tool is missing:
     - Run the `install_command`
     - If it fails, explain what the user needs to do manually (license acceptance, account creation, manual download, etc.)
   - Run a smoke test of the tool to confirm it works end-to-end
3. Assign the profile to the workspace

### LSP Server Setup

For each profile that includes LSP configuration (`lsp_server` field in the configuration):

1. Check the profile's `description` field via `workspace_get_verification_profiles`. If it contains setup instructions (look for phrases like "LSP setup requires", "LSP setup uses", or "call `workspace_update_verification_profile`"), follow those instructions now — before smoke-testing:
   - Execute any discovery or install commands described
   - Once the required path or value is resolved, call `workspace_update_verification_profile` with the profile's ID and the resolved LSP fields (e.g., updated `lsp_command` and `lsp_args`)
   - Continue with the updated profile values for all subsequent steps
2. Check if the LSP server binary is installed by running the `lsp_install_check_command` from the profile (use the updated value if it was just changed), or `which <lsp_server>` if no check command is provided
3. If not installed, run the `lsp_install` command from the configuration
   - If the install command fails, report clearly: what binary is missing, what was attempted, and what the user must do manually
4. Smoke-test the server to confirm it runs: try `<lsp_server> --help` or `<lsp_server> --version`
   - If the binary exits with a non-zero code but the LSP protocol requires no flags, treat it as passing if the binary is found
   - If the binary is not found at all, report it as a failure
5. Report LSP server status alongside the profile status: installed / not installed / failed

#### LSP runtime version matching (Java / jdtls specifically)

Java's LSP server (`jdtls`) is JVM-based, and each jdtls release has a *minimum required JDK*. Mismatches are the most common cause of `LSP server closed stdout before responding to initialize`. The Java profile description carries the version matrix and discovery commands — follow them, but the core idea is:

- Detect installed jdtls version: `brew info jdtls` (macOS) or check the binary's wrapper script.
- Approximate matrix: jdtls < 1.28 → JDK 11+; jdtls 1.28–1.37 → JDK 17+; jdtls ≥ 1.38 → JDK 21+.
- Confirmation: run `JAVA_HOME=<candidate> jdtls --jvm-arg=-Xmx1G </dev/null` once. If it errors with `jdtls requires at least Java N`, switch to JDK N and retry. If it starts cleanly and waits for stdin, the JDK is correct.
- After resolution, call `workspace_update_verification_profile` to write `lsp_command='bash'` and `lsp_args='["-c", "JAVA_HOME=<resolved> exec jdtls --jvm-arg=-Xmx1G"]'`.

#### LSP runtime troubleshooting (jdtls workspace cache)

If a jdtls-based profile starts cleanly via `bash -c` from the terminal but the admin panel reports `LSP server closed stdout before responding to initialize`, jdtls's per-project workspace cache is almost certainly corrupt. jdtls hashes the project working directory and stores Eclipse workspace state at:
- macOS: `~/Library/Caches/jdtls/jdtls-<hash>/`
- Linux: `~/.cache/jdtls/jdtls-<hash>/`

When that state references files that no longer exist on disk (after a rebuild, branch switch, or stale build artifacts), Eclipse's `ResourcesPlugin` throws `ObjectNotFoundException` during init and the server exits before responding. Fix: delete the offending `jdtls-<hash>/` directory and retry the LSP start. The fresh cache rebuilds in under a minute. The actual error stack lives in the cache's `.metadata/.log` file — read it to confirm the diagnosis before wiping anything else.

#### LSP runtime setup (Kotlin / kotlin-lsp specifically)

Kotlin uses the official JetBrains `kotlin-lsp` (the `Kotlin/kotlin-lsp` project, distributed by JetBrains). It is **not** the same as the community `fwcd/kotlin-language-server` — pick the JetBrains one, it's based on IntelliJ infrastructure and gives correct cross-module references for JVM Gradle projects.

Important: Kotlin and Java are **different LSP servers** even though both target the JVM. jdtls cannot index `.kt` files; kotlin-lsp cannot index `.java` files. If a project mixes both you need both profiles assigned.

Install:
- macOS: `brew install --cask kotlin-lsp`
- Linux: download the latest archive from `https://github.com/Kotlin/kotlin-lsp/releases`, extract it, and symlink `kotlin-lsp.sh` to a directory on PATH as `kotlin-lsp`.

Smoke test: `kotlin-lsp --help` should print usage. The binary ships its own bundled JRE — there is no `JAVA_HOME` or system Java requirement, and the version-matching dance you do for jdtls does **not** apply here.

LSP profile fields for Kotlin:
- `lsp_command`: `kotlin-lsp`
- `lsp_args`: `["--stdio"]`
- `lsp_install_check_command`: `which kotlin-lsp`
- `lsp_install_command` (macOS): `brew install --cask kotlin-lsp`

First-start timing: kotlin-lsp performs its full Gradle import + index pass on the first `initialize` request. For a fresh, never-imported multi-module project this takes 30-90 seconds before references will work. Subsequent starts reuse the cache and are much faster. If a `textDocument/references` query returns empty immediately after start, wait and retry — it is almost always still indexing.

Limitations (per upstream, status as of 262.x): Kotlin Multiplatform and Maven are not yet supported. Only JVM Gradle projects work reliably. If the profile is assigned to a KMP or Maven Kotlin project, expect kotlin-lsp to either return partial results or fail to import; report this clearly to the user instead of silently treating it as success.

For custom profiles with LSP:

1. The user provides the binary name (`lsp_server`) and install command (`lsp_install`) in the configuration
2. Follow the same check → install → smoke-test flow described above
3. Pass LSP parameters in `workspace_create_verification_profile` for a clean setup, or add/update them later via `workspace_update_verification_profile`. The following parameters map from the user's configuration:
   - `lsp_server` → `lsp_command` parameter
   - `lsp_install` → `lsp_install_command` parameter
   - Auto-derive `lsp_install_check_command` as `which <lsp_server>` if not provided
   - Set `lsp_args` if the LSP protocol requires specific flags (e.g., `'["--stdio"]'`)
4. After creation, verify the profile ID was returned and the LSP button appears in the admin panel

### Phase 3: Final Verification

1. List all configured modules and their status (enabled / disabled / failed / skipped)
2. List all configured verification profiles with the status of each step:
   - Step name, install check result, smoke test result
3. Run a quick verification pass of each profile to confirm all steps pass cleanly
4. Report a summary:
   - What succeeded
   - What failed or is degraded
   - Any manual actions the user needs to take, listed clearly and specifically

## Module Directory Structure

Modules live at `<repo>/claude/modules/`. Each module directory contains:
- `SKILL.md` — The skill definition with install/configure/status instructions
- Additional files needed by the module (scripts, configs, etc.)

## Verification Profile Configuration

When creating custom verification profiles, each language configuration includes:
- `name` — Profile display name (e.g., "Go")
- `language` — Language key (e.g., "go")
- `tools` — List of tools to add as verification steps, each with:
  - `name` — Step name (e.g., "Compilation")
  - `command` — The verification command (e.g., `go build ./...`)
  - `install_check_command` — Command to check if tool is installed (e.g., `which go`)
  - `install_command` — Command to install the tool if missing
  - `fail_severity` — `"blocking"` or `"warning"`

## Important Notes

- Profiles are global, not workspace-specific — they apply across all projects once configured
- Be adaptive to the device: never assume a fixed OS, package manager, or binary location
- Never skip a failure silently — always report what happened and what the user can do about it
- If the user needs to take a manual action (accept a license, log in to a registry, download a proprietary SDK), explain exactly what to do with enough detail that they can act without guessing
- This skill should minimize interaction, but it must not hide problems behind false success messages