cc-dev-template 0.1.79 → 0.1.81

package/src/skills/creating-sub-agents/references/create-step-5-install.md

@@ -75,6 +75,4 @@ Summarize what was created:
 - Memory scope (if any)
 - Skills preloaded (if any)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-step-6-reflect.md` now.
+Use the Read tool on `references/create-step-6-reflect.md` to reflect on the creation process and note any skill issues.

package/src/skills/creating-sub-agents/references/create-step-6-reflect.md

@@ -1,9 +1,5 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The sub-agent creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating this sub-agent. The purpose is to improve the creating-sub-agents skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/creating-sub-agents/references/fix-step-3-validate.md

@@ -51,6 +51,4 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the sub-agent now behaves as expected
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/fix-step-4-reflect.md` now.
+Use the Read tool on `references/fix-step-4-reflect.md` to reflect on the fix process and note any skill issues.

package/src/skills/creating-sub-agents/references/fix-step-4-reflect.md

@@ -1,9 +1,5 @@
 # Step 4: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The sub-agent fix workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience fixing this sub-agent. The purpose is to improve the creating-sub-agents skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/execute-spec/SKILL.md

@@ -1,4 +1,6 @@
 ---
+name: execute-spec
+description: Orchestrates implementation and validation of a spec's task breakdown by dispatching agents — never reads task files or edits code directly.
 allowed-tools: Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
 hooks:
   PreToolUse:
@@ -12,8 +14,6 @@ hooks:
 
 Orchestrates the implementation and validation of a spec's task breakdown.
 
-**Important**: This skill is an orchestrator only. It does NOT read task files or edit code directly. It dispatches agents and receives minimal status responses. All detailed work happens in the agents; all detailed findings live in the task files.
-
 ## When to Use
 
 Invoke when you have a complete spec with a `tasks/` folder containing task files (T001-*.md, T002-*.md, etc.) ready for implementation.
@@ -23,26 +23,18 @@ Invoke when you have a complete spec with a `tasks/` folder containing task file
 This skill takes a spec path as an argument:
 - `docs/specs/my-feature` - path to the spec folder containing `spec.md` and `tasks/`
 
-## Workflow
-
-Read `references/workflow.md` for the full orchestration flow.
-
-## Phases
-
-1. **Hydrate** - Run parse script, create tasks with dependencies (NO file reading)
-2. **Build** - Dispatch spec-implementer agents, receive minimal status
-3. **Validate** - Dispatch spec-validator agents, receive pass/fail
-4. **Triage** - Re-dispatch implementers for failed tasks, loop until clean
-5. **Reflect** - Assess orchestration experience, improve skill files (mandatory)
-
 ## Key Principles
 
-- **Never read task files** - Use the parse script for hydration, pass paths to agents
-- **Minimal context** - Agent returns are pass/fail only, details in task files
-- **Delegate everything** - Fixes go to spec-implementer, not done by orchestrator
+- **Never read task files** — Use the parse script for hydration, pass paths to agents. A PreToolUse hook blocks task file reads.
+- **Minimal context** — Agent returns are pass/fail only, details live in task files.
+- **Dispatch only** — All implementation and fixes go to spec-implementer agents, all validation to spec-validator agents. The orchestrator dispatches and collects status.
 
 ## Requirements
 
 - Spec folder must contain `spec.md` and `tasks/` directory
 - Task files must have YAML frontmatter with `id`, `title`, `status`, `depends_on`
 - The `spec-implementer` and `spec-validator` agents must be installed
+
+## Start
+
+Read `references/phase-1-hydrate.md` to begin the workflow.

package/src/skills/execute-spec/references/phase-1-hydrate.md

@@ -68,4 +68,7 @@ Maintain a mapping of task IDs (T001, T002) to Claude task system IDs.
 
 - All tasks in Claude Code task system
 - Dependencies configured
-- Ready for Phase 2
+
+## Next
+
+Use the Read tool on `references/phase-2-build.md` to start dispatching implementers.

package/src/skills/execute-spec/references/phase-2-build.md

