cc-dev-template 0.1.78 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/commands/done.md

@@ -1,5 +1,5 @@
 ---
-description: End a session - sync documentation and commit work
+description: End a session - sync documentation, commit, and push
 argument-hint: [next task]
 ---
 

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 user says "setup LSP", "configure LSP", "enable LSP", "install language servers", or "add code intelligence". Use "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.
+
+Read `references/step-2-install-configure.md`.

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

@@ -0,0 +1,85 @@
+# 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
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/step-4-reflect.md` now.

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

@@ -0,0 +1,43 @@
+# 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)
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/step-4-reflect.md` now.

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

@@ -0,0 +1,22 @@
+# Step 4: Reflect
+
+**IMPORTANT: This step is mandatory. The setup-lsp workflow is not complete until this step is finished. Do not skip this.**
+
+## 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.

package/src/skills/spec-to-tasks/SKILL.md

@@ -9,14 +9,15 @@ context: fork
 
 ## Workflow Overview
 
-This skill has 4 steps. **You must complete ALL steps before presenting to the user.**
+This skill has 5 steps. **You must complete ALL steps. Do not stop early or skip any step.**
 
 1. **Identify Spec** - Find and verify the spec file
 2. **Verify File Landscape** - Map files to acceptance criteria
 3. **Generate Tasks** - Create task files in `tasks/` directory
-4. **Review Tasks** - Invoke `task-review` skill to validate, fix issues
+4. **Review Tasks** - Run review checklist in a loop until no critical issues remain
+5. **Reflect** - Note any skill issues observed during this run
 
-Do NOT skip step 4. The review catches dependency errors and coverage gaps.
+Steps 4 and 5 are mandatory. The review loop in step 4 is automated — fix issues and re-check until clean, with no user input required.
 
 ## What To Do Now
 

package/src/skills/spec-to-tasks/references/step-3-generate.md

@@ -60,13 +60,10 @@ docs/specs/<name>/
 
 Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
 
-## REQUIRED: Run Review Before Presenting
+## Do NOT Present Results Yet
 
-**Do NOT present results to the user yet.** After generating task files, you MUST:
+You have generated task files but you are NOT done. The review step is next and it is mandatory.
 
-1. Read `references/step-4-review.md`
-2. Invoke the `task-review` skill to validate the breakdown
-3. Fix any critical issues found
-4. Only then present results (including any warnings)
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-This review step catches dependency errors, coverage gaps, and verification issues. Skipping it leads to broken task breakdowns that fail during implementation.
+Read `references/step-4-review.md` now.

package/src/skills/spec-to-tasks/references/step-4-review.md

@@ -1,50 +1,95 @@
 # Step 4: Review Task Breakdown
 
-**This step is REQUIRED.** Do not present results until review is complete.
+**IMPORTANT: This step is mandatory. The spec-to-tasks workflow is not complete until this step is finished. Do not skip this.**
 
-## Run Task Review
+You must review the generated tasks, fix any issues, and re-review until the breakdown is clean. This is fully automated — do not ask the user for input during this step.
 
-Invoke the task-review skill NOW:
+## Review Checklist
 
-```
-Skill(skill: "task-review", args: "<spec-name>")
-```
+Read every task file and the spec. Evaluate each area below. For each issue found, note the severity:
+- **Critical**: Must fix before proceeding
+- **Warning**: Should fix, but could proceed
+- **Note**: Minor suggestion
 
-Wait for the review to complete before proceeding.
+### 1. Coverage
 
-The review will check:
-- Coverage (all criteria have tasks)
-- Dependency order (tasks properly sequenced)
-- File plausibility (paths make sense)
-- Verification executability (concrete commands)
-- Task scope (appropriately sized)
-- Consistency (format, frontmatter)
+Compare acceptance criteria in the spec to tasks generated.
 
-## Handle Findings
+- Every acceptance criterion has exactly one corresponding task
+- No criteria were skipped or forgotten
+- No phantom tasks that don't map to a criterion
 
-The review returns findings categorized as Critical, Warning, or Note.
+**How to verify:** List each criterion from the spec's Acceptance Criteria section. For each, find the matching task file. Flag any orphans in either direction.
 
