User Story

As an adopter running /setup on a fresh apexyard fork, I want LSP installed + configured + enabled as part of the bootstrap flow (with the option to decline), so that I get the documented 3-15× token savings on /code-review, /threat-model, /security-review, and /handover deep-dive without having to learn about ENABLE_LSP_TOOL, find the right language-server binary, install the right Claude Code plugin, and edit my shell rc.

Driver

/setup's job is to take a fresh fork to "ready to use" in ~2 minutes. Today's flow stops short of LSP — adopters get LSP-aware skill callouts but no enabled LSP. They have to read docs/getting-started.md, install per-language servers (npm/pip/etc.), set an env var, and install the Claude Code LSP plugin themselves. The "3 minutes of setup buys 3-15× per-query savings" trade-off is the right one, but adopters won't make it if the work is hidden in docs.

From the user's testing of this fork on a constrained machine: "we are NOT using LSP" was the diagnostic — three pre-requisites all unmet (env var, plugin, language server binaries). Framework recommends LSP, marketing implies it's part of the team-feel, reality is it's opt-in via three independent setup steps spread across docs.

Scope

1. Extend /setup with an LSP step

After the existing Step 2a (privacy gate) and Step 2b (split-portfolio mode), add a new step:

Step 2c — LSP enablement (recommended)

LSP-aware code navigation makes /code-review, /threat-model,
/security-review, and /handover deep-dives 3-15× cheaper in token cost
on semantic queries (find-definition, walk-references, etc).

Enable LSP now? This will:
  - Install the LSP plugin for Claude Code (one-shot, ~5 sec)
  - Detect the project's language and install the right server
    (TypeScript: typescript-language-server via npm; Python: pyright;
    Go: gopls; Rust: rust-analyzer via rustup)
  - Set ENABLE_LSP_TOOL=1 in your shell rc

Skip if:
  - You're on a constrained machine (cold-start can be 30+s on
    large repos)
  - Your workflow is metadata-only (you only run /handover, /inbox,
    /status — these don't benefit from LSP)
  - You want to install per-language servers selectively later

[y / n / "y, but ask before installing"]

2. Language detection

From the operator's earlier /setup description (Step 2 — "tell me about your company and tech stack"), extract languages. Examples:

• "TypeScript + React" → install typescript-language-server
• "Python + FastAPI" → install pyright
• "Go" → install gopls
• "Rust" → rust-analyzer comes with rustup (often pre-installed)

If multiple languages mentioned (polyglot stack), offer multi-install. If none clearly detected, ask which to install.

3. Installation steps

For TypeScript (most common in apexyard adopters):

# Check if Node is available first (refuse gracefully if not)
command -v npm >/dev/null || { echo "npm not found — install Node first then re-run /setup"; return 1; }

# Install the language server globally
npm install -g typescript typescript-language-server

For Python:

command -v pip3 >/dev/null || command -v pipx >/dev/null || { echo "pip3 / pipx not found — install Python first"; return 1; }
pipx install pyright || pip3 install --user pyright

For Go / Rust: similar pattern using go install / rustup component add.

4. Env var setup

Detect the operator's shell + rc file:

case "$SHELL" in
  */zsh)  RC_FILE=~/.zshrc ;;
  */bash) RC_FILE=~/.bashrc ;;
  *)      RC_FILE=~/.profile ;;
esac

if ! grep -q 'ENABLE_LSP_TOOL=1' "$RC_FILE" 2>/dev/null; then
  echo "" >> "$RC_FILE"
  echo "# ApexYard: enable Claude Code's LSP tool for semantic code navigation" >> "$RC_FILE"
  echo "export ENABLE_LSP_TOOL=1" >> "$RC_FILE"
  echo "  Added ENABLE_LSP_TOOL=1 to $RC_FILE. Open a new shell or run: source $RC_FILE"
fi

5. Claude Code plugin install

Use the Claude Code plugin marketplace command (exact syntax to verify against v2.1+ docs):

# Pseudo-command — verify in the spike's Phase 2 plugin-marketplace findings
claude plugin install lsp-typescript  # or equivalent per the marketplace shape

If the plugin manager isn't yet stable / scriptable, fall back to printing the manual install command and asking the operator to run it.

6. Verification

After install, run a smoke test:

# Verify the binary is on PATH
command -v typescript-language-server >/dev/null && echo "✓ typescript-language-server installed"

