feat(agents): dogfood dev-agent MCP tools in Claude agents

.claude/agents/bug-investigator.md

@@ -1,7 +1,7 @@
 ---
 name: bug-investigator
 description: "Traces bugs through the codebase and identifies root causes. Use when debugging issues, investigating errors, or understanding why something is broken."
-tools: Read, Edit, Write, Glob, Grep, Bash
+tools: Read, Edit, Write, Glob, Grep, Bash, mcp__dev-agent__dev_search, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_map
 model: sonnet
 color: orange
 ---
@@ -10,18 +10,28 @@ color: orange
 
 Systematically traces issues through the dev-agent monorepo. Reproduces, traces, fixes, and prevents regression.
 
+## MCP Tools — Use These First
+
+- **`dev_search`** — Start here for any conceptual query ("where does rate limiting happen", "how are embeddings stored"). Semantic search finds code by meaning, not just keywords.
+- **`dev_refs`** — Trace callers/callees of a function to map the data flow. Use this instead of grepping for function names when tracing how data moves across packages.
+- **`dev_map`** — Check change frequency to see what files changed recently. Useful for "when did it break?" — high-churn files near the bug timeframe are prime suspects.
+
+Fall back to Grep/Glob for exact string matches or file patterns.
+
 ## Investigation Framework
 
 ### Phase 1: Understand the Bug
 
 1. What is the expected behavior?
 2. What is the actual behavior?
 3. What are the reproduction steps?
-4. When did it start happening? (check recent commits)
+4. When did it start happening? (check recent commits + `dev_map` for churn)
 5. Is it consistent or intermittent?
 
 ### Phase 2: Trace the Data Flow
 
+Use `dev_refs` to trace caller/callee chains along these paths:
+
 **MCP path:**
 ```
 AI Tool Request → MCP Server → Adapter → Core Service → Scanner/Vector/GitHub
@@ -41,6 +51,8 @@ dev index → Indexer → Scanner (ts-morph/tree-sitter) → Antfly (embed + sto
 
 ### Phase 3: Identify Root Cause
 
+Use `dev_search` to find code related to each symptom area:
+
 | Symptom | Likely Cause | Where to Look |
 |---------|--------------|---------------|
 | MCP tool returns empty | Index not built or stale | `packages/core/src/indexer/` |

.claude/agents/logic-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: logic-reviewer
 description: "Correctness-focused code reviewer. Checks edge cases, error handling, race conditions, null access. Adds confidence levels per finding."
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, mcp__dev-agent__dev_search, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_patterns
 model: opus
 color: yellow
 ---
@@ -64,9 +64,13 @@ Every finding MUST include confidence: **HIGH** (verified from code), **MEDIUM**
 - [ ] Retry logic respects backoff limits and doesn't retry non-transient errors
 
 ### Cross-Package Data Flow (Deep+ Effort)
-- [ ] Core exports consumed correctly by CLI, MCP server, and subagents
+
+Use `dev_refs` to trace caller/callee chains across package boundaries. Use `dev_search` to find related code by concept when the function name isn't obvious.
+
+- [ ] Core exports consumed correctly by CLI, MCP server, and subagents — verify with `dev_refs`
 - [ ] Type boundaries between packages match (no `any` casting to bridge mismatches)
 - [ ] Logger (@prosdevlab/kero) configuration consistent across consumers
+- [ ] Error handling patterns are consistent with existing code (verify with `dev_patterns`)
 
 ## Design Echo Pass (Deep+ Effort)
 

.claude/agents/plan-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: plan-reviewer
 description: "Reviews execution plans for completeness, risks, and feasibility. Use before approving a plan for implementation."
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_map, mcp__dev-agent__dev_patterns
 model: opus
 color: purple
 ---
@@ -16,12 +16,12 @@ This agent **NEVER modifies plans**. It reports issues for the author to fix.
 
 ### Pass 1: Engineer Review
 
-Read the plan as a senior engineer. Check:
+Read the plan as a senior engineer. Use `dev_map` to verify structure claims, `dev_refs` to confirm dependency assertions, and `dev_patterns` to check if proposed patterns match existing conventions.
 
-1. **Context** — Does it accurately describe what exists today? (Verify by reading the actual code)
+1. **Context** — Does it accurately describe what exists today? (Verify with `dev_map` and reading actual code)
 2. **Architecture** — Does the proposed design fit the existing monorepo structure?
 3. **Parts breakdown** — Are parts sized correctly? (Each should be 1-2 commits)
-4. **Dependencies** — Are cross-package dependencies identified?
+4. **Dependencies** — Are cross-package dependencies identified? (Verify with `dev_refs`)
 5. **Build order** — Does the implementation order respect the build dependency chain?
 6. **Breaking changes** — Are they identified and migration paths described?
 

.claude/agents/pr-composer.md

@@ -1,7 +1,7 @@
 ---
 name: pr-composer
 description: "Prepares code for pull request. Runs validation, reviews diff, and composes PR description. Use after completing a feature or fix."
-tools: Read, Glob, Grep, Bash
+tools: Read, Glob, Grep, Bash, mcp__dev-agent__dev_map
 model: sonnet
 ---
 
@@ -31,6 +31,8 @@ git diff main...HEAD
 git log main..HEAD --oneline
 ```
 
