litclaude-ai 0.3.1 → 0.3.6

package/plugins/litclaude/skills/init-deep/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: init-deep
+description: "Initialize a hierarchical AGENTS.md knowledge base for a repository — a root AGENTS.md plus complexity-scored subdirectory files. Use when the user wants to bootstrap or refresh project knowledge for Claude Code, onboard a codebase, generate AGENTS.md/CLAUDE.md guidance, or map an unfamiliar repo. Adapted for the Claude Code host: discovery via background explore subagents + the LSP tool, parallel generation via Dynamic workflow."
+---
+
+# Init-Deep — hierarchical AGENTS.md generator (Claude Code)
+
+Generate hierarchical `AGENTS.md` files: a root knowledge base plus complexity-scored subdirectory
+files. This is the LitClaude onboarding/knowledge-base skill, re-authored for Claude Code surfaces
+(`Agent`/`Task` subagents, the `LSP` tool, `Workflow` for parallel generation, `TodoWrite`).
+
+## Usage
+
+```
+init-deep                 # Update mode: modify existing AGENTS.md + create new where warranted
+init-deep --create-new    # Read existing → remove all → regenerate from scratch
+init-deep --max-depth=2   # Limit directory depth (default: 3)
+```
+
+## Workflow (high level)
+
+1. **Discovery + analysis** (concurrent) — background explore subagents + local bash structure + LSP
+   codemap + read existing AGENTS.md.
+2. **Score & decide** — determine AGENTS.md locations from merged findings.
+3. **Generate** — root first, then subdirectories in parallel.
+4. **Review** — deduplicate, trim, validate.
+
+Track all four phases with `TodoWrite` and flip each `pending → in_progress → completed` in real time.
+
+## Phase 1 — Discovery + analysis (concurrent)
+
+Mark "discovery" in_progress.
+
+### Fire background explore subagents immediately
+
+Spawn read-only explore subagents with the `Agent` tool (`subagent_type: "explore"`,
+`run_in_background: true`) so they run while the main session works. Claude notifies you when each
+finishes; collect their final messages before scoring. Launch independent agents in one message so
+they run concurrently. Suggested lanes (one agent each):
+
+- **Structure** — predict standard patterns for the detected language; report deviations only.
+- **Entry points** — find main/entry files; report non-standard organization.
+- **Conventions** — find config files (`.eslintrc`, `pyproject.toml`, `.editorconfig`, …); report
+  project-specific rules.
+- **Anti-patterns** — find `DO NOT` / `NEVER` / `ALWAYS` / `DEPRECATED` markers; list forbidden patterns.
+- **Build/CI** — find `.github/workflows`, `Makefile`, `Taskfile`; report non-standard patterns.
+- **Tests** — find test configs and structure; report unique conventions.
+
+**Dynamic subagent scaling** — after the bash pass below, spawn ADDITIONAL explore agents based on
+project scale (never a static count):
+
+| Factor | Threshold | Additional agents |
+|--------|-----------|-------------------|
+| Total files | >100 | +1 per 100 files |
+| Total lines | >10k | +1 per 10k lines |
+| Directory depth | ≥4 | +2 for deep exploration |
+| Large files (>500 lines) | >10 files | +1 for complexity hotspots |
+| Monorepo | detected | +1 per package/workspace |
+| Multiple languages | >1 | +1 per language |
+
+```bash
+total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
+total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
+large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {c++} END {print c+0}')
+max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)
+```
+
+For very broad repos, run the discovery fan-out as a Dynamic workflow (call the `Workflow` tool when
+Claude Code exposes it) instead of many manual `Agent` calls.
+
+### Main session: concurrent local analysis
+
+While background agents run, the main session does:
+
+**1. Bash structural analysis**
+```bash
+# Directory depth distribution
+find . -type d -not -path '*/.*' -not -path '*/node_modules/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c
+# Files per directory (top 30)
+find . -type f -not -path '*/.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30
+# Existing knowledge bases
+find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null
+```
+
+**2. Read existing AGENTS.md** — for each file found, `Read` it and extract key insights,
+conventions, and anti-patterns into an EXISTING map. With `--create-new`, read ALL existing files
+first (preserve context), THEN delete, THEN regenerate.
+
+**3. LSP codemap (if available)** — use the Claude `LSP` tool: list configured servers, then request
+document symbols for entry points and workspace symbols for `class` / `interface` / `function`, and
+references for the top exports to gauge centrality. If no server is configured, fall back to the
+explore subagents + plain search.
+
+Merge bash + LSP + existing + explore findings. Mark "discovery" completed.
+
+## Phase 2 — Scoring & location decision
+
+Mark "scoring" in_progress.
+
+### Scoring matrix
+
+| Factor | Weight | High threshold | Source |
+|--------|--------|----------------|--------|
+| File count | 3× | >20 | bash |
+| Subdir count | 2× | >5 | bash |
+| Code ratio | 2× | >70% | bash |
+| Unique patterns | 1× | has own config | explore |
+| Module boundary | 2× | has `index.ts`/`__init__.py` | bash |
+| Symbol density | 2× | >30 symbols | LSP |
+| Export count | 2× | >10 exports | LSP |
+| Reference centrality | 3× | >20 refs | LSP |
+
+### Decision rules
+
+| Score | Action |
+|-------|--------|
+| Root (`.`) | ALWAYS create |
+| >15 | Create AGENTS.md |
+| 8–15 | Create if it is a distinct domain |
+| <8 | Skip (parent covers it) |
+
+Mark "scoring" completed.
+
+## Phase 3 — Generate AGENTS.md
+
+Mark "generate" in_progress.
+
+**File-writing rule:** if `AGENTS.md` already exists at the target path, use `Edit`; if not, use
+`Write`. NEVER `Write` over an existing file — check existence first (via the discovery results or a
+`Read`).
+
+### Root AGENTS.md (full treatment)
+
+```markdown
+# PROJECT KNOWLEDGE BASE
+**Generated:** {TIMESTAMP}  **Commit:** {SHORT_SHA}  **Branch:** {BRANCH}
+
+## OVERVIEW
+{1–2 sentences: what + core stack}
+
+## STRUCTURE
+{tree with non-obvious purposes only}
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+
+## CODE MAP
+{from LSP — skip if unavailable or project <10 files}
+
+## CONVENTIONS
+{ONLY deviations from standard}
+
+## ANTI-PATTERNS (THIS PROJECT)
+{explicitly forbidden here}
+
+## COMMANDS
+{dev / test / build}
+
+## NOTES
+{gotchas}
+```
+
+Quality gate: 50–150 lines, no generic advice, no obvious info.
+
+### Subdirectory AGENTS.md (parallel)
+
+Generate each non-root location in parallel — spawn one writing subagent per location with the `Agent`
+tool, or run them as a Dynamic workflow. Each child gets a `TASK:` line plus `DELIVERABLE` (the
+AGENTS.md), `SCOPE` (this directory only), and `VERIFY` (30–80 lines, never repeats parent content;
+sections: OVERVIEW 1 line, STRUCTURE if >5 subdirs, WHERE TO LOOK, CONVENTIONS if different,
+ANTI-PATTERNS). Wait for all. Mark "generate" completed.
+
+## Phase 4 — Review & deduplicate
+
+Mark "review" in_progress. For each generated file: remove generic advice, remove parent duplicates,
+trim to the size limits, verify telegraphic style. Mark "review" completed.
+
+## Final report
+
+```
+=== init-deep complete ===
+Mode: {update | create-new}
+Files: [OK] ./AGENTS.md (root, {N} lines) · [OK] ./src/hooks/AGENTS.md ({N} lines)
+Dirs analyzed: {N} · Created: {N} · Updated: {N}
+Hierarchy: ./AGENTS.md └── src/hooks/AGENTS.md
+```
+
+## Anti-patterns
+
+- **Static agent count** — vary explore subagents by project size/depth (see the scaling table).
+- **Sequential execution** — run explore + LSP concurrently; generate subdirectories in parallel.
+- **Ignoring existing** — ALWAYS read existing AGENTS.md first, even with `--create-new`.
+- **Over-documenting** — not every directory needs an AGENTS.md.
+- **Redundancy** — a child file never repeats its parent.
+- **Generic content** — remove anything that applies to all projects.
+- **Verbose style** — telegraphic or die.