# Verify the env var is set in the operator's CURRENT shell (only matters for next session)
echo "ℹ Next Claude Code session will use LSP. Current session won't (env var not yet exported)."

7. Opt-out + machine-spec heuristic

For machines that are clearly constrained:

# Quick capability check before defaulting to "y"
CORES=$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 0)
RAM_GB=$(awk '/MemTotal/ {print int($2/1024/1024)}' /proc/meminfo 2>/dev/null || sysctl -n hw.memsize 2>/dev/null | awk '{print int($1/1024/1024/1024)}' || echo 0)

if [ "$CORES" -lt 4 ] || [ "$RAM_GB" -lt 8 ]; then
  echo "Your machine has $CORES cores / ${RAM_GB}GB RAM — LSP cold-start on large repos can be slow here. Default: skip. Override with explicit 'y'."
  DEFAULT="n"
else
  DEFAULT="y"
fi

Acceptance Criteria

• /setup includes an LSP enablement step (Step 2c) after the privacy gate.
• Language detection works for at least 4 languages: TypeScript, Python, Go, Rust.
• Language-server install commands run cleanly on macOS + Linux (gracefully refuse on Windows for v1; track Windows support as a follow-up).
• ENABLE_LSP_TOOL=1 written to the operator's shell rc (idempotent — skip if already present).
• Claude Code LSP plugin installed via marketplace (or clear manual instruction if scriptable install isn't supported yet).
• Smoke test confirms the language server is on PATH.
• Machine-spec heuristic defaults to "skip" on constrained hardware (< 4 cores OR < 8GB RAM).
• Re-running /setup is idempotent — detects existing LSP install + skips re-install.
• Existing /setup adopters can run /setup --enable-lsp to retrofit LSP without re-running the full bootstrap.
• Doc note in docs/getting-started.md § "LSP" — points at /setup as the easy path; manual install steps remain as a fallback.

Risks / Dependencies

• Plugin marketplace scriptable install — verify that Claude Code v2.1+ supports claude plugin install <name> as a real command. If not, this ticket can only get partway (env var + language server install + manual plugin-install prompt). Spike Phase 2 of [Spike] Measure token savings of LSP-based code navigation + clone-first /handover #178 verified the plugin system exists; install ergonomics need confirmation.
• System package managers — npm install -g requires Node; pip requires Python; etc. For each install, refuse gracefully if the prerequisite is missing rather than auto-installing Node/Python.
• Shell rc detection on Windows — out of scope for v1. Windows PowerShell adopters get a manual instruction.
• Operator overrides — /setup --skip-lsp opts out at the step.
• Constrained machines — capability check is heuristic, not infallible. The operator can always override.

Out of scope

• Bundling language servers in the framework. Per-machine install is the right shape; framework doesn't ship binaries.
• Auto-detection of polyglot repos (e.g. TS frontend + Go backend). v1 asks for primary language; v2 can scan workspace/* for additional languages.
• Per-skill LSP toggles. Already covered by the LSP-aware annotations from [Docs] Annotate code-aware skills (/code-review, /threat-model, /security-review, /handover) with LSP-aware callouts #190.

Refs

• Predecessor: [Spike] Measure token savings of LSP-based code navigation + clone-first /handover #178 (LSP spike) → PR docs(#178): LSP integration spike — measurement + recommendation #184 — concluded GO with manual setup
• Predecessor: [Docs] Document ENABLE_LSP_TOOL opt-in + per-language plugin install #189 → PR docs(#189): document ENABLE_LSP_TOOL + per-language LSP plugin install #193 — documented manual setup
• Predecessor: [Docs] Annotate code-aware skills (/code-review, /threat-model, /security-review, /handover) with LSP-aware callouts #190 → PR docs(#190): annotate LSP-aware skills with opt-in callouts #191 — annotated 4 skills as LSP-aware
• Adjacent: [Spike] Measure local-model routing for bounded sub-tasks (issue classify, commit-type suggest, inbox summary) #195 / [Feature] Spike: Claude Opus/Sonnet/Haiku model-tier routing for bounded sub-tasks (sibling to #195) #197 (local-model + Claude tier-routing spikes) — same "framework recommends optimization, adopter has to opt in" pattern; if this ticket lands, do the same for local-LLM via /setup --enable-local-models
• Closes the gap between "framework recommends LSP" and "framework actually enables LSP for adopters"