@@ -25,8 +25,7 @@ Loop until all tasks complete:
      )
 
 4. Wait for completions:
-   - Agents mark tasks complete when done
-   - Poll TaskList periodically to check status
+   - Background agents will notify you when they finish — wait for their completion messages
    - As tasks complete, newly unblocked tasks become ready
 
 5. Repeat until no pending tasks remain
@@ -60,4 +59,7 @@ Build Progress:
 
 - All tasks implemented (or failed with notes)
 - Implementation Notes written to each task file
-- Ready for Phase 3: Validate
+
+## Next
+
+Use the Read tool on `references/phase-3-validate.md` to validate the implementations.

package/src/skills/execute-spec/references/phase-3-validate.md

@@ -29,9 +29,7 @@ Dispatch spec-validator agents for each completed task.
 
 4. Wait for all validators to complete
 
-5. Collect results:
-   - Read Review Notes from each task file
-   - Aggregate issues by severity
+5. Collect results from validator returns (pass/fail status only)
 ```
 
 ## Validator Behavior
@@ -69,4 +67,7 @@ Validation Results:
 
 - Validation complete for all tasks
 - Issues collected and categorized
-- Ready for Phase 4: Triage
+
+## Next
+
+Use the Read tool on `references/phase-4-triage.md` to process results and fix any failures.

package/src/skills/execute-spec/references/phase-4-triage.md

@@ -73,3 +73,7 @@ Phase completes when:
 1. All validators return "Pass: TXXX"
 2. User explicitly defers remaining issues
 3. Max retry limit reached (suggest user intervention)
+
+## Next
+
+Use the Read tool on `references/phase-5-reflect.md` to present final results to the user and reflect on the workflow.

package/src/skills/execute-spec/references/phase-5-reflect.md

@@ -1,8 +1,6 @@
 # Phase 5: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The execute-spec workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience orchestrating this spec execution. The purpose is to improve the execute-spec skill itself based on what you just learned.
+Reflect on your experience orchestrating this spec execution.
 
 ## Assess
 

package/src/skills/initialize-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: initialize-project
-description: Scaffold docs structure for Claude Code sessions. Use when starting a new project, when "docs/CURRENT_WORK.md is missing", or when user says "initialize this project" or "set up session tracking".
+description: Scaffold docs structure for Claude Code sessions. Use when starting a new project, when the project lacks docs/CURRENT_WORK.md, or when the user wants session tracking initialized.
 ---
 
 # Initialize Project
@@ -32,6 +32,4 @@ Report what was created:
 
 End with: "Run `/prime` to start a session."
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/reflect.md now.
+Use the Read tool on `references/reflect.md` to reflect on the setup and note any skill issues.

package/src/skills/initialize-project/references/reflect.md

@@ -1,9 +1,5 @@
 # Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The initialize-project workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill. The purpose is to improve the initialize-project skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/project-setup/references/step-5-verify.md

@@ -69,6 +69,4 @@ Tell the user:
 
 If everything passed, the setup is complete.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-6-reflect.md` now.
+Use the Read tool on `references/step-6-reflect.md` to reflect on the setup experience and note any skill issues.

package/src/skills/project-setup/references/step-6-reflect.md

@@ -1,9 +1,5 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The project setup workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience setting up this project. The purpose is to improve the project-setup skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompting
-description: Invoked when user says "review my prompt", "help me write a prompt", "improve this prompt", or "create a prompt for...". Guides prompt creation and improvement using Claude 4.x best practices.
+description: Guide prompt creation and improvement using Claude 4.x best practices. Use for reviewing existing prompts, creating new prompts, or improving prompt effectiveness.
 ---
 
 # Prompting

package/src/skills/prompting/references/create-reflect.md

@@ -1,9 +1,5 @@
 # Reflect on Prompt Creation
 
-**IMPORTANT: This step is mandatory. The prompt creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill to create the prompt. The purpose is to improve the prompting skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/references/create.md

