specweave 1.0.198 → 1.0.199

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.197" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.198" sections="header,start,autodetect,metarule,rules,workflow,reflect,context,structure,taskformat,secrets,syncing,testing,tdd,api,limits,troubleshooting,lazyloading,principles,linking,mcp,auto,docs" -->
 
 <!-- SW:SECTION:hook-priority version="1.0.171" -->
 ## ⛔ ABSOLUTE PRIORITY: Hook Instructions Are Mandatory
@@ -53,7 +53,7 @@ Hooks exist to enforce workflow discipline. If you ignore them:
 **This is non-negotiable. No exceptions. No "just this once".**
 <!-- SW:END:hook-priority -->
 
-<!-- SW:SECTION:header version="1.0.197" -->
+<!-- SW:SECTION:header version="1.0.198" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
@@ -277,7 +277,7 @@ SpecWeave's `user-prompt-submit.sh` hook auto-installs LSP plugins with **projec
 
 **Reference**: [Official Docs](https://code.claude.com/docs/en/discover-plugins#install-plugins) | [Settings Scopes](https://code.claude.com/docs/en/settings#configuration-scopes)
 
-<!-- SW:SECTION:start version="1.0.197" -->
+<!-- SW:SECTION:start version="1.0.198" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -287,7 +287,7 @@ SpecWeave's `user-prompt-submit.sh` hook auto-installs LSP plugins with **projec
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.197" -->
+<!-- SW:SECTION:autodetect version="1.0.198" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -297,7 +297,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.197" -->
+<!-- SW:SECTION:metarule version="1.0.198" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -308,7 +308,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.197" -->
+<!-- SW:SECTION:rules version="1.0.198" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (see Structure section for details)
@@ -324,7 +324,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
    Use next available number. **NEVER create duplicate prefixes.**
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.197" -->
+<!-- SW:SECTION:workflow version="1.0.198" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -338,7 +338,6 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 | `/sw:cancel-auto` | ⚠️ EMERGENCY ONLY manual cancel |
 | `/sw:validate` | Quality check |
 | `/sw:done` | Close |
-| `/sw:reconcile` | Fix ID collisions after merge (multi-dev) |
 | `/sw-github:sync` | GitHub sync |
 | `/sw-jira:sync` | Jira sync |
 
@@ -371,24 +370,14 @@ project/
 **NEVER assume single-repo mode without scanning first!**
 <!-- SW:END:save-nested-repos -->
 
-<!-- SW:SECTION:reflect version="1.0.197" -->
+<!-- SW:SECTION:reflect version="1.0.198" -->
 ## Skill Memories
 
 SpecWeave learns from corrections. Learnings saved here automatically. Edit or delete as needed.
 
 **Disable**: Set `"reflect": { "enabled": false }` in `.specweave/config.json`
-
-### Devops
-- **2026-01-29**: LSP requires setup (see "LSP Setup" section)
-
-### Logging
-- **2026-01-29**: Do NOT verify immediately - show dialog instead
-
-### General
-- **2026-01-29**: Always check for credentials FIRST (presence only - never display values)
 <!-- SW:END:reflect -->
 
-
 ## Skill Memories
 
 <!-- Auto-captured by SpecWeave reflect. Edit or delete as needed. -->
@@ -396,7 +385,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ### Pm
 - **2026-02-01**: Enable interview process during increment creation for SpecWeave projects
 
-<!-- SW:SECTION:context version="1.0.197" -->
+<!-- SW:SECTION:context version="1.0.198" -->
 ## Context
 
 **Before implementing**: Check ADRs at `.specweave/docs/internal/architecture/adr/`
@@ -404,7 +393,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Load context**: `/sw:context <topic>` loads relevant living docs into conversation
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:structure version="1.0.197" -->
+<!-- SW:SECTION:structure version="1.0.198" -->
 ## Structure
 
 ```
@@ -419,7 +408,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 **Everything else → subfolders**: `reports/` | `logs/` | `scripts/` | `backups/`
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.197" -->
+<!-- SW:SECTION:taskformat version="1.0.198" -->
 ## Task Format
 
 ```markdown
@@ -429,7 +418,7 @@ SpecWeave learns from corrections. Learnings saved here automatically. Edit or d
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.197" -->
+<!-- SW:SECTION:secrets version="1.0.198" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -443,7 +432,7 @@ gh auth status
 **SECURITY**: NEVER use `grep TOKEN .env` without `-q` flag - it exposes credentials in terminal!
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.197" -->
+<!-- SW:SECTION:syncing version="1.0.198" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **Commands**: `/sw-github:sync {id}` (issues) | `/sw:sync-specs` (living docs only)
@@ -453,7 +442,7 @@ gh auth status
 **Config**: Set `sync.github.enabled: true` + `canUpdateExternalItems: true` in config.json
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:testing version="1.0.197" -->
+<!-- SW:SECTION:testing version="1.0.198" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -465,7 +454,7 @@ vi.mock('./module', () => ({ func: mockFn }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:tdd version="1.0.197" -->
+<!-- SW:SECTION:tdd version="1.0.198" -->
 ## TDD Mode (Test-Driven Development)
 
 **When `testing.defaultTestMode: "TDD"` is configured**, follow RED-GREEN-REFACTOR discipline:
@@ -526,7 +515,7 @@ When TDD is enabled, tasks include phase markers:
 **Rule**: Complete dependencies BEFORE dependent tasks (RED before GREEN).
 <!-- SW:END:tdd -->
 
-<!-- SW:SECTION:api version="1.0.197" -->
+<!-- SW:SECTION:api version="1.0.198" -->
 ## API Development (OpenAPI-First)
 
 **For API projects only.** Commands: `/sw:api-docs --all` | `--openapi` | `--postman` | `--validate`
@@ -534,72 +523,13 @@ When TDD is enabled, tasks include phase markers:
 Enable in config: `{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml"}}`
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.197" -->
+<!-- SW:SECTION:limits version="1.0.198" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:multidev version="1.0.197" -->
-## Multi-Developer Workflows
-
-**For teams with 2+ developers working on same project.**
-
-### How It Works
-
-1. **Each developer works on their branch** - create increments freely
-2. **Merge to main** - git handles folder merges naturally
-3. **Run `/sw:reconcile` after merge** - fixes any ID collisions
-
-### Post-Merge Reconciliation
-
-When two developers create increments with same ID (e.g., both create `0001E-feature` from JIRA import):
-
-```bash
-# After merging branches to main
-/sw:reconcile
-
-# What it does:
-# 1. Scans ALL increment folders (active, _archive, _abandoned, _paused)
-# 2. Detects ID collisions (same base number in multiple folders)
-# 3. Uses file modification dates to determine chronological order
-# 4. Renumbers "later" increments to next available IDs
-# 5. Updates metadata.json, living docs references, and sync links
-```
-
-### Example Scenario
-
-```
-Branch A creates: 0001E-auth-feature (closed, synced to JIRA)
-Branch B creates: 0001E-payment-feature (closed, synced to JIRA)
-
-After merge to main:
-.specweave/increments/
-├── 0001E-auth-feature/      # From branch A (modified Jan 15)
-└── 0001E-payment-feature/   # From branch B (modified Jan 20) ← COLLISION
-
-After /sw:reconcile:
-.specweave/increments/
-├── 0001E-auth-feature/      # Kept as 0001E (earlier)
-└── 0002E-payment-feature/   # Renumbered to 0002E (later)
-```
-
-### Merge Conflict Strategy
-
-| File | Strategy | Notes |
-|------|----------|-------|
-| `spec.md`, `tasks.md` | Manual merge | Essential content |
-| `metadata.json` | Union merge | Auto via `.gitattributes` |
-| `.specweave/state/*` | Gitignored | Local state, no conflicts |
-
-### Best Practices
-
-1. **Different increment names** - even with same ID, different names merge fine
-2. **Run `/sw:reconcile` after merge** - always, to catch any ID collisions
-3. **Commit reconcile results** - the renumbering is a git commit
-<!-- SW:END:multidev -->
-
-<!-- SW:SECTION:troubleshooting version="1.0.197" -->
+<!-- SW:SECTION:troubleshooting version="1.0.198" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -616,7 +546,7 @@ After /sw:reconcile:
 | Docs folder collisions | Check: `ls docs/ \| grep -E '^[0-9]{2}-' \| cut -d'-' -f1 \| sort \| uniq -d` |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:lazyloading version="1.0.197" -->
+<!-- SW:SECTION:lazyloading version="1.0.198" -->
 ## Plugin Auto-Loading
 
 Plugins load automatically based on project type and keywords. Manual install if needed:
@@ -630,7 +560,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 **Token savings**: Core ~3-5K tokens vs all plugins ~60K+
 <!-- SW:END:lazyloading -->
 
-<!-- SW:SECTION:principles version="1.0.197" -->
+<!-- SW:SECTION:principles version="1.0.198" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -639,7 +569,7 @@ export SPECWEAVE_DISABLE_AUTO_LOAD=1         # Disable auto-load
 4. **Traceable**: All work → specs → ACs
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.197" -->
+<!-- SW:SECTION:linking version="1.0.198" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -647,7 +577,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.197" -->
+<!-- SW:SECTION:mcp version="1.0.198" -->
 ## External Services
 
 **Priority**: CLI tools first (simpler) → MCP for complex integrations
@@ -669,7 +599,7 @@ claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server
 MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:auto version="1.0.197" -->
+<!-- SW:SECTION:auto version="1.0.198" -->
 ## Auto Mode
 
 **Commands**: `/sw:auto` (start) | `/sw:auto-status` (check) | `/sw:cancel-auto` (emergency only)
@@ -686,7 +616,7 @@ MCP supports lazy-loading (auto mode) - tools load on-demand when >10% context.
 **STOP & ASK** if: Spec conflicts | Task unnecessary | Requirement ambiguous
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.197" -->
+<!-- SW:SECTION:docs version="1.0.198" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.198",
+  "version": "1.0.199",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -172,6 +172,39 @@ output_approve_with_context() {
   printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$escaped"
 }
 
+# Helper: Get skill memory content for injection (v1.0.198)
+# Reads .specweave/skill-memories/{skill}.md and extracts learnings.
+# Args: $1=full skill name (e.g., "sw:pm", "sw-frontend:frontend-architect")
+# Returns: Formatted memory content on stdout, or empty string if not found
+get_skill_memory_context() {
+  local full_skill="$1"
+  local project_root="${PROJECT_ROOT:-$(pwd)}"
+
+  # Extract skill name (part after colon, or whole string if no colon)
+  local skill_name="${full_skill##*:}"
+
+  local memory_file="$project_root/.specweave/skill-memories/${skill_name}.md"
+
+  if [[ ! -f "$memory_file" ]]; then
+    return 0
+  fi
+
+  # Read the file and extract learnings section
+  local content
+  content=$(cat "$memory_file" 2>/dev/null)
+
+  # Extract lines between "## Learnings" and next heading or EOF
+  local learnings
+  learnings=$(echo "$content" | sed -n '/^## Learnings$/,/^## /{ /^## Learnings$/d; /^## /d; p; }' | sed '/^$/d')
+
+  if [[ -z "$learnings" ]]; then
+    return 0
+  fi
+
+  # Format for injection
+  printf '📚 **Skill Memory for %s**:\\n%s' "$skill_name" "$learnings"
+}
+
 # Helper: Check if plugin is installed by reading installed_plugins.json (v1.0.175)
 # This is the SOURCE OF TRUTH - more reliable than `claude plugin list` which can have timing issues.
 # Args: $1=plugin name (e.g., "sw-frontend"), $2=marketplace (e.g., "specweave")
@@ -837,12 +870,25 @@ if [[ "${SPECWEAVE_DISABLE_AUTO_LOAD:-0}" != "1" ]] && [[ "${SPECWEAVE_DISABLE_H
                 # Build agent spawn directive if routing skills available (v1.0.155)
                 AGENT_DIRECTIVE=""
                 # v1.0.168: Skill invocation directive (takes precedence over routing)
+                # v1.0.198: Added skill memory injection
                 if [[ -n "$SKILL_INVOCATION" ]]; then
+                  # Get skill memory for injection (v1.0.198)
+                  SKILL_MEMORY=""
+                  SKILL_MEMORY_RAW=$(get_skill_memory_context "$SKILL_INVOCATION")
+                  if [[ -n "$SKILL_MEMORY_RAW" ]]; then
+                    SKILL_MEMORY="
+
+${SKILL_MEMORY_RAW}
+
+---
+"
+                  fi
+
                   if [[ "$SKILL_MANDATORY" == "true" ]]; then
                     AGENT_DIRECTIVE="
 
 ---
-
+${SKILL_MEMORY}
 <skill_invocation_required>
 ### 🎯 MANDATORY: Use ${SKILL_INVOCATION} Skill
 
@@ -862,7 +908,7 @@ ${SKILL_REASON:-This skill provides specialized support for your task.}
                     AGENT_DIRECTIVE="
 
 ---
-
+${SKILL_MEMORY}
 ### 💡 Recommended: Use ${SKILL_INVOCATION} Skill
 
 Consider invoking this skill for better results:
@@ -926,7 +972,18 @@ Continue interviewing until requirements are crystal clear (10-40+ questions for
 "
                       fi
 
-                      MSG="${AUTOLOAD_PREFIX}╔══════════════════════════════════════════════════════════════════════════════╗
+                      # v1.0.198: Get skill memory for increment-planner
+                      INC_PLANNER_MEMORY=""
+                      INC_PLANNER_MEMORY_RAW=$(get_skill_memory_context "sw:increment-planner")
+                      if [[ -n "$INC_PLANNER_MEMORY_RAW" ]]; then
+                        INC_PLANNER_MEMORY="
+${INC_PLANNER_MEMORY_RAW}
+
+---
+"
+                      fi
+
+                      MSG="${AUTOLOAD_PREFIX}${INC_PLANNER_MEMORY}╔══════════════════════════════════════════════════════════════════════════════╗
 ║  🎯 SKILL FIRST - Call Skill tool BEFORE implementation                      ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
 

package/plugins/specweave/skills/lsp/SKILL.md

@@ -1,35 +1,27 @@
 ---
 name: lsp
 description: >
-  MANDATORY: When user says "LSP", "findReferences", "find references", "go to definition",
-  "where defined", "show type", "list symbols", "what uses", or "who calls" - YOU MUST use
-  specweave lsp commands via Bash (NOT grep). This skill provides the commands to use.
+  Code navigation with LSP. When user says "find references", "go to definition",
+  "where defined", "show type", "list symbols", "what uses", or "who calls" -
+  use native LSP tools if available, otherwise fall back to specweave lsp commands.
 ---
 
 # LSP Code Intelligence
 
-Use SpecWeave's LSP CLI for semantic code navigation and analysis.
+Semantic code navigation and analysis.
 
-## IMPORTANT: File Path Required
+## Priority Order
 
-**If the user does NOT specify a file path, you MUST first find the file:**
+**1. Native LSP (if plugins installed via hooks)**
 
-```bash
-# Step 1: Find which file(s) contain the symbol
-grep -rn --include="*.ts" "function symbolName\|class symbolName" .
-
-# Step 2: Then use LSP on the found file
-specweave lsp refs <found-file> <symbol>
-```
+If you have native LSP tools available (goToDefinition, findReferences, hover, etc.),
+use those directly - they're faster and more integrated.
 
-**Example:**
-User says: "Find references to sayHello"
-1. First: `grep -rn --include="*.ts" "function sayHello" .` → finds `src/utils.ts`
-2. Then: `specweave lsp refs src/utils.ts sayHello`
+Check: Native LSP requires `ENABLE_LSP_TOOL=1` and LSP plugins installed by hooks.
 
-## How to Use
+**2. SpecWeave CLI (fallback)**
 
-**Use Bash tool with `specweave lsp` commands:**
+If native LSP is unavailable or not working, use `specweave lsp` commands:
 
 ```bash
 # Find all references to a symbol
@@ -48,174 +40,46 @@ specweave lsp symbols <file>
 specweave lsp search <query>
 ```
 
-## Command Reference
-
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `lsp refs` | Find all usages of a symbol | `specweave lsp refs src/api.ts handleRequest` |
-| `lsp def` | Navigate to symbol definition | `specweave lsp def src/utils.ts formatDate` |
-| `lsp hover` | Get type signature and docs | `specweave lsp hover src/models.ts User` |
-| `lsp symbols` | List all symbols in file | `specweave lsp symbols src/index.ts` |
-| `lsp search` | Find symbols across workspace | `specweave lsp search Controller` |
+## When to Use Which
 
-## When to Use LSP vs Grep
-
-| Task | Use LSP | Use Grep |
-|------|---------|----------|
-| Find function usages | ✅ `lsp refs` | ❌ |
-| Navigate to definition | ✅ `lsp def` | ❌ |
-| Get type information | ✅ `lsp hover` | ❌ |
-| Search text patterns | ❌ | ✅ `Grep tool` |
-| Find in comments | ❌ | ✅ `Grep tool` |
-| Case-insensitive search | ❌ | ✅ `Grep -i` |
-
-**Rule of thumb**: Use LSP for symbols, Grep for text patterns.
-
-## Examples
-
-### Example 1: Find All References Before Refactoring
-
-User: "Find all references to handleAutoCommand"
-
-```bash
-specweave lsp refs src/cli/commands/auto.ts handleAutoCommand
-```
-
-Output:
-```
-References to 'handleAutoCommand':
-
-  bin/specweave.js:473:1
-  bin/specweave.js:474:1
-  src/cli/commands/auto.ts:82:5
-  src/cli/commands/auto.ts:96:24
-
-Total: 4 references
-```
-
-### Example 2: Go to Definition
-
-User: "Where is processArgs defined?"
-
-```bash
-specweave lsp def src/cli/commands/auto.ts processArgs
-```
-
-### Example 3: Get Type Information
-
-User: "What's the type signature of handleAutoCommand?"
-
-```bash
-specweave lsp hover src/cli/commands/auto.ts handleAutoCommand
-```
+| Situation | Use |
+|-----------|-----|
+| Native LSP tools available | Native tools (faster) |
+| Native LSP unavailable | `specweave lsp` commands |
+| CI/CD or scripts | `specweave lsp` commands |
+| User explicitly asks for specweave | `specweave lsp` commands |
 
-### Example 4: List All Exports
+## File Path Required (for CLI fallback)
 
-User: "What functions are exported from lsp.ts?"
+If using `specweave lsp` and user doesn't specify a file path, find it first:
 
 ```bash
-specweave lsp symbols src/cli/commands/lsp.ts
-```
-
-### Example 5: Search Workspace
-
-User: "Find all Command classes"
-
-```bash
-specweave lsp search Command
-```
-
-## Supported Languages
-
-| Language | Server Required | Auto-detected by |
-|----------|-----------------|------------------|
-| TypeScript/JS | `typescript-language-server` | `tsconfig.json`, `package.json` |
-| Python | `pyright` or `pylsp` | `requirements.txt`, `pyproject.toml` |
-| C#/.NET | `csharp-ls` | `*.csproj`, `*.sln` |
-| Go | `gopls` | `go.mod` |
-| Rust | `rust-analyzer` | `Cargo.toml` |
-
-## Fallback Behavior
-
-If LSP is unavailable (server not installed, timeout, etc.):
-1. Commands automatically fall back to grep-based search
-2. Results show "(grep fallback)" in output
-3. Still functional, but less precise for symbol resolution
-
-## Requirements
-
-Language servers must be installed globally:
-
-```bash
-# TypeScript (most common)
-npm install -g typescript-language-server typescript
-
-# Python
-pip install pyright
-
-# Go
-go install golang.org/x/tools/gopls@latest
-
-# Rust
-rustup component add rust-analyzer
-```
-
-## Decision Tree for Claude
+# Step 1: Find which file(s) contain the symbol
+grep -rn --include="*.ts" "function symbolName\|class symbolName" .
 
+# Step 2: Then use LSP on the found file
+specweave lsp refs <found-file> <symbol>
 ```
-User asks about code navigation?
-│
-├─ "Find references to X" or "What uses X" or "Who calls X"
-│   └─ Use: specweave lsp refs <file> <symbol>
-│
-├─ "Go to definition" or "Where is X defined"
-│   └─ Use: specweave lsp def <file> <symbol>
-│
-├─ "What type is X" or "Show signature of X"
-│   └─ Use: specweave lsp hover <file> <symbol>
-│
-├─ "List symbols in file" or "What's exported"
-│   └─ Use: specweave lsp symbols <file>
-│
-├─ "Find symbol X in workspace" or "Search for X"
-│   └─ Use: specweave lsp search <query>
-│
-└─ Text search, patterns, comments
-    └─ Use: Grep tool (not LSP)
-```
-
-## Why This Exists
-
-**This is SpecWeave's OWN LSP CLI - separate from Claude Code's native LSP!**
-
-| System | What It Is | Requires ENABLE_LSP_TOOL? |
-|--------|------------|---------------------------|
-| **SpecWeave LSP CLI** (this skill) | Commands like `specweave lsp refs/def/hover` | **NO** - works standalone |
-| **Claude Code Native LSP** | Background code intelligence via plugins | **YES** - requires env var |
 
-### SpecWeave LSP CLI (This Skill)
-- Uses `specweave lsp` commands via Bash
-- Directly calls language servers (typescript-language-server, pyright, etc.)
-- Works independently of Claude Code's plugin system
-- Falls back to grep if language server unavailable
+## How Plugin Installation Works
 
-### Claude Code Native LSP (Separate)
-- Requires `export ENABLE_LSP_TOOL=1` in shell config
-- Requires working LSP plugins from `boostvolt/claude-code-lsps` marketplace
-- Official marketplace plugins (`@claude-plugins-official`) are broken (Issue #15148)
-- Provides background enhancement when editing code
+SpecWeave hooks auto-install LSP plugins per project:
+- `vtsls@claude-code-lsps` for TypeScript/JavaScript
+- `pyright@claude-code-lsps` for Python
+- `rust-analyzer@claude-code-lsps` for Rust
 
-**Bottom line**: Use this skill's commands (`specweave lsp refs/def/hover`) - they work
-without any additional setup beyond having the language server installed.
+These require `ENABLE_LSP_TOOL=1` in the environment.
 
-## Project-Specific Learnings
+## Why SpecWeave CLI Still Exists
 
-**Before starting work, check for project-specific learnings:**
-
-```bash
-# Check if skill memory exists for this skill
-cat .specweave/skill-memories/lsp.md 2>/dev/null || echo "No project learnings yet"
-```
+1. **Fallback** when plugins unavailable or broken
+2. **CI/CD** environments without Claude Code
+3. **Direct user access** to LSP functionality
+4. **Living docs generation** uses it internally
 
-Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.
+## Performance
 
+SpecWeave's TsServerClient (used by both systems) is **52x faster** than grep:
+- Uses direct tsserver protocol (not typescript-language-server)
+- Semantic analysis vs text matching
+- 226 fewer false positives in typical searches