package/plugins/litclaude/skills/lit-loop/SKILL.md

@@ -39,16 +39,18 @@ Before implementation:
 
 ## Native Goal + Dynamic Workflow
 
-Use Claude Code's native goal surface when available:
-
-- If model-facing tools exist, call `get_goal`, call `create_goal` only when no
-  matching active goal exists, and call `update_goal` only after every success
-  criterion has evidence or the work is genuinely blocked.
-- If the user chooses `/goal`, treat it as the native Claude Code session goal.
-  LitClaude must not auto-type or send `/goal` text.
-- If model-facing goal tools are not exposed, continue quietly with the local
-  evidence ledger. Mention `/goal <completion condition>` only when it helps a
-  long-running task; do not spam fallback status.
+Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command** that sets an autonomous
+completion condition; a hook or skill **cannot invoke it**, and Claude Code exposes no
+model-facing goal tools today. Bind goals like this:
+
+- When a goal is worth binding, **propose a concrete, ready-to-paste `/goal <completion
+  condition>`** for the user, and keep driving the local evidence ledger meanwhile. LitClaude
+  must not auto-type or send `/goal` text.
+- Forward-compat only: if a future Claude Code build exposes model-facing goal tools, prefer
+  them — call `get_goal`, call `create_goal` only when no matching active goal exists, and call
+  `update_goal` only after every success criterion has evidence or the work is genuinely blocked.
+- While model-facing goal tools are not exposed (the case today), the local litgoal ledger is the
+  durable record; surface the `/goal` proposal for long-running goals and don't spam fallback status.
 
 Dynamic workflow orchestration is mandatory for broad, risky, parallel, or
 long-running work: call `Workflow` when exposed instead of merely mentioning it.

