refactor(mcp)!: replace dev_explore with dev_inspect tool

- Renamed dev_explore to dev_inspect for clarity
- Changed actions to specific verbs: compare, validate
- Removed redundant pattern and relationships actions
- Updated all documentation and tests
- Added comprehensive migration guide

BREAKING CHANGE: dev_explore tool has been replaced with dev_inspect.
Use action 'compare' instead of 'similar', and 'validate' for pattern checks.
The 'pattern' action is replaced by dev_search, and 'relationships' by dev_refs.

Author: prosdev

.changeset/dev-explore-to-dev-inspect.md

@@ -0,0 +1,44 @@
+---
+"@lytics/dev-agent-mcp": patch
+"@lytics/dev-agent": patch
+"@lytics/dev-agent-cli": patch
+---
+
+Refactor: Rename dev_explore → dev_inspect with focused actions
+
+**BREAKING CHANGES:**
+
+- `dev_explore` renamed to `dev_inspect`
+- Actions changed from `['pattern', 'similar', 'relationships']` to `['compare', 'validate']`
+- Removed `action: "pattern"` → Use `dev_search` instead
+- Removed `action: "relationships"` → Use `dev_refs` instead  
+- Renamed `action: "similar"` → `action: "compare"`
+
+**What's New:**
+
+- `dev_inspect` with `action: "compare"` finds similar code implementations
+- `dev_inspect` with `action: "validate"` checks pattern consistency (placeholder for future)
+- Clearer tool boundaries: search vs. inspect vs. refs
+- File-focused analysis (always takes file path, not search query)
+
+**Migration Guide:**
+
+```typescript
+// Before
+dev_explore { action: "similar", query: "src/auth.ts" }
+dev_explore { action: "pattern", query: "error handling" }
+dev_explore { action: "relationships", query: "src/auth.ts" }
+
+// After
+dev_inspect { action: "compare", query: "src/auth.ts" }
+dev_search { query: "error handling" }
+dev_refs { name: "authenticateUser" }
+```
+
+**Why:**
+
+- Eliminate tool duplication (`pattern` duplicated `dev_search`)
+- Clear single responsibility (file analysis only)
+- Better naming (`inspect` = deep file examination)
+- Reserve `dev_explore` for future external context (standards, examples, docs)
+

AGENTS.md

@@ -191,7 +191,7 @@ MCP server with built-in adapters for AI tools.
 - **HistoryAdapter:** Semantic git commit search (`dev_history`)
 - **StatusAdapter:** Repository status (`dev_status`)
 - **PlanAdapter:** Context assembly for issues (`dev_plan`)
-- **ExploreAdapter:** Code exploration (`dev_explore`)
+- **InspectAdapter:** File analysis and pattern checking (`dev_inspect`)
 - **GitHubAdapter:** Issue/PR search (`dev_gh`)
 - **HealthAdapter:** Server health checks (`dev_health`)
 

CHANGELOG.md

@@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `dev_search` - Semantic code search with type-aware understanding
   - `dev_status` - Repository health and statistics
   - `dev_plan` - Implementation planning from GitHub issues
-  - `dev_explore` - Code pattern discovery and relationship mapping
+  - `dev_inspect` - File analysis (similarity + pattern checking)
   - `dev_gh` - GitHub issue/PR search with offline caching
 - **Multi-language Support** - TypeScript, JavaScript, Go, Python, Rust, Markdown
 - **Local-first Architecture** - All embeddings and indexing run locally

CLAUDE.md

@@ -168,7 +168,7 @@ Once installed, AI tools gain access to:
 - **`dev_map`** - Codebase structure with component counts and change frequency
 - **`dev_history`** - Semantic search over git commits (who changed what and why)
 - **`dev_plan`** - Assemble context for GitHub issues (code + history + patterns)