+Use `dev_map` to understand the structural impact of changes and identify which areas of the codebase were modified.
+
 Review all changes for:
 
 #### Package Architecture

.claude/agents/quality-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: quality-reviewer
 description: "Quality-focused code reviewer. Checks tests, conventions, readability, simplification. Caps suggestions at 5 per review."
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, mcp__dev-agent__dev_search, mcp__dev-agent__dev_patterns
 model: sonnet
 color: blue
 ---
@@ -47,7 +47,10 @@ Maximum **5 SUGGESTION items** per review. If more found, pick the top 5 and not
 - [ ] MCP adapters follow the adapter pattern consistently
 
 ### Readability & Simplification
-- [ ] No code duplicating existing utilities
+
+Use `dev_patterns` to find similar code and detect duplication. Use `dev_search` to check if a utility already exists before flagging missing abstractions.
+
+- [ ] No code duplicating existing utilities — verify with `dev_patterns` and `dev_search`
 - [ ] Functions reasonably sized (consider splitting if >50 lines)
 - [ ] Complex logic has comments explaining "why", not "what"
 - [ ] No premature abstractions for one-time operations

.claude/agents/quick-scout.md

@@ -1,7 +1,7 @@
 ---
 name: quick-scout
 description: "Fast codebase explorer. Use for finding code, understanding patterns, tracing data flows, and answering 'where is X?' questions."
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, mcp__dev-agent__dev_search, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_map
 model: haiku
 color: blue
 ---
@@ -25,9 +25,11 @@ Do NOT guess at architectural reasoning or make recommendations.
 
 ## Workflow
 
-1. **Search** — Use Glob for file patterns, Grep for content
-2. **Verify** — Read the file to confirm the match
-3. **Report** — Concise, factual answer with file paths and line numbers
+1. **Search** — Always start with `dev_search`. It finds code by meaning, not just keywords. Only fall back to Grep for exact string matches or Glob for file patterns.
+2. **Trace** — For "who calls X?" or "what does X call?", use `dev_refs`. Do not grep for function names when `dev_refs` can trace the graph directly.
+3. **Map** — For "what's the structure?" or "what changed recently?", use `dev_map`.
+4. **Verify** — Read the file to confirm the match
+5. **Report** — Concise, factual answer with file paths and line numbers
 
 ## Dev-Agent Quick Reference
 

.claude/agents/research-planner.md

@@ -1,7 +1,7 @@
 ---
 name: research-planner
 description: "Investigation planner. Use when you need to understand a problem space before implementing. Produces a research plan, not code."
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, mcp__dev-agent__dev_search, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_map, mcp__dev-agent__dev_patterns
 model: sonnet
 color: cyan
 ---
@@ -12,6 +12,13 @@ Plans investigations before jumping into implementation. Produces a structured r
 
 This agent **NEVER writes code**. It produces investigation plans.
 
