@kennethsolomon/shipkit 3.11.1 → 3.13.0

package/README.md

@@ -269,6 +269,63 @@ Use these anytime — they're not part of any workflow.
 
 ---
 
+## Code Navigation (LSP)
+
+ShipKit configures LSP (Language Server Protocol) automatically — giving Claude Code go-to-definition, find-references, hover, and diagnostics instead of plain text search.
+
+**`/sk:setup-claude`** and **`/sk:setup-optimizer`** both run an LSP Integration step that:
+- Sets `ENABLE_LSP_TOOL=1` in `~/.claude/settings.json`
+- Detects your stack and installs the appropriate language server
+
+| Stack | Language Server |
+|-------|----------------|
+| TypeScript / JavaScript | `typescript-language-server` |
+| PHP | `intelephense` |
+| Python | `pylsp` |
+| Go | `gopls` |
+| Rust | `rust-analyzer` |
+| Swift | `sourcekit-lsp` |
+
+**Rule:** Prefer LSP over `rg`/Grep for code navigation. Use `rg` only when LSP is unavailable or for arbitrary text/pattern matching.
+
+---
+
+## MCP Servers & Plugins
+
+Both `/sk:setup-claude` and `/sk:setup-optimizer` offer to install three tools that enhance Claude Code's reasoning, knowledge, and session visibility. All are opt-in and idempotent.
+
+### Sequential Thinking MCP
+
+**Why it exists:** Complex problems — architecture decisions, multi-step debugging, tasks with many constraints — benefit from structured reasoning. Without it, Claude works through hard problems in a single pass, which can miss steps or lose track of constraints.
+
+**What it does:** Gives Claude a dedicated reasoning scratchpad. It thinks through steps sequentially before responding, without cluttering your conversation with the intermediate work.
+
+**Benefit:** More coherent, thorough responses on hard problems. Especially useful during `/sk:brainstorm`, `/sk:debug`, and `/sk:review`.
+
+**How it's installed:** Adds `@modelcontextprotocol/server-sequential-thinking` to `~/.mcp.json` (global, applies to all projects).
+
+### Context7
+
+**Why it exists:** Claude's training has a knowledge cutoff. When you're working with libraries that release frequently — React, Next.js, Tailwind, shadcn/ui — Claude's suggestions can reference outdated APIs, deprecated methods, or patterns that no longer apply.
+
+**What it does:** Fetches current, version-accurate documentation for libraries you're using and injects it into Claude's context at the moment it's needed.
+
+**Benefit:** Accurate code suggestions for the actual version you're running. No more `useEffect` patterns from React 17 when you're on React 19.
+
+**How it's installed:** Enables `context7@claude-plugins-official` in `~/.claude/settings.json`.
+
+### ccstatusline
+
+**Why it exists:** Knowing your context window %, active model, and current branch at a glance matters. Without it, you have to run `/sk:status` or guess when to `/compact`.
+
+**What it does:** Adds a persistent statusline to the Claude Code CLI showing context window usage, active model, git branch, and current task.
+
+**Benefit:** Always-visible session state. Know when you're approaching context limits before it becomes a problem.
+
+**How it's installed:** Runs `npx ccstatusline@latest` which writes the statusline config to `~/.claude/settings.json`.
+
+---
+
 ## All Commands
 
 <details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.11.1",
+  "version": "3.13.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:setup-claude/SKILL.md

@@ -303,8 +303,9 @@ Use `run_in_background: true` for tasks that don't block your next step:
 
 When a generated CLAUDE.md exists (has `<!-- Generated by /sk:setup-claude -->` marker), perform a section completeness check before reporting "no changes needed":
 
-1. Search for `<!-- BEGIN:sub-agent-patterns -->`. If not found, insert the full Sub-Agent Patterns section after the Workflow section and before `## Commands`.
-2. For any future managed sections with BEGIN/END markers, repeat: search for marker, insert if missing, replace content between markers if found.
+1. Search for `<!-- BEGIN:code-navigation -->`. If not found, insert the Code Navigation section (with BEGIN/END markers) before `## Workflow`.
+2. Search for `<!-- BEGIN:sub-agent-patterns -->`. If not found, insert the full Sub-Agent Patterns section after the Workflow section and before `## Commands`.
+3. For any future managed sections with BEGIN/END markers, repeat: search for marker, insert if missing, replace content between markers if found.
 
 This check runs every time — even if tools are installed and tasks files exist. Never short-circuit before verifying section completeness.
 
@@ -377,6 +378,90 @@ Deployed from `templates/.claude/rules/` based on detected stack:
 | `laravel.md.template` | Laravel detected in framework |
 | `react.md.template` | React or Next.js detected in framework |
 