-- **`dev_explore`** - Find similar code, trace relationships
+- **`dev_inspect`** - Inspect files (compare similar implementations, check patterns)
 - **`dev_gh`** - Search GitHub issues/PRs semantically
 - **`dev_status`** - Repository indexing status
 - **`dev_health`** - Server health checks

PLAN.md

@@ -44,7 +44,7 @@ Dev-agent provides semantic code search, codebase intelligence, and GitHub integ
 | Adapter framework | ✅ Done | `@lytics/dev-agent-mcp` |
 | `dev_search` - Semantic code search | ✅ Done | MCP adapter |
 | `dev_status` - Repository status | ✅ Done | MCP adapter |
-| `dev_explore` - Code exploration | ✅ Done | MCP adapter |
+| `dev_inspect` - File analysis | ✅ Done | MCP adapter |
 | `dev_plan` - Issue planning | ✅ Done | MCP adapter |
 | `dev_gh` - GitHub search | ✅ Done | MCP adapter |
 | `dev_health` - Health checks | ✅ Done | MCP adapter |
@@ -219,8 +219,8 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 | Phase | Tool | Status |
 |-------|------|--------|
 | 1 (v0.4.4) | `dev_search` | ✅ Done |
-| 2 | `dev_refs`, `dev_explore` | 🔲 Todo |
-| 3 | `dev_map`, `dev_status` | 🔲 Todo |
+| 2 | `dev_refs`, `dev_inspect` | ✅ Done |
+| 3 | `dev_map`, `dev_status` | ✅ Done |
 
 **Implementation (Phase 1):**
 - After search results, check filesystem for test siblings
@@ -234,7 +234,7 @@ Git history is valuable context that LLMs can't easily access. We add intelligen
 |------|--------|
 | Improved dev_search description ("USE THIS FIRST") | ✅ Done |
 | Improved dev_map description (vs list_dir) | ✅ Done |
-| Improved dev_explore description (workflow hints) | ✅ Done |
+| Improved dev_inspect description (file analysis) | ✅ Done |
 | Improved dev_refs description (specific symbols) | ✅ Done |
 | All 9 adapters registered in CLI | ✅ Done |
 

README.md

@@ -15,7 +15,7 @@ dev-agent indexes your codebase and provides 9 MCP tools to AI assistants. Inste
 - `dev_map` — Codebase structure with change frequency
 - `dev_history` — Semantic search over git commits
 - `dev_plan` — Assemble context for GitHub issues
-- `dev_explore` — Find similar code, trace relationships
+- `dev_inspect` — Inspect files (compare similar code, check patterns)
 - `dev_gh` — Search GitHub issues/PRs semantically
 - `dev_status` / `dev_health` — Monitoring
 
@@ -157,12 +157,12 @@ Assemble context for issue #42
 
 **Note:** This tool no longer generates task breakdowns. It provides comprehensive context so the AI assistant can create better plans.
 
-### `dev_explore` - Code Exploration
-Discover patterns, find similar code, analyze relationships.
+### `dev_inspect` - File Analysis
+Inspect specific files, compare implementations, validate patterns.
 
 ```
-Find code similar to src/auth/middleware.ts
-Search for error handling patterns
+Compare src/auth/middleware.ts with similar implementations
+Validate pattern consistency in src/hooks/useAuth.ts
 ```
 
 ### `dev_status` - Repository Status

TROUBLESHOOTING.md

@@ -456,7 +456,7 @@ dev github index
 **Expected:**
 - `dev_search`: 100-500ms
 - `dev_status`: 50-100ms
-- `dev_explore`: 200-800ms
+- `dev_inspect`: 200-800ms
 - `dev_plan`: 5-15 seconds
 - `dev_gh`: 100-300ms
 
@@ -546,7 +546,7 @@ dev github index
 **Solution:**
 Check the tool's input schema:
 - `dev_search`: Requires `query` (string)
-- `dev_explore`: Requires `action` and `query`
+- `dev_inspect`: Requires `action` and `query` (file path)
 - `dev_plan`: Requires `issue` (number)
 - `dev_gh`: Requires `action`
 