+## MCP Tools — Use These to Map the Territory
+
+- **`dev_search`** — Find relevant code areas by meaning. Start broad ("authentication middleware", "vector storage") to discover what exists before diving in.
+- **`dev_map`** — Get codebase structure with change frequency. Use early to understand scope and identify hot spots.
+- **`dev_patterns`** — Analyze existing patterns before proposing new ones. Find similar implementations, error handling conventions, and type patterns.
+- **`dev_refs`** — Trace cross-package dependencies. Understand what depends on what before proposing changes.
+
 ## When to Use
 
 - Before starting a feature that touches unfamiliar parts of the codebase
@@ -22,10 +29,11 @@ This agent **NEVER writes code**. It produces investigation plans.
 ## Workflow
 
 1. **Clarify the goal** — What are we trying to understand or achieve?
-2. **Map the territory** — What parts of the codebase are relevant?
+2. **Map the territory** — Use `dev_map` for structure, `dev_search` to find relevant areas, `dev_patterns` to understand conventions
 3. **Identify unknowns** — What do we need to learn before proceeding?
-4. **Plan the investigation** — Ordered steps with specific files/functions to examine
-5. **Estimate scope** — How big is this? Should we break it down?
+4. **Trace dependencies** — Use `dev_refs` to understand cross-package impact
+5. **Plan the investigation** — Ordered steps with specific files/functions to examine
+6. **Estimate scope** — How big is this? Should we break it down?
 
 ## Output Format
 

.claude/agents/security-reviewer.md

@@ -1,7 +1,7 @@
 ---
 name: security-reviewer
 description: "Security-focused code reviewer. Checks dependency safety, injection vectors, secrets, and data exposure. Reports CRITICAL and WARNING only."
-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash, mcp__dev-agent__dev_search, mcp__dev-agent__dev_refs, mcp__dev-agent__dev_patterns
 model: opus
 color: red
 ---
@@ -14,6 +14,8 @@ This agent **NEVER modifies code**. It reports issues for the developer to fix.
 
 ## Checklist
 
+Use `dev_search` to find security-sensitive code ("user input", "shell execution", "token handling"). Use `dev_patterns` to find similar patterns across the codebase — if one injection vector exists, the same pattern likely appears elsewhere. Use `dev_refs` to trace how user input flows through the system.
+
 ### Command Injection
 - [ ] No unsanitized user input passed to `child_process`, `exec`, `execSync`, or shell commands
 - [ ] GitHub CLI calls (`gh`) use parameterized arguments, not string interpolation

CLAUDE.md

@@ -102,6 +102,28 @@ plan-reviewer     — two-pass plan review (engineer + SDET)
 research-planner  — investigation planning before implementation
 ```
 
+### Agent → MCP Tool Matrix
+
+Agents dogfood the dev-agent MCP tools. ★ = high impact, ● = useful.
+
+```
+┌───────────────────┬────────────┬──────────┬─────────┬──────────────┐
+│       Agent       │ dev_search │ dev_refs │ dev_map │ dev_patterns │
+├───────────────────┼────────────┼──────────┼─────────┼──────────────┤
+│ bug-investigator  │     ★      │    ★     │    ●    │              │
+│ quick-scout       │     ★      │    ★     │    ●    │              │
+│ research-planner  │     ★      │    ●     │    ★    │      ★       │
+│ logic-reviewer    │     ●      │    ★     │         │      ●       │
+│ security-reviewer │     ★      │    ★     │         │      ★       │
+│ quality-reviewer  │     ●      │          │         │      ★       │
+│ plan-reviewer     │            │    ★     │    ★    │      ●       │
+│ pr-composer       │            │          │    ●    │              │
+│ code-reviewer*    │            │          │         │              │
+└───────────────────┴────────────┴──────────┴─────────┴──────────────┘
+
+* code-reviewer is an orchestrator — it delegates to security/logic/quality reviewers.
+```
+
 ---
 
 ## Plans (`.claude/da-plans/`)