package/plugins/litclaude/skills/lit-plan/SKILL.md

@@ -44,16 +44,15 @@ and do not pretend the skill can silently execute it.
 
 ## Native Goal + Dynamic Workflow
 
-Include native goal handling:
-
-- If model-facing goal tools are exposed, call `get_goal`, create with
-  `create_goal` only when no matching active goal exists, and delay
-  `update_goal` until verified completion or a real blocker.
-- If goal tools are not exposed, plan a quiet local ledger and a user-visible
-  `/goal <completion condition>` option instead of claiming native activation.
-- If only the `/goal` UI surface is available, include an exact
-  `/goal <completion condition>` line for the user or wrapper to run.
-- Do not auto-type or send `/goal` text from a skill.
+Include native goal handling. Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command**,
+not a model-facing tool, and a hook/skill **cannot invoke it**:
+
+- Include an exact, ready-to-paste `/goal <completion condition>` line in the plan for the user to
+  run — this is the real way to bind the native goal — plus a quiet local ledger for tracking.
+- Forward-compat only: if a future Claude Code build exposes model-facing goal tools, call
+  `get_goal`, create with `create_goal` only when no matching active goal exists, and delay
+  `update_goal` until verified completion or a real blocker. These goal tools are not exposed today.
+- Do not auto-type or send `/goal` text from a skill, and never claim native activation without evidence.
 
 For broad, risky, parallel, or long-running implementation, include Dynamic workflow
 and Dynamic worktree instructions:

package/plugins/litclaude/skills/litgoal/SKILL.md

@@ -50,11 +50,47 @@ Represent every litgoal run as:
 - checkpoint history
 - final quality gate
 
-If model-facing goal tools are exposed, inspect them before creating a new
-active goal. Treat `/goal` as a user-visible Claude Code slash command. Never
-auto-type `/goal`, never claim slash-command activation without evidence, and
-never mark a goal complete through native goal tooling until the local
-litgoal criteria have passed.
+### Binding the native Claude Code goal
+
+Claude Code's `/goal` (v2.1.139+) is a **user-typed slash command** that sets an autonomous
+completion condition; it is **not a model-facing tool**, and a hook or skill **cannot invoke
+it**. So when this skill activates, derive the objective into a crisp completion condition and
+**offer the user a ready-to-paste `/goal <completion condition>`** (e.g. ``/goal all litgoal
+criteria pass and `litclaude litgoal status` shows complete``). Then keep the durable record in
+the local litgoal ledger. Never auto-type `/goal`, never claim slash-command activation without
+evidence, and never mark a goal complete until the local litgoal criteria have passed.
+
+Forward-compat only: if a future Claude Code build exposes model-facing goal tools, inspect
+`get_goal` before creating a new active goal, use `create_goal` for the objective, and
+`update_goal` only on verified completion. These are not exposed today — the `/goal` proposal is
+the actual mechanism.
+
+### Autoloop — a plugin-controlled `/goal`-equivalent (no `/goal` typing)
+
+LitClaude ships its own **`Stop` hook** that reproduces `/goal`'s keep-running behavior **under
+plugin control**, driven by this ledger — so an autonomous completion loop can start without the
+user typing `/goal`. Opt in per goal:
+
+```bash
+litclaude-ai litgoal create-goals --brief "<objective>" --autoloop --json
+```
+
+This sets `autoloop: true` on the goal. On every Stop event the LitClaude Stop hook reads
+`.litclaude/litgoal/goals.json` and, while any criterion is not `pass`, returns `decision: block`
+with a snapshot of the remaining criteria — Claude keeps working and advancing them with
+`record-evidence` until **all criteria pass**, at which point the hook allows the session to stop.
+Completion is **deterministic** (a pure function of recorded evidence), so it cannot be faked.
+
+Safety (the loop can never trap a session):
+- **Default off** — only the explicit `--autoloop` flag arms the hook; ordinary goals never block.
+- **Hard cap** — a durable counter at `.litclaude/litgoal/autoloop.json` stops the loop after
+  8 blocks or 30 minutes (emits `continue:false`); if the counter can't be written, the hook
+  fails safe and allows stopping.
+- **Escape hatches** — `LITCLAUDE_GOAL_OFF=1` (env kill switch), or
+  `litclaude-ai litgoal checkpoint --status blocked` / `--status complete` to end the loop.
+
+Prefer `--autoloop` when the user wants hands-off autonomous completion of a multi-criteria goal;
+otherwise the user-typed `/goal` proposal above remains available and they compose cleanly.
 
 ## Bootstrap
 