+### LSP Integration
+
+After stack detection, check and configure LSP tooling:
+
+1. **Enable LSP tool** — ensure `"env": { "ENABLE_LSP_TOOL": "1" }` is present in `~/.claude/settings.json` (global settings, not project-level). Add if missing — merge additively, never overwrite existing keys.
+
+2. **Detect language server** — based on detected stack:
+
+   | Stack | Language Server | Install Command |
+   |-------|----------------|-----------------|
+   | JavaScript / TypeScript | `typescript-language-server` | `npm install -g typescript typescript-language-server` |
+   | PHP / Laravel | `intelephense` | `npm install -g intelephense` |
+   | Python | `pyright` | `npm install -g pyright` |
+   | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
+   | Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
+   | Swift | `sourcekit-lsp` | pre-installed with Xcode — no install needed |
+
+3. **Check if installed** — run `which <server>` to verify. If missing, install automatically.
+
+4. **Report:**
+   ```
+   LSP: typescript-language-server ✓ installed
+   ENABLE_LSP_TOOL=1 in ~/.claude/settings.json ✓
+   ```
+
+**Idempotency:** Skip install if the server is already present. Skip settings update if `ENABLE_LSP_TOOL` is already set.
+
+### MCP Servers & Plugins
+
+After LSP setup, prompt the user to install three recommended tools that enhance Claude Code with structured reasoning, live documentation, and session visibility:
+
+> "Install recommended MCP servers & plugins? (Sequential Thinking, Context7, ccstatusline) [y/n]"
+
+If yes, install each — skip any already configured.
+
+#### 1. Sequential Thinking MCP
+
+Gives Claude a structured scratchpad for complex multi-step reasoning (architecture decisions, debugging chains, multi-constraint problems) without cluttering the conversation context.
+
+**Check:** grep `~/.mcp.json` for `sequential-thinking`. If missing, add the entry:
+
+```json
+{
+  "sequential-thinking": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+  }
+}
+```
+
+Merge additively into `~/.mcp.json` — never overwrite existing entries. Create the file if it doesn't exist.
+
+Report: `+ sequential-thinking MCP added to ~/.mcp.json`
+
+#### 2. Context7
+
+Fetches live, version-accurate library documentation and injects it into Claude's context — eliminating stale knowledge cutoff issues when working with rapidly evolving frameworks (Tailwind 4, React 19, Next.js 15, etc.).
+
+**Check:** grep `~/.claude/settings.json` for `context7`. If missing, add to `enabledPlugins`:
+
+```json
+"enabledPlugins": {
+  "context7@claude-plugins-official": true
+}
+```
+
+Merge additively — never overwrite other `enabledPlugins` entries.
+
+Report: `+ context7 plugin enabled in ~/.claude/settings.json`
+
+#### 3. ccstatusline
+
+Configures a persistent Claude Code statusline showing context window %, active model, git branch, and current task — always visible without running `/sk:status`.
+
+**Check:** look for an existing `statusline` config in `~/.claude/settings.json`. If not already configured by ccstatusline:
+
+```bash
+npx ccstatusline@latest
+```
+
+Report: `+ ccstatusline configured`
+
+**Idempotency:** Skip each install if already present. Never overwrite existing MCP entries, plugin flags, or statusline config.
+
 ### Settings Generation (`.claude/settings.json`)
 
 Rendered from `templates/.claude/settings.json.template`. Contains:

package/skills/sk:setup-claude/templates/.claude/settings.json.template

@@ -1,5 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  },
   "statusline": {
     "command": "bash .claude/statusline.sh"
   },

package/skills/sk:setup-claude/templates/CLAUDE.md.template

@@ -31,6 +31,12 @@
 [TEST_COMMAND]
 ```
 
+## Code Navigation
+<!-- BEGIN:code-navigation -->
+- Prefer LSP over Grep for code navigation (go-to-definition, find-references, hover, diagnostics)
+- Use `rg` only when LSP is unavailable or for arbitrary text/pattern matching
+<!-- END:code-navigation -->
+
 ## Workflow — Follow This Order
 <!-- LOCK -->
 

package/skills/sk:setup-optimizer/SKILL.md

@@ -40,7 +40,7 @@ The single command to keep your entire ShipKit project infrastructure current. D
 
 Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
 
-- **Missing sections** — checks for essential sections (Workflow, Sub-Agent Patterns, Cross-Platform Tracking, Project Memory, Lessons Capture, Testing, Commands, etc.)
+- **Missing sections** — checks for essential sections (Code Navigation, Workflow, Sub-Agent Patterns, Cross-Platform Tracking, Project Memory, Lessons Capture, Testing, Commands, etc.)
 - **Stale content** — detects outdated info (stale model/route counts, removed dependencies, old command names like `/laravel-lint` instead of `/sk:lint`)
 - **Inconsistencies** — compares documented vs actual project state (directories, scripts, workflows)
 - **Section completeness** — flags sections that exist but are empty or have only placeholder text
@@ -88,7 +88,7 @@ Explore → Design → Plan → Branch → Write Tests + Implement → Commit
 1. Read the latest workflow template from `~/.claude/skills/sk:setup-claude/templates/CLAUDE.md.template`
 2. Compare with the current CLAUDE.md workflow section
 3. If different, replace the workflow section (between `## Workflow` and the next `##` that isn't a workflow subsection)
