From a288f3704fa9f2c386f8e956e0a1c1b2e3567779 Mon Sep 17 00:00:00 2001 From: prosdev Date: Mon, 30 Mar 2026 23:21:41 -0700 Subject: [PATCH 1/2] feat(agents): dogfood dev-agent MCP tools in Claude agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Give our own agents access to the MCP tools they build and maintain. Each agent gets the tools most relevant to its workflow — semantic search for investigators, ref tracing for reviewers, pattern analysis for quality checks. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/bug-investigator.md | 16 ++++++++++++++-- .claude/agents/logic-reviewer.md | 8 ++++++-- .claude/agents/plan-reviewer.md | 8 ++++---- .claude/agents/pr-composer.md | 4 +++- .claude/agents/quality-reviewer.md | 7 +++++-- .claude/agents/quick-scout.md | 10 ++++++---- .claude/agents/research-planner.md | 16 ++++++++++++---- .claude/agents/security-reviewer.md | 4 +++- CLAUDE.md | 20 ++++++++++++++++++++ 9 files changed, 73 insertions(+), 20 deletions(-) diff --git a/.claude/agents/bug-investigator.md b/.claude/agents/bug-investigator.md index fbcc156..e4fa880 100644 --- a/.claude/agents/bug-investigator.md +++ b/.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,6 +10,14 @@ 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 @@ -17,11 +25,13 @@ Systematically traces issues through the dev-agent monorepo. Reproduces, traces, 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/` | diff --git a/.claude/agents/logic-reviewer.md b/.claude/agents/logic-reviewer.md index 0910358..fde9802 100644 --- a/.claude/agents/logic-reviewer.md +++ b/.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 +- [ ] Use `dev_patterns` to check if error handling patterns are consistent with existing code ## Design Echo Pass (Deep+ Effort) diff --git a/.claude/agents/plan-reviewer.md b/.claude/agents/plan-reviewer.md index fa5f9b6..39ac624 100644 --- a/.claude/agents/plan-reviewer.md +++ b/.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? diff --git a/.claude/agents/pr-composer.md b/.claude/agents/pr-composer.md index b569f34..5534a1e 100644 --- a/.claude/agents/pr-composer.md +++ b/.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, mcp__dev-agent__dev_status 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. Use `dev_status` to verify the index is healthy before PR. + Review all changes for: #### Package Architecture diff --git a/.claude/agents/quality-reviewer.md b/.claude/agents/quality-reviewer.md index 5916b3a..ac47fd3 100644 --- a/.claude/agents/quality-reviewer.md +++ b/.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 diff --git a/.claude/agents/quick-scout.md b/.claude/agents/quick-scout.md index 740004c..65aa084 100644 --- a/.claude/agents/quick-scout.md +++ b/.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** — Start with `dev_search` for conceptual queries ("authentication flow", "error handling"). Fall back to Grep for exact string matches and Glob for file patterns. +2. **Trace** — Use `dev_refs` to find callers/callees when tracing usage across packages. Faster and more complete than grepping for function names. +3. **Map** — Use `dev_map` when asked about codebase structure or to identify high-churn areas. +4. **Verify** — Read the file to confirm the match +5. **Report** — Concise, factual answer with file paths and line numbers ## Dev-Agent Quick Reference diff --git a/.claude/agents/research-planner.md b/.claude/agents/research-planner.md index be14796..32b6b89 100644 --- a/.claude/agents/research-planner.md +++ b/.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 diff --git a/.claude/agents/security-reviewer.md b/.claude/agents/security-reviewer.md index fe98891..d1adca9 100644 --- a/.claude/agents/security-reviewer.md +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index b9fd978..c1c35bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,6 +102,26 @@ 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 │ dev_status │ dev_health │ +├───────────────────┼────────────┼──────────┼─────────┼──────────────┼────────────┼────────────┤ +│ bug-investigator │ ★ │ ★ │ ● │ │ │ │ +│ quick-scout │ ★ │ ★ │ ● │ │ │ │ +│ research-planner │ ★ │ ● │ ★ │ ★ │ │ │ +│ logic-reviewer │ ● │ ★ │ │ ● │ │ │ +│ security-reviewer │ ★ │ ● │ │ ★ │ │ │ +│ quality-reviewer │ ● │ │ │ ★ │ │ │ +│ plan-reviewer │ │ ★ │ ★ │ ● │ │ │ +│ pr-composer │ │ │ ● │ │ ● │ │ +│ code-reviewer │ │ │ │ │ │ │ +└───────────────────┴────────────┴──────────┴─────────┴──────────────┴────────────┴────────────┘ +``` + --- ## Plans (`.claude/da-plans/`) From 9899a983b3fcd69d58c264b5f070403c3528a80d Mon Sep 17 00:00:00 2001 From: prosdev Date: Mon, 30 Mar 2026 23:26:23 -0700 Subject: [PATCH 2/2] fix(agents): address code review feedback on MCP tool assignments - Fix checklist phrasing in logic-reviewer to match boolean assertion style - Make quick-scout workflow more prescriptive for haiku model - Bump security-reviewer dev_refs to high-impact (taint tracking) - Drop unused dev_health and dev_status columns from matrix - Add footnote explaining code-reviewer is an orchestrator Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/logic-reviewer.md | 2 +- .claude/agents/pr-composer.md | 4 ++-- .claude/agents/quick-scout.md | 6 +++--- CLAUDE.md | 28 +++++++++++++++------------- 4 files changed, 21 insertions(+), 19 deletions(-) diff --git a/.claude/agents/logic-reviewer.md b/.claude/agents/logic-reviewer.md index fde9802..7bf8687 100644 --- a/.claude/agents/logic-reviewer.md +++ b/.claude/agents/logic-reviewer.md @@ -70,7 +70,7 @@ Use `dev_refs` to trace caller/callee chains across package boundaries. Use `dev - [ ] 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 -- [ ] Use `dev_patterns` to check if error handling patterns are consistent with existing code +- [ ] Error handling patterns are consistent with existing code (verify with `dev_patterns`) ## Design Echo Pass (Deep+ Effort) diff --git a/.claude/agents/pr-composer.md b/.claude/agents/pr-composer.md index 5534a1e..78468fd 100644 --- a/.claude/agents/pr-composer.md +++ b/.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, mcp__dev-agent__dev_map, mcp__dev-agent__dev_status +tools: Read, Glob, Grep, Bash, mcp__dev-agent__dev_map model: sonnet --- @@ -31,7 +31,7 @@ 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. Use `dev_status` to verify the index is healthy before PR. +Use `dev_map` to understand the structural impact of changes and identify which areas of the codebase were modified. Review all changes for: diff --git a/.claude/agents/quick-scout.md b/.claude/agents/quick-scout.md index 65aa084..c4246a8 100644 --- a/.claude/agents/quick-scout.md +++ b/.claude/agents/quick-scout.md @@ -25,9 +25,9 @@ Do NOT guess at architectural reasoning or make recommendations. ## Workflow -1. **Search** — Start with `dev_search` for conceptual queries ("authentication flow", "error handling"). Fall back to Grep for exact string matches and Glob for file patterns. -2. **Trace** — Use `dev_refs` to find callers/callees when tracing usage across packages. Faster and more complete than grepping for function names. -3. **Map** — Use `dev_map` when asked about codebase structure or to identify high-churn areas. +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 diff --git a/CLAUDE.md b/CLAUDE.md index c1c35bc..5f95ba8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,19 +107,21 @@ research-planner — investigation planning before implementation Agents dogfood the dev-agent MCP tools. ★ = high impact, ● = useful. ``` -┌───────────────────┬────────────┬──────────┬─────────┬──────────────┬────────────┬────────────┐ -│ Agent │ dev_search │ dev_refs │ dev_map │ dev_patterns │ dev_status │ dev_health │ -├───────────────────┼────────────┼──────────┼─────────┼──────────────┼────────────┼────────────┤ -│ bug-investigator │ ★ │ ★ │ ● │ │ │ │ -│ quick-scout │ ★ │ ★ │ ● │ │ │ │ -│ research-planner │ ★ │ ● │ ★ │ ★ │ │ │ -│ logic-reviewer │ ● │ ★ │ │ ● │ │ │ -│ security-reviewer │ ★ │ ● │ │ ★ │ │ │ -│ quality-reviewer │ ● │ │ │ ★ │ │ │ -│ plan-reviewer │ │ ★ │ ★ │ ● │ │ │ -│ pr-composer │ │ │ ● │ │ ● │ │ -│ code-reviewer │ │ │ │ │ │ │ -└───────────────────┴────────────┴──────────┴─────────┴──────────────┴────────────┴────────────┘ +┌───────────────────┬────────────┬──────────┬─────────┬──────────────┐ +│ 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. ``` ---