package/plugins/litclaude/skills/lsp-setup/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: lsp-setup
+description: "Configure a Language Server (LSP) for a specific language so Claude Code tooling — diagnostics, go-to-definition, find-references, rename — works in LitClaude. Use when you need to set up or install a language server, fix 'no LSP server configured' / 'server not installed', choose between servers (basedpyright vs pyright vs ruff), or add a language to plugins/litclaude/.lsp.json. Routes by file extension to references/<language>/README.md for the server choice, per-OS install commands, the .lsp.json config snippet, and troubleshooting. Ships scripts: detect-lsp.ts (scan a project for languages + report each server's install/config status against .lsp.json) and verify-lsp.ts (real diagnostics roundtrip). Covers typescript, python, go, rust, c/c++, java, kotlin, c#/razor, swift, ruby, php, dart, elixir, zig, lua, bash, yaml, terraform, haskell, julia."
+---
+
+# LSP Setup
+
+Configure the right Language Server for a project so Claude Code's LSP tools
+(`diagnostics`, `goto_definition`, `find_references`, `symbols`, `rename`)
+actually work in LitClaude. This skill is an index: detect what a project needs,
+install the server, declare it in `plugins/litclaude/.lsp.json`, then verify with
+a real diagnostics roundtrip.
+
+This is the multi-language configurator. For a quick post-edit diagnostics pass
+on an already-configured language, use the lighter `lsp` skill instead — `lsp` is
+the quick path, `lsp-setup` is the configurator that wires new languages in.
+
+The recommended server per language is the source of truth in
+`scripts/lsp-server-table.ts`; each `references/<language>/README.md` mirrors it.
+
+## Runtime
+
+The scripts are dependency-free TypeScript. Run them with either:
+
+- **Node 22.6+:** `node --experimental-strip-types scripts/detect-lsp.ts <dir>`
+- **Bun:** `bun scripts/detect-lsp.ts <dir>`
+
+No `npm install` is required; the scripts import only Node built-ins and the
+embedded `lsp-server-table.ts`.
+
+## Phase 0 — Language Gate (run first)
+
+Identify the language from the file extension, then read the matching reference
+before installing or configuring anything.
+
+| Extension(s) | Reference |
+|---|---|
+| `.ts .tsx .js .jsx .mjs .cjs .mts .cts` | `references/typescript/README.md` |
+| `.py .pyi` | `references/python/README.md` |
+| `.go` | `references/go/README.md` |
+| `.rs` | `references/rust/README.md` |
+| `.c .cpp .cc .cxx .h .hpp .hh .hxx` | `references/c-cpp/README.md` |
+| `.java` | `references/java/README.md` |
+| `.kt .kts` | `references/kotlin/README.md` |
+| `.cs .razor .cshtml` | `references/csharp/README.md` |
+| `.swift` | `references/swift/README.md` |
+| `.rb .rake .gemspec .ru` | `references/ruby/README.md` |
+| `.php` | `references/php/README.md` |
+| `.dart` | `references/dart/README.md` |
+| `.ex .exs` | `references/elixir/README.md` |
+| `.zig .zon` | `references/zig/README.md` |
+| `.lua` | `references/lua/README.md` |
+| `.sh .bash .zsh .ksh` | `references/bash/README.md` |
+| `.yaml .yml` | `references/yaml/README.md` |
+| `.tf .tfvars` | `references/terraform/README.md` |
+| `.hs .lhs` | `references/haskell/README.md` |
+| `.jl` | `references/julia/README.md` |
+
+## Workflow — detect, install, configure, verify
+
+### 1. Detect
+
+Scan the project to see which languages are present and whether each server is
+installed and already declared in `.lsp.json`:
+
+```bash
+node --experimental-strip-types scripts/detect-lsp.ts <projectDir>
+node --experimental-strip-types scripts/detect-lsp.ts <projectDir> --json
+```
+
+For each detected language it prints the recommended server, the executable it
+needs on `PATH`, whether that executable is installed, an install hint, and
+whether `plugins/litclaude/.lsp.json` already declares the language. Use
+`--config=<path>` to point at a different `.lsp.json` copy.
+
+### 2. Install
+
+Open `references/<language>/README.md` and run the install command for your OS,
+then confirm the executable resolves:
+
+```bash
+command -v <server-executable>   # e.g. typescript-language-server, gopls, rust-analyzer
+```
+
+### 3. Configure (LitClaude `.lsp.json`)
+
+LitClaude declares servers in `plugins/litclaude/.lsp.json`. The schema is keyed
+by **language name**; each entry holds a `command` array and an
+`extensionToLanguage` map that tells Claude Code which file extensions route to
+that server:
+
+```json
+{
+  "<language>": {
+    "command": ["<bin>", "<arg>"],
+    "extensionToLanguage": {
+      ".ext": "<languageId>"
+    }
+  }
+}
+```
+
+Rules:
+
+- One entry per server, keyed by language name. The `command` is the full argv.
+- `extensionToLanguage` maps each owned extension to the LSP `languageId`. Claude
+  Code resolves the server for an edited file by matching its extension here.
+- The shipped default declares only `typescript`. Add a language by copying the
+  block from its reference README into `.lsp.json`.
+- Server-specific tuning (schemas, licence keys, check commands) travels through
+  the editor's LSP `initializationOptions` or a project config file (for example
+  `.clangd`, `.rubocop.yml`, `pyrightconfig.json`), not through `.lsp.json`.
+
+If a language also needs an MCP wiring (for example a server exposed through an
+MCP stdio bridge rather than a direct binary), declare that bridge in `.mcp.json`
+and keep `.lsp.json` pointed at the resulting command. Most servers here are
+direct binaries and need only `.lsp.json`.
+
+Each language reference gives a ready-to-paste `.lsp.json` snippet.
+
+### 4. Verify
+
+Run a real diagnostics roundtrip against a source file. The script resolves the
+server for the file extension (from `.lsp.json` when present, else the embedded
+table), spawns it, runs the JSON-RPC `initialize` -> `initialized` -> `didOpen`
+handshake over stdio, waits for `textDocument/publishDiagnostics`, and reports:
+
+```bash
+node --experimental-strip-types scripts/verify-lsp.ts <path/to/file.ext>
+node --experimental-strip-types scripts/verify-lsp.ts <file> --timeout=90000
+```
+
+`OK` = the server started and answered with diagnostics. `FAIL: language server
+not installed` = go back to step 2. Other `FAIL` text carries the server or
+timeout error. `SKIP` = no server is known for that extension; add one via the
+reference and `.lsp.json`. Exit codes: 0 OK, 1 FAIL, 2 usage, 3 SKIP.
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `scripts/detect-lsp.ts` | Scan a directory; per detected language report the recommended server, install status, install hint, and whether `.lsp.json` declares it. `--json` for machine output, `--config=<path>` to target a config. |
+| `scripts/verify-lsp.ts` | Real LSP diagnostics roundtrip for one file over stdio JSON-RPC; `OK`/`FAIL`/`SKIP` + exit code 0/1/2/3. Dependency-free. |
+| `scripts/lsp-server-table.ts` | Embedded snapshot of the recommended server per language, mirrored by the references. |
+
+## When LSP tooling is unavailable
+
+If Claude Code does not expose LSP tools and a server is not installed, do not
+fabricate a passing diagnostics result. Fall back to the project's own commands
+(`tsc --noEmit`, `ruff`, `cargo check`, `go test`, etc.), label the LSP gap as a
+controlled skip, and report it — consistent with the `lsp` skill's failure rules.