-4. Insert missing sections (Sub-Agent Patterns, Project Memory, etc.) in their correct positions
+4. Insert missing sections (Code Navigation, Sub-Agent Patterns, Project Memory, etc.) in their correct positions — Code Navigation (`<!-- BEGIN:code-navigation -->`) goes before `## Workflow`; Sub-Agent Patterns goes after `## Workflow` and before `## Commands`
 5. Preserve all `<!-- LOCK -->` and project-specific sections
 
 ### Step 1.5: Hooks Deployment
@@ -135,10 +135,66 @@ After updating the workflow, check and deploy hooks:
      ~ Updated .claude/settings.json with new hook wiring
    ```
 
-**If no:** skip hook deployment, continue to Step 2.
+**If no:** skip hook deployment, continue to Step 1.6.
+
+### Step 1.6: LSP Integration Check
+
+After hooks deployment, check and configure LSP tooling:
+
+1. **Check `ENABLE_LSP_TOOL`** — verify `~/.claude/settings.json` has `"env": { "ENABLE_LSP_TOOL": "1" }`. If missing, add it.
+
+2. **Detect stack language server** — based on the project's detected language:
+
+   | Stack | Language Server | Install Command |
+   |-------|----------------|-----------------|
+   | JavaScript / TypeScript | `typescript-language-server` | `npm install -g typescript typescript-language-server` |
+   | PHP / Laravel | `intelephense` | `npm install -g intelephense` |
+   | Python | `pyright` | `npm install -g pyright` |
+   | Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
+   | Rust | `rust-analyzer` | `rustup component add rust-analyzer` |
+   | Swift | `sourcekit-lsp` | pre-installed with Xcode — no install needed |
+
+3. **Check if installed** — run `which <server>` or `<server> --version`
+
+4. **Install if missing** — run the install command for the detected stack
+
+5. **Report status:**
+   ```
+   LSP: typescript-language-server ✓ installed
+   ENABLE_LSP_TOOL=1 in ~/.claude/settings.json ✓
+   ```
+
+**If no language server needed** (e.g. Swift with Xcode), skip install — report status only.
+
+**Idempotency:** Never overwrite existing `env` keys — merge additively.
 
 **Idempotency:** Never overwrite existing hook files — the user may have customized them. Only deploy hooks that don't exist yet. For settings.json, merge additively.
 
+### Step 1.7: MCP Servers & Plugin Check
+
+After LSP check, verify the three recommended tools are configured:
+
+1. **Sequential Thinking MCP** — grep `~/.mcp.json` for `sequential-thinking`
+2. **Context7 plugin** — grep `~/.claude/settings.json` for `context7@claude-plugins-official` in `enabledPlugins`
+3. **ccstatusline** — check `~/.claude/settings.json` for a `statusline` entry set by ccstatusline
+
+**Report status and prompt:**
+
+> "MCP/Plugins: [X/3] configured
+>   sequential-thinking: [✓ configured / ✗ missing]
+>   context7:            [✓ configured / ✗ missing]
+>   ccstatusline:        [✓ configured / ✗ missing]
+> Install missing? [y/n]"
+
+**If yes:** Follow the same install steps as `sk:setup-claude` MCP Servers & Plugins section:
+- Sequential Thinking: merge entry into `~/.mcp.json`
+- Context7: add `context7@claude-plugins-official: true` to `~/.claude/settings.json` enabledPlugins
+- ccstatusline: run `npx ccstatusline@latest`
+
+**If no:** skip, continue to Step 2.
+
+**Idempotency:** Never overwrite existing MCP entries, plugin flags, or statusline config — additive merge only.
+
 ### Step 2: Scan & Enrich
 
 After workflow update, proceeds with codebase discovery and enrichment:

package/skills/sk:setup-optimizer/templates/CLAUDE.md.template

@@ -65,6 +65,11 @@
 - **Testing**: `[TEST_COMMAND]`
 - **Linting**: `[LINT_COMMAND]`
 
+## Code Navigation
+
+- Prefer LSP over Grep for code navigation (go-to-definition, find-references, hover, diagnostics)
+- Use `rg` only when LSP is unavailable or for arbitrary text/pattern matching
+
 ## Important Context
 
 - The project uses [LANGUAGE] with [FRAMEWORK]