@@ -58,6 +58,4 @@ Ask: "Does this capture what you need? Any adjustments?"
 
 Incorporate feedback until the user is satisfied.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-reflect.md` now.
+Use the Read tool on `references/create-reflect.md` to reflect on the prompt creation and note any skill issues.

package/src/skills/prompting/references/review-reflect.md

@@ -1,9 +1,5 @@
 # Reflect on Prompt Review
 
-**IMPORTANT: This step is mandatory. The prompt review workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill to review the prompt. The purpose is to improve the prompting skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/references/review.md

@@ -77,6 +77,4 @@ Ask: "Would you like me to adjust anything in the improved version?"
 
 Incorporate feedback and present updated version until the user is satisfied.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/review-reflect.md` now.
+Use the Read tool on `references/review-reflect.md` to reflect on the prompt review and note any skill issues.

package/src/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Deep research on unfamiliar paradigms, libraries, or patterns before implementation. Activates when the user says "research X", "how should we implement X", "best practices for X", or when spec-interview identifies research needs. Outputs to docs/research/ with YAML frontmatter.
+description: Deep research on unfamiliar paradigms, libraries, or patterns before implementation. Use when a topic needs investigation before coding, or when spec-interview identifies research needs. Outputs to docs/research/ with YAML frontmatter.
 ---
 
 # Research

package/src/skills/research/references/step-2-conduct-research.md