-**Critical issues**: Fix before proceeding. Update the affected task files.
+### 2. Dependency Order
 
-**Warnings**: Present to user with your recommendation (fix or skip).
+- Task file names sort in valid execution order (T001, T002, etc.)
+- Each task's `depends_on` references only earlier tasks
+- No circular dependencies
+- Foundation work comes before features that use it
 
-**Notes**: Mention briefly, no action required.
+### 3. File Plausibility
 
-## Present to User
+- File paths follow project conventions
+- Files to modify actually exist in the codebase
+- Files to create are in appropriate directories
+- No duplicate files across tasks (each file appears in exactly one task)
 
-After addressing critical issues, present:
+### 4. Verification Executability
 
-1. Number of tasks generated
-2. Task titles in dependency order
-3. Any warnings from the review (with recommendations)
-4. Offer to show task files or proceed to implementation
+- Verification is a specific command or script, not vague prose
+- Test file paths exist or will be created by the task
+- No "manually verify" without clear steps
+
+**Red flags:** "Verify it works correctly", "Check that the feature functions", test commands for files not listed in the task.
+
+### 5. Verification Completeness
+
+- Read the criterion text carefully — identify every distinct behavior or edge case mentioned
+- For each behavior, confirm there's a corresponding verification step
+- Flag any behaviors in the criterion that have no verification
+
+### 6. Dependency Completeness
+
+- If task X modifies a file, check if another task creates it — that task must be in X's depends_on
+- If task X uses a component/function/route, check if another task creates it — that task must be in X's depends_on
+
+### 7. Task Scope
+
+- No task touches more than ~10 files (consider splitting)
+- No trivially small tasks that could merge with related work
+- Each task produces a verifiable outcome
+
+### 8. Consistency
 
-If the user wants changes, update the task files and re-run the review.
+- Task titles match or closely reflect the acceptance criterion
+- Status is `pending` for all new tasks
+- Frontmatter format is consistent across all task files
 
-## Skill Observations
+### 9. Component Consolidation
 
-If any task generation patterns, step instructions, or template formats in this skill were wrong, incomplete, or misleading during this run, include a note in your final output to the user. This helps the parent context decide whether to update the skill.
+- No two tasks create components with similar names, purposes, or overlapping structure
+- Shared patterns use a single shared component with configuration, not separate implementations
+
+## Review Loop
+
+Run the checklist above against all task files. Then:
+
+1. **If Critical issues found:** Fix them by editing the task files. Then re-run the full checklist again from the top. Repeat until no Critical issues remain.
+2. **If only Warnings/Notes remain:** Proceed — you will present these to the user.
+3. **If no issues found:** Proceed.
+
+Do NOT present results after a single pass if Critical issues exist. The loop must continue until clean.
+
+## Present to User
+
+After the review loop completes with no Critical issues, present:
+
+1. Number of tasks generated
+2. Task dependency tree (visual format)
+3. Any Warnings from the review (with your recommendation)
+4. Offer to show task files or proceed to implementation
 
-## Complete
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Once the user approves the task breakdown, the skill is complete. The tasks are ready for implementation.
+Read `references/step-5-reflect.md` now.

package/src/skills/spec-to-tasks/references/step-5-reflect.md

@@ -0,0 +1,22 @@
+# Step 5: Skill Reflection
+
+**IMPORTANT: This step is mandatory. The spec-to-tasks workflow is not complete until this step is finished. Do not skip this.**
+
+## Reflect on This Run
+
+Think about how this skill performed during this session. Consider:
+
+1. **Step instructions**: Were any steps unclear, misleading, or missing information?
+2. **Task template**: Did the template work well, or did you need to deviate from it?
+3. **Review checklist**: Did the checklist catch real issues? Were any checks unnecessary or missing?
+4. **Workflow flow**: Did the step order make sense? Were there unnecessary steps or missing ones?
+
+## Report Issues
+
+If you identified any problems with the skill's instructions, templates, or workflow, include a brief note in your final output to the user under a "Skill Observations" heading. Keep it factual — what was wrong, what would be better.
+
+If everything worked well, state: "No skill issues observed."
+
+## Complete
+
+The spec-to-tasks workflow is now complete.