package/plugins/litclaude/skills/lsp-setup/references/bash/README.md

@@ -0,0 +1,63 @@
+# Bash — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `bash-language-server start`
+- **Extensions:** `.sh .bash .zsh .ksh`
+- **Install hint:** `npm install -g bash-language-server`
+
+## Install
+
+- **macOS:** `npm install -g bash-language-server`
+- **Linux:** `npm install -g bash-language-server`
+- **Windows:** `npm install -g bash-language-server` (PowerShell)
+
+For real diagnostics, also install `shellcheck`:
+
+- **macOS:** `brew install shellcheck`
+- **Linux:** `apt install shellcheck` (or `dnf install ShellCheck`)
+- **Windows:** `scoop install shellcheck`
+
+Confirm it resolves:
+
+```bash
+command -v bash-language-server
+command -v shellcheck
+```
+
+## Configure
+
+Add a `bash` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "bash": {
+    "command": ["bash-language-server", "start"],
+    "extensionToLanguage": {
+      ".sh": "shellscript",
+      ".bash": "shellscript",
+      ".zsh": "shellscript",
+      ".ksh": "shellscript"
+    }
+  }
+}
+```
+
+Claude Code routes these extensions to `bash-language-server` via the map.
+`bash-language-server` discovers `shellcheck` on PATH automatically; to point at a
+non-PATH binary, export `SHELLCHECK_PATH` in the launching shell.
+
+## Alternatives
+
+- `shellcheck` standalone as a linter-only flow (no LSP).
+- `shfmt` for formatting (complements, does not replace, the LSP).
+
+## Troubleshooting
+- **PATH:** `bash-language-server` on PATH; reopen shell after `npm -g` install.
+- **No diagnostics:** `shellcheck` missing — diagnostics are powered by it; install and reopen.
+- **Wrong shell dialect:** `.zsh`/`.ksh` are linted as bash; shellcheck may flag shell-specific syntax.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.sh
+# or: bun ../../scripts/verify-lsp.ts path/to/file.sh
+```