@@ -62,6 +62,4 @@ After writing the document:
 2. Summarize the key takeaways
 3. Return to the invoking context (spec-interview or user)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-3-reflect.md` now.
+Use the Read tool on `references/step-3-reflect.md` to reflect on the research process and note any skill issues.

package/src/skills/research/references/step-3-reflect.md

@@ -1,9 +1,5 @@
 # Step 3: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The research workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill. The purpose is to improve the research skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/setup-lsp/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: setup-lsp
+description: Set up LSP language servers for the current project. Use when the project needs code intelligence configured, or to verify an existing LSP setup. Pass "verify" argument after restart to confirm LSP is working.
+disable-model-invocation: true
+argument-hint: "[verify]"
+---
+
+# Setup LSP
+
+Configure LSP (Language Server Protocol) for the current project so Claude Code uses precise code intelligence instead of grep-based search.
+
+| Argument | Action |
+|----------|--------|
+| No argument | Read `references/step-1-scan.md` |
+| `verify` | Read `references/step-3-verify.md` |

package/src/skills/setup-lsp/references/lsp-registry.md

@@ -0,0 +1,148 @@
+# LSP Registry
+
+## Language Detection
+
+Detect languages by file extensions AND project config files. Config files are more reliable — a `go.mod` is definitive proof of Go usage; a stray `.go` file might not be.
+
+| Config File | Language |
+|-------------|----------|
+| `package.json`, `tsconfig.json`, `jsconfig.json` | TypeScript/JavaScript |
+| `pyproject.toml`, `setup.py`, `setup.cfg`, `requirements.txt`, `Pipfile` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java |
+| `*.csproj`, `*.sln` | C# |
+| `composer.json` | PHP |
+| `Package.swift` | Swift |
+| `build.gradle.kts` with `kotlin` | Kotlin |
+| `CMakeLists.txt`, `Makefile` with `.c`/`.cpp` | C/C++ |
+
+| Extension | Language |
+|-----------|----------|
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` | TypeScript/JavaScript |
+| `.py`, `.pyi` | Python |
+| `.go` | Go |
+| `.rs` | Rust |
+| `.java` | Java |
+| `.cs` | C# |
+| `.php` | PHP |
+| `.swift` | Swift |
+| `.kt`, `.kts` | Kotlin |
+| `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` | C/C++ |
+| `.lua` | Lua |
+
+## Language Server Details
+
+Each entry: plugin name, binary command, install command, and verification command.
+
+| Language | Plugin | Binary | Install | Verify |
+|----------|--------|--------|---------|--------|
+| TypeScript/JS | `typescript-lsp` | `typescript-language-server` | `npm i -g typescript-language-server typescript` | `which typescript-language-server` |
+| Python | `pyright-lsp` | `pyright-langserver` | `npm i -g pyright` | `which pyright-langserver` |
+| Go | `gopls-lsp` | `gopls` | `go install golang.org/x/tools/gopls@latest` | `which gopls` |
+| Rust | `rust-analyzer-lsp` | `rust-analyzer` | `rustup component add rust-analyzer` | `which rust-analyzer` |
+| Java | `jdtls-lsp` | `jdtls` | `brew install jdtls` | `which jdtls` |
+| C/C++ | `clangd-lsp` | `clangd` | `brew install llvm` | `which clangd` |
+| C# | `csharp-lsp` | `csharp-ls` | `dotnet tool install -g csharp-ls` | `which csharp-ls` |
+| PHP | `php-lsp` | `intelephense` | `npm i -g intelephense` | `which intelephense` |
+| Kotlin | `kotlin-lsp` | `kotlin-lsp` | Install from GitHub releases | `which kotlin-lsp` |
+| Swift | `swift-lsp` | `sourcekit-lsp` | Included with Xcode | `which sourcekit-lsp` |
+| Lua | `lua-lsp` | `lua-language-server` | Install from GitHub releases | `which lua-language-server` |
+
+## Plugin Naming Convention
+
+Plugins are referenced as `{plugin-name}@{marketplace}`. The official marketplace is `claude-plugins-official`.
+
+Example: `typescript-lsp@claude-plugins-official`
+
+## Known Issue: Official Marketplace Plugin Cache Bug
+
+As of early 2026, there is a known bug (GitHub #15148) where plugins installed from `claude-plugins-official` cache only a `README.md` — missing the `.lsp.json` server configuration. This can cause `"No LSP server available for file type"` errors.
+
+**Primary workaround:** Use the `Piebald-AI/claude-code-lsps` community marketplace, which properly structures plugins with `.lsp.json` files and supports additional languages (Ruby, PowerShell, HTML/CSS, Vue, etc.).
+
+```
+claude plugin marketplace add Piebald-AI/claude-code-lsps
+claude plugin install {plugin-name}
+```
+
+**Fallback workaround:** Manually create `.lsp.json` in the cached plugin directory. The `.lsp.json` format:
+
+```json
+{
+  "language-id": {
+    "command": "language-server-binary",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".ext": "language-id"
+    }
+  }
+}
+```
+
+Example for TypeScript (`~/.claude/plugins/cache/claude-plugins-official/typescript-lsp/1.0.0/.lsp.json`):
+
+```json
+{
+  "typescript": {
+    "command": "typescript-language-server",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact",
+      ".mts": "typescript",
+      ".cts": "typescript",
+      ".mjs": "javascript",
+      ".cjs": "javascript"
+    }
+  }
+}
+```
+
+Example for Python (`~/.claude/plugins/cache/claude-plugins-official/pyright-lsp/1.0.0/.lsp.json`):
+
+```json
+{
+  "python": {
+    "command": "pyright-langserver",
+    "args": ["--stdio"],
+    "extensionToLanguage": {
+      ".py": "python",
+      ".pyi": "python"
+    }
+  }
+}
+```
+
+Example for Go (`~/.claude/plugins/cache/claude-plugins-official/gopls-lsp/1.0.0/.lsp.json`):
+
+```json
+{
+  "go": {
+    "command": "gopls",
+    "args": [],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+## LSP Operations
+
+Claude Code's LSP tool provides these operations. All use the same `LSP` tool — the operation is chosen based on what the agent needs.
+
+| Operation | What It Does | Use When |
+|-----------|-------------|----------|
+| `workspaceSymbol` | Search for a symbol across the entire project | Finding where something is defined |
+| `goToDefinition` | Jump to the exact definition of a symbol | Navigating to source code |
+| `goToImplementation` | Find concrete implementations of interfaces | Understanding polymorphism |
+| `findReferences` | Find every usage of a symbol | Impact analysis before refactoring |
+| `hover` | Get type signature and docs for a symbol | Understanding types without reading files |
+| `documentSymbol` | List all symbols in a file | Getting an overview of a file's structure |
+| `incomingCalls` | Trace what calls a function | Understanding callers |
+| `outgoingCalls` | Trace what a function calls | Understanding dependencies |
+
+Not every language server supports every operation. If an operation returns no results, it may be unsupported for that language — fall back to Grep.

package/src/skills/setup-lsp/references/step-1-scan.md

@@ -0,0 +1,28 @@
+# Step 1: Scan the Codebase
+
+Determine which languages are used in this project and which LSP servers to install.
+
+## Detect Languages
+
+Read `references/lsp-registry.md` for the detection tables.
+
+1. Use Glob to check for config files first (they are definitive): `go.mod`, `Cargo.toml`, `package.json`, `tsconfig.json`, `pyproject.toml`, `setup.py`, `requirements.txt`, `pom.xml`, `build.gradle`, `*.csproj`, `*.sln`, `composer.json`, `Package.swift`, `CMakeLists.txt`
+2. Then check file extensions as a secondary signal: `.py`, `.ts`, `.go`, `.rs`, `.java`, `.cs`, `.php`, `.swift`, `.kt`, `.c`, `.cpp`, `.lua`
+3. Check existing LSP configuration — read `.claude/settings.json` if it exists to see what's already configured
+
+## Check Prerequisites
+
+Run `claude --version` to verify Claude Code version is 2.0.74 or later.
+
+## Present Findings
+
+Show the user:
+- Which languages were detected and how (config file vs extension)
+- Which LSP servers are recommended for each language
+- Which language server binaries are already installed (check with `which`)
+- Which Claude Code plugins are already installed (check `~/.claude/plugins/installed_plugins.json` if it exists)
+- Any languages detected but not supported by available LSP plugins
+
+Ask the user to confirm which LSPs to install. They may want to skip some languages.
+
+Use the Read tool on `references/step-2-install-configure.md` to install language server binaries and configure Claude Code plugins.

package/src/skills/setup-lsp/references/step-2-install-configure.md

@@ -0,0 +1,83 @@
+# Step 2: Install and Configure
+
+Read `references/lsp-registry.md` for install commands, plugin names, and known issues.
+
+## Install Language Server Binaries
+
+For each confirmed language, check if the binary is already installed (`which <binary>`). Install only what's missing using the install commands from the registry.
+
+Verify each installation succeeded by running the verify command from the registry.
+
+## Install and Enable Claude Code Plugins
+
+For each language, install the Claude Code plugin:
+
+```
+claude plugin install <plugin-name>
+```
+
+If this fails with "Plugin not found in any marketplace", update the marketplace catalog first:
+
+```
+claude plugin marketplace update claude-plugins-official
+```
+
+If plugins still fail or produce errors about missing LSP server configuration, follow the workaround in `references/lsp-registry.md` under "Known Issue: Official Marketplace Plugin Cache Bug" — try the Piebald-AI community marketplace, or manually create `.lsp.json` files using the examples in the registry.
+
+## Configure Project-Level Settings
+
+Create or update `.claude/settings.json` in the project root (NOT `~/.claude/settings.json`).
+
+Merge these settings, preserving any existing configuration:
+
+```json
+{
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  },
+  "enabledPlugins": {
+    "<plugin-name>@<marketplace>": true
+  }
+}
+```
+
+Add an `enabledPlugins` entry for each installed plugin. Use the correct marketplace name (either `claude-plugins-official` or `Piebald-AI/claude-code-lsps`).
+
+## Update CLAUDE.md
+
+Read the project's root `CLAUDE.md`. Append the following section if no LSP instructions exist yet. If LSP instructions already exist, update them to match this format.
+
+Tailor the snippet to the languages actually installed — list the language servers that were set up:
+
+```markdown
+## Code Intelligence (LSP)
+
+This project has LSP language servers configured for: [list languages].
+
+Prefer LSP over Grep/Read for code navigation — LSP returns exact, structural results instantly:
+
+| Task | LSP Operation |
+|------|--------------|
+| Find where a symbol is defined | `workspaceSymbol` or `goToDefinition` |
+| Find all usages of a symbol | `findReferences` |
+| Get type info without reading the file | `hover` |
+| List all symbols in a file | `documentSymbol` |
+| Find implementations of an interface | `goToImplementation` |
+| Trace callers/callees of a function | `incomingCalls` / `outgoingCalls` |
+
+Use Grep only for text/pattern searches (comments, strings, config values, regex patterns).
+
+After writing or editing code, check LSP diagnostics and fix type errors before proceeding.
+```
+
+## Tell the User to Restart
+
+LSP servers initialize at startup. The plugins just installed require a full restart of Claude Code to take effect.
+
+Tell the user:
+
+1. Exit Claude Code
+2. Restart Claude Code in this project directory
+3. Run `/setup-lsp verify` to confirm LSP is working
+
+Use the Read tool on `references/step-4-reflect.md` to reflect on the setup and capture any workarounds for future runs.

package/src/skills/setup-lsp/references/step-3-verify.md

@@ -0,0 +1,41 @@
+# Step 3: Verify LSP
+
+This step runs after the user restarts Claude Code and invokes `/setup-lsp verify`.
+
+## Check LSP is Available
+
+1. Read `.claude/settings.json` to confirm `ENABLE_LSP_TOOL` and `enabledPlugins` are set
+2. Try a `workspaceSymbol` search for a common symbol in the project (pick any function or class name visible in the codebase)
+
+If `workspaceSymbol` returns results, LSP is working.
+
+## Test Operations
+
+Run a quick smoke test — try 3-4 different LSP operations against real symbols in the codebase:
+
+- `workspaceSymbol` — search for a known class or function name
+- `documentSymbol` — list symbols in a file that clearly has functions/classes
+- `hover` — get type info on a symbol
+- `findReferences` — find usages of a commonly-used function
+
+Report which operations succeeded and which returned no results. Some operations may not be supported by all language servers — that's expected.
+
+## If LSP is Not Working
+
+Check these in order:
+
+1. **"LSP tool not available"** — `ENABLE_LSP_TOOL` is not set. Verify `.claude/settings.json` has it under `env`
+2. **"No server available for file type"** — the plugin is installed but its `.lsp.json` config is missing (known bug). Read `references/lsp-registry.md` under "Known Issue" for the manual `.lsp.json` fix
+3. **Plugin is disabled** — run `claude plugin list` to check status. Run `claude plugin enable <name>` if disabled
+4. **Binary not in PATH** — verify with `which <binary>`. The language server must be in PATH when Claude Code starts
+
+After fixing, the user needs to restart Claude Code again and re-run `/setup-lsp verify`.
+
+## Report Results
+
+Tell the user:
+- Which LSP servers are active
+- Which operations were tested and their results
+- Any operations that didn't work (with explanation)
+
+Use the Read tool on `references/step-4-reflect.md` to reflect on the setup and capture any workarounds for future runs.

package/src/skills/setup-lsp/references/step-4-reflect.md

@@ -0,0 +1,20 @@
+# Step 4: Reflect
+
+## Assess
+
+- Were any install commands wrong, outdated, or platform-specific in a way the registry didn't account for?
+- Did any plugin installations fail? What was the cause and fix?
+- Did the official marketplace plugin cache bug occur? Was the workaround effective?
+- Were there languages detected that had no available LSP plugin?
+- Did the CLAUDE.md snippet accurately reflect the operations that actually worked?
+- Was any step confusing, missing information, or in the wrong order?
+
+## Act
+
+If any instructions were wrong, incomplete, or misleading — identify the specific file, read it, and apply the fix.
+
+Apply the tribal knowledge test: only add information that a fresh Claude instance would not already know. Standard tool usage (npm install, which, etc.) does not need documenting. Workarounds for bugs, non-obvious configuration details, and platform-specific gotchas do.
+
+## Report
+
+Tell the user what you changed and why, or confirm that no updates were needed.