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..7bf8687 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 +- [ ] Error handling patterns are consistent with existing code (verify with `dev_patterns`) ## 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..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 +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 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..c4246a8 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** — 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 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..5f95ba8 100644 --- a/CLAUDE.md +++ b/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/`)