navgator

Find dead code — orphaned components with no connections, unused packages, unused database models

Main gator entry. Dispatches to a subcommand based on your request, or lists options if unclear. Use `gator:<subcommand>` to target a specific action directly.

Check what breaks if you change a component — blast radius analysis before modifying code

List, search, promote, and manage NavGator architecture lessons. Use when the user asks about project or cross-project architectural patterns, lesson management, or promoting a lesson from one project to global scope.

Map all LLM use cases — shows what each AI call does, which provider, and what it connects to

Specialized agent for architecture decisions, dependency management, and impact analysis. Use when planning significant changes to the tech stack.

Autonomous subagent for investigating architecture issues using NavGator MCP tools. Follows SRE-style read-only investigation before proposing changes. Deploy via the Task tool when a specific component, violation, or data-flow issue needs deep analysis.

Use this agent when the user's request requires understanding the architecture before answering — phrasings like "review architecture for X", "what's the blast radius of changing Y", "is the graph fresh", "investigate the auth flow", "should I refactor Z", "how does this connect to that", "trace this data flow", "plan a change to <component>". This agent reads NavGator's stored graph, decides whether the data is stale enough to warrant a quick incremental scan, runs that scan if needed (write-capable for `navgator scan --incremental` only), then dispatches the appropriate read-only NavGator MCP tools (`impact`, `trace`, `connections`, `review`, `dead`, `rules`) and aggregates a structured report. Examples: <example> Context: User is about to refactor the authentication flow. user: "I want to migrate auth from Lucia to Better Auth — what breaks?" assistant: "I'll dispatch the architecture-planner agent. It will check graph freshness, run an incremental scan if stale, then trace the auth component and compute blast radius before recommending a sequence." <commentary> This needs architecture context, not raw file reading. The planner agent owns scan-decision and MCP-tool orchestration. </commentary> </example> <example> Context: User asks an open-ended structural question. user: "Is the architecture graph still up-to-date with main?" assistant: "Launching the architecture-planner. It'll inspect index.json + hashes.json, decide whether incremental or full is needed, and either trigger an incremental scan or recommend a full one with reason." <commentary> Freshness-of-graph questions are exactly what this agent owns — it has the policy logic to decide what to do. </commentary> </example> <example> Context: User wants a connection trace. user: "Trace what happens when a user submits a checkout request" assistant: "Dispatching architecture-planner. It will run `navgator trace checkout-handler --agent` after confirming the graph is current, then summarize the path." <commentary> Trace requests benefit from the planner ensuring fresh data first; otherwise the trace may follow stale connections. </commentary> </example> Do NOT use this agent for: simple `/gator:scan` requests (use the scan command directly), one-shot file reads, or non-architectural questions. Do NOT auto-trigger a full scan; if state demands one, return that as a recommendation for the user to confirm.

Use this agent when NavGator needs its external boundary nodes (npm/pip/spm/cargo/go/service/llm/infra) resolved or refreshed against upstream registries — attaching canonical identity, latest version, release date, docs URL, and a freshness verdict. Typical triggers include the staleness sweep finding nodes past the 7-day freshness window, a scan surfacing boundary nodes the registry cache cannot resolve, and a user asking "are my dependencies current", "what's drifting", or "refresh the architecture map's external layer". Do NOT use it for internal code structure, database profiling, or anything requiring secrets. See "When to invoke" in the agent body for worked scenarios.

Use when user asks to show or generate an architecture diagram, visualize dependencies, export architecture docs, create architecture documentation, save architecture output, or create a mermaid diagram of their project.

Use when user asks to scan architecture, check dependencies, find outdated packages, show project structure, refresh architecture, or run a health check. Navgator scan, status, and staleness check.

Use when user asks to review architecture, check connections, navgator review, is this safe to merge, what did I break, or when scan detects architectural drift. Architectural integrity review of system flow and connections.

Use when user asks what breaks if I change X, impact of changing, what depends on, trace data flow, show connections, dependency graph, upstream/downstream, or safe to modify before refactoring.

Use when user asks to install navgator, update navgator, set up navgator, launch the dashboard, or run navgator ui maintenance.