package/plugins/litclaude/skills/lsp-setup/references/c-cpp/README.md

@@ -0,0 +1,72 @@
+# C / C++ — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `clangd --background-index --clang-tidy`
+- **Extensions:** `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++`
+- **Install hint:** `https://clangd.llvm.org/installation`
+
+## Install
+
+- **macOS:** `brew install llvm` (clangd ships in the LLVM keg; add its `bin` to PATH)
+- **Linux:** `apt install clangd` (Debian/Ubuntu); use your distro package elsewhere
+- **Windows:** install LLVM from `https://releases.llvm.org` or `winget install LLVM.LLVM`
+
+See `https://clangd.llvm.org/installation` for other platforms.
+
+Confirm it resolves:
+
+```bash
+command -v clangd
+```
+
+## Configure
+
+Add a `c-cpp` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "c-cpp": {
+    "command": ["clangd", "--background-index", "--clang-tidy"],
+    "extensionToLanguage": {
+      ".c": "c",
+      ".h": "c",
+      ".cpp": "cpp",
+      ".cc": "cpp",
+      ".cxx": "cpp",
+      ".hpp": "cpp",
+      ".hh": "cpp",
+      ".hxx": "cpp"
+    }
+  }
+}
+```
+
+Claude Code routes these extensions to `clangd` via the map. clangd reads
+build flags from a project `.clangd` file, not from `.lsp.json`; the `command`
+above already passes `--background-index --clang-tidy`.
+
+## Compile commands
+
+clangd needs a `compile_commands.json` at the project root (or in `build/`) for
+accurate diagnostics and cross-file navigation. Generate it with:
+
+- **CMake:** `cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` (symlink/copy `build/compile_commands.json` to the root)
+- **Make / other:** `bear -- make`
+
+Without it, clangd falls back to heuristic flags and reports spurious errors.
+
+## Alternatives
+
+`ccls` exists as a third-party server — set the `command` to `["ccls"]` in the
+`c-cpp` entry if you prefer it.
+
+## Troubleshooting
+- **PATH:** `clangd` must be on PATH; reopen shell after install. Homebrew LLVM is keg-only — add `$(brew --prefix llvm)/bin` to PATH.
+- **Spurious "file not found" / unknown flags:** missing or stale `compile_commands.json` — regenerate it after changing the build.
+- **Header-only diagnostics wrong:** ensure the header's translation unit appears in the compile database, or add a `.clangd` `CompileFlags` block.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.cpp
+# or: bun ../../scripts/verify-lsp.ts path/to/file.cpp
+```