@@ -655,7 +655,7 @@ dev mcp start --verbose
 # In another terminal, send test message
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | dev mcp start
 
-# Should list all 9 tools: dev_search, dev_refs, dev_map, dev_history, dev_status, dev_plan, dev_explore, dev_gh, dev_health
+# Should list all 9 tools: dev_search, dev_refs, dev_map, dev_history, dev_status, dev_plan, dev_inspect, dev_gh, dev_health
 ```
 
 ### Inspect storage
@@ -875,7 +875,7 @@ dev_health
 **Solution:**
 - Index at monorepo root
 - Search works across all projects
-- Use `dev_explore` to find related code
+- Use `dev_inspect` to analyze specific files
 
 ### Non-git repositories
 
@@ -890,7 +890,7 @@ dev_health
 dev index .
 
 # Skip GitHub indexing
-# Just use dev_search, dev_status, dev_explore, dev_plan
+# Just use dev_search, dev_status, dev_inspect, dev_plan
 ```
 
 ### Very large files (>10MB)

examples/README.md

@@ -200,20 +200,20 @@ dev github index
 
 ---
 
-### `dev_explore` - Code Exploration
+### `dev_inspect` - File Analysis
 
-Find patterns and similar code:
+Inspect files and compare implementations:
 
 ```
-# Find patterns
-dev_explore:
-  action: "pattern"
-  query: "error handling middleware"
-
-# Find similar code
-dev_explore:
-  action: "similar"
-  path: "src/utils/retry.ts"
+# Compare similar implementations
+dev_inspect:
+  action: "compare"
+  query: "src/utils/retry.ts"
+
+# Validate pattern consistency (coming soon)
+dev_inspect:
+  action: "validate"
+  query: "src/hooks/useAuth.ts"
 ```
 
 ---
@@ -294,9 +294,9 @@ dev_health:
    dev_plan: { issue: 123 }
    ```
 
-2. **Explore relevant patterns:**
+2. **Search for relevant patterns:**
    ```
-   dev_explore: { action: "pattern", query: "feature type from issue" }
+   dev_search: { query: "feature type from issue" }
    ```
 
 ### Code Review Prep

packages/cli/src/commands/mcp.ts

@@ -61,7 +61,7 @@ Setup:
   3. Restart Cursor to activate
 
 Available Tools (9):
-  dev_search, dev_status, dev_plan, dev_explore, dev_gh,
+  dev_search, dev_status, dev_plan, dev_inspect, dev_gh,
   dev_health, dev_refs, dev_map, dev_history
 `
   )
@@ -251,7 +251,7 @@ Available Tools (9):
 
           logger.info(chalk.green('MCP server started successfully!'));
           logger.info(
-            'Available tools: dev_search, dev_status, dev_plan, dev_explore, dev_gh, dev_health, dev_refs, dev_map, dev_history'
+            'Available tools: dev_search, dev_status, dev_plan, dev_inspect, dev_gh, dev_health, dev_refs, dev_map, dev_history'
           );
 
           if (options.transport === 'stdio') {

packages/core/src/observability/README.md

@@ -126,7 +126,7 @@ Track parent-child relationships:
 
 ```typescript
 const parent = tracker.startRequest('dev_plan', { issue: 42 });
-const child = tracker.startRequest('dev_explore', { action: 'pattern' }, parent.requestId);
+const child = tracker.startRequest('dev_inspect', { action: 'compare' }, parent.requestId);
 // child.parentId === parent.requestId
 ```
 
@@ -144,7 +144,7 @@ const metrics = tracker.getMetrics();
 //   p99Duration: 890,
 //   byTool: {
 //     'dev_search': { count: 500, avgDuration: 100 },
-//     'dev_explore': { count: 300, avgDuration: 200 },
+//     'dev_inspect': { count: 300, avgDuration: 200 },
 //     'dev_plan': { count: 200, avgDuration: 180 }
 //   }
 // }