feat(cli,core): dev refs CLI, callee normalization, token efficiency docs

.changeset/refs-cli.md

@@ -0,0 +1,13 @@
+---
+'@prosdevlab/dev-agent': patch
+---
+
+Add `dev refs` CLI command and fix callee path normalization
+
+- New `dev refs <name>` command: find callers and callees from the terminal
+  - `--direction callees|callers|both` to filter results
+  - `--depends-on <file>` to trace dependency paths
+  - `--json` for machine-readable output
+- Normalize callee file paths: `dist/` → `src/`, `.d.ts` → `.ts`, absolute → relative
+- Fix hot paths showing build output (`packages/logger/dist/types.d.ts` → `packages/logger/src/types.ts`)
+- Fix indexer passing empty exclude array (was bypassing scanner default exclusions)

.claude/agents/bug-investigator.md

@@ -10,13 +10,17 @@ color: orange
 
 Systematically traces issues through the dev-agent monorepo. Reproduces, traces, fixes, and prevents regression.
 
-## MCP Tools — Use These First
+## MCP Tools — Conserve Context
 
-- **`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.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
 
-Fall back to Grep/Glob for exact string matches or file patterns.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_search`** — Conceptual queries ("where does rate limiting happen"). Returns ranked snippets, not 200 grep matches.
+- **`dev_refs`** — Callers/callees of a function. Use `dependsOn` to trace dependency chains. Returns the call graph directly.
+- **`dev_map`** — Codebase structure with hot paths and subsystems. One call replaces dozens of ls/glob/read operations.
+
+Only use Grep for exact string matches where you know the literal text. Only Read files when you need the full implementation.
 
 ## Investigation Framework
 

.claude/agents/logic-reviewer.md

@@ -65,9 +65,10 @@ Every finding MUST include confidence: **HIGH** (verified from code), **MEDIUM**
 
 ### Cross-Package Data Flow (Deep+ Effort)
 
-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.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_refs` returns the call graph directly, `dev_search` finds related code by concept, `dev_patterns` compares error handling across files — each saves ~3,000-5,000 tokens vs manual file reading.
 
 - [ ] Core exports consumed correctly by CLI, MCP server, and subagents — verify with `dev_refs`
+- [ ] Dependency chains make sense — use `dev_refs` with `dependsOn` to trace file-to-file paths
 - [ ] 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`)

.claude/agents/plan-reviewer.md

@@ -12,6 +12,16 @@ Two-pass review of execution plans in `.claude/da-plans/`. Validates completenes
 
 This agent **NEVER modifies plans**. It reports issues for the author to fix.
 
+## MCP Tools — Conserve Context
+
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_map`** — Verify structure claims in the plan against actual codebase layout.
+- **`dev_refs`** — Confirm dependency assertions. Use `dependsOn` to trace dependency chains between files.
+- **`dev_patterns`** — Check if proposed patterns match existing conventions.
+
 ## Two-Pass Review
 
 ### Pass 1: Engineer Review
@@ -21,7 +31,7 @@ Read the plan as a senior engineer. Use `dev_map` to verify structure claims, `d
 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? (Verify with `dev_refs`)
+4. **Dependencies** — Are cross-package dependencies identified? (Verify with `dev_refs`. Use `dependsOn` to trace dependency chains between files.)
 5. **Build order** — Does the implementation order respect the build dependency chain?
 6. **Breaking changes** — Are they identified and migration paths described?
 

.claude/agents/quality-reviewer.md

@@ -48,7 +48,7 @@ Maximum **5 SUGGESTION items** per review. If more found, pick the top 5 and not
 
 ### Readability & Simplification
 
-Use `dev_patterns` to find similar code and detect duplication. Use `dev_search` to check if a utility already exists before flagging missing abstractions.
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_patterns` compares patterns across similar files (~500 tokens vs ~3,000 for manual reads). `dev_search` checks if a utility exists by meaning, not just name.
 
 - [ ] No code duplicating existing utilities — verify with `dev_patterns` and `dev_search`
 - [ ] Functions reasonably sized (consider splitting if >50 lines)

.claude/agents/quick-scout.md

@@ -10,6 +10,12 @@ color: blue
 
 Lightweight explorer optimized for speed and cost. Finds code, traces flows, maps dependencies.
 
+## MCP Tools — Conserve Context
+
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
 ## Capability Boundaries
 
 You excel at:
@@ -25,58 +31,12 @@ Do NOT guess at architectural reasoning or make recommendations.
 
 ## Workflow
 
-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
+1. **Search** — Start with `dev_search` for conceptual queries. Returns ranked snippets without reading files. Only fall back to Grep for exact string matches.
+2. **Trace** — For "who calls X?", use `dev_refs`. For "how does A depend on B?", use `dev_refs` with `dependsOn`. Returns the call graph directly — no grepping for function names.
+3. **Map** — For "what's the structure?", use `dev_map`. One call replaces dozens of ls/glob/read operations.
+4. **Verify** — Only Read a file when you need the full implementation, not just the location.
 5. **Report** — Concise, factual answer with file paths and line numbers
 
-## Dev-Agent Quick Reference
-
-```
-packages/
-  core/src/
-    scanner/          # ts-morph (TS/JS) and tree-sitter (Go) analysis
-    vector/           # Antfly vector storage + embeddings
-    services/         # Coordinator, search, health
-    events/           # Event bus system
-    indexer/          # Repository indexing orchestration
-    map/              # Codebase structure mapping
-    observability/    # Logger integration
-
-  cli/src/
-    commands/         # Commander.js CLI commands
-    utils/            # Formatters, logger, output helpers
-
-  mcp-server/src/
-    server/           # MCP server setup
-    adapters/         # Tool adapters (search, refs, map, inspect, status, health)
-    formatters/       # Compact and verbose output formatters
-    utils/            # Logger
-
-  subagents/src/
-    coordinator/      # Agent orchestration
-    explorer/         # Code exploration agent
-    planner/          # Planning agent
-    github/           # GitHub integration agent
-
-  logger/src/         # @prosdevlab/kero centralized logging
-  types/src/          # Shared TypeScript types
-  integrations/       # Claude Code, VS Code integrations
-  dev-agent/          # Root package (CLI entry point)
-```
-
-### Common Patterns
+## Orientation
 
-| Pattern | Location |
-|---------|----------|
-| MCP tool adapters | `packages/mcp-server/src/adapters/built-in/` |
-| Core services | `packages/core/src/services/` |
-| Scanner implementations | `packages/core/src/scanner/` |
-| CLI commands | `packages/cli/src/commands/` |
-| Subagent types | `packages/subagents/src/{agent}/` |
-| Tests | `packages/**/src/**/__tests__/` |
-| Package configs | `packages/*/package.json` |
-| Build config | `turbo.json`, `tsconfig.json` |
-| Test config | `vitest.config.ts` |
-```
+Use `dev_map` to get the current codebase structure — don't rely on memorized paths. Run `dev_map --focus packages/core --depth 3` to drill into a specific area.

.claude/agents/research-planner.md

@@ -12,12 +12,16 @@ 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
+## MCP Tools — Conserve Context
 
-- **`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.
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+- **`dev_search`** — Find relevant code areas by meaning. Returns ranked snippets, not 200 grep matches.
+- **`dev_map`** — Codebase structure with hot paths and subsystems. One call replaces dozens of ls/glob/read operations.
+- **`dev_patterns`** — Compare patterns across similar files without reading each one.
+- **`dev_refs`** — Trace cross-package dependencies. Use `dependsOn` to trace dependency chains between files.
 
 ## When to Use
 

.claude/agents/security-reviewer.md

@@ -12,9 +12,17 @@ Security-focused review for a TypeScript monorepo that processes repository data
 
 This agent **NEVER modifies code**. It reports issues for the developer to fix.
 
-## Checklist
+## MCP Tools — Conserve Context
+
+This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
 
-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.
+- **`dev_search`** — Find security-sensitive code ("user input", "shell execution", "token handling"). Returns ranked snippets.
+- **`dev_patterns`** — If one injection vector exists, the same pattern likely appears elsewhere. Scan for similar patterns across files.
+- **`dev_refs`** — Trace how user input flows through the system. Use `dependsOn` to trace dependency chains.
+
+## Checklist
 
 ### Command Injection
 - [ ] No unsanitized user input passed to `child_process`, `exec`, `execSync`, or shell commands

CLAUDE.md

@@ -22,7 +22,7 @@ Everything runs on your machine. No data leaves.
 ```
 packages/
   core/          # Scanner (ts-morph, tree-sitter for Python/Go), vector storage (Antfly), services
-  cli/           # Commander.js CLI — dev index, dev mcp install, etc.
+  cli/           # Commander.js CLI — dev index, dev search, dev refs, dev map, dev mcp install
   mcp-server/    # MCP server with 5 built-in adapters
   subagents/     # Coordinator, explorer, planner, PR agents
   integrations/  # Claude Code, VS Code, Cursor
@@ -139,16 +139,35 @@ See `.claude/da-plans/README.md` for status and format details.
 
 ---
 
-## MCP tools (5 adapters)
+## MCP tools — conserve context
+
+**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
+
+MCP tools return pre-ranked snippets. Every Grep → Read cycle burns ~3,000-5,000 tokens of context window on irrelevant matches. MCP tools return only what you need.
+
+| Instead of | Use | Tokens saved |
+|------------|-----|-------------|
+| Grep "auth" → read 10 files | `dev_search "authentication"` | ~5,000 |
+| Grep function name → read callers | `dev_refs "functionName"` | ~3,000 |
+| ls + glob + read READMEs | `dev_map` | ~2,000 |
+| Read multiple files to compare patterns | `dev_patterns filePath` | ~3,000 |
+
+Only use Grep for exact string matches where you know the literal text. Only Read files when you need the full implementation.
+
+### 5 adapters
 
 | Tool | Purpose |
 |------|---------|
 | `dev_search` | Hybrid code search — BM25 + vector + RRF (use FIRST for conceptual queries) |
-| `dev_refs` | Find callers/callees of functions |
-| `dev_map` | Codebase structure with change frequency |
+| `dev_refs` | Find callers/callees of functions. `dependsOn` traces the dependency chain between files. |
+| `dev_map` | Codebase structure with PageRank hot paths and connected subsystems |
 | `dev_patterns` | File pattern analysis (similar code, error handling, types). Takes `filePath`, not `query`. |
 | `dev_status` | Repository indexing status + Antfly stats + health checks (`section="health"`) |
 
+**Graph caching:** `dev index` builds a dependency graph (`dependency-graph.json`) saved alongside the index.
+`dev_map` and `dev_refs` load the cached graph instead of fetching all docs — scales to 50k+ docs.
+File watcher incrementally updates the graph on save.
+
 ---
 
 ## Adding a new MCP adapter
@@ -172,6 +191,13 @@ dev setup                                 # One-time: start Antfly
 dev index                                 # Index repository
 dev mcp install                           # Install for Claude Code
 dev mcp install --cursor                  # Install for Cursor
+
+# CLI tools (no MCP server needed)
+dev search "authentication"               # Semantic code search
+dev refs "functionName"                   # Find callers/callees
+dev refs "fn" --depends-on "src/db.ts"    # Trace dependency chain
+dev map                                    # Codebase structure overview
+dev map --focus packages/core --depth 3    # Focused map
 ```
 
 ---

packages/cli/src/cli.ts

@@ -7,6 +7,7 @@ import { compactCommand } from './commands/compact.js';
 import { indexCommand } from './commands/index.js';
 import { mapCommand } from './commands/map.js';
 import { mcpCommand } from './commands/mcp.js';
+import { refsCommand } from './commands/refs.js';
 import { resetCommand } from './commands/reset.js';
 import { searchCommand } from './commands/search.js';
 import { setupCommand } from './commands/setup.js';
@@ -26,6 +27,7 @@ program
 // Register commands
 program.addCommand(indexCommand);
 program.addCommand(searchCommand);
+program.addCommand(refsCommand);
 program.addCommand(mapCommand);
 program.addCommand(compactCommand);
 program.addCommand(cleanCommand);