@tyroneross/navgator 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "navgator",
+  "version": "0.1.0",
+  "description": "Architecture connection tracker - know your stack before you change it",
+  "author": {
+    "name": "Tyrone Ross"
+  },
+  "homepage": "https://github.com/tyroneross/navgator",
+  "license": "MIT"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tyrone Ross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,486 @@
+# NavGator
+
+**Architecture Connection Tracker for Claude Code**
+
+> Know your stack before you change it
+
+NavGator tracks architecture connections across your entire stack—packages, services, databases, queues, and infrastructure—so Claude knows what else needs to change when you modify one part of the system.
+
+## Features
+
+- **Component Detection**: Packages (npm, pip), frameworks, databases, queues, infrastructure
+- **Connection Mapping**: API → Database, Frontend → API, Queue → Handler, Service calls
+- **Impact Analysis**: "What's affected if I change X?"
+- **Change Detection**: SHA-256 file hashing tracks what changed since last scan
+- **Mermaid Diagrams**: Visual architecture diagrams
+- **Claude Code Integration**: Hooks, skills, and slash commands
+
+## Installation
+
+### As a CLI Tool
+
+```bash
+# Install globally
+npm install -g @tyroneross/navgator
+
+# Or use with npx
+npx @tyroneross/navgator scan
+```
+
+### As a Claude Code Plugin
+
+```bash
+# Clone to your plugins directory
+git clone https://github.com/tyroneross/navgator ~/.claude/plugins/navgator
+
+# Or symlink an existing clone
+ln -s /path/to/navgator ~/.claude/plugins/navgator
+```
+
+## Quick Start
+
+### 1. Scan Your Project
+
+```bash
+# Full scan (packages + connections)
+navgator scan
+
+# Quick scan (packages only, faster)
+navgator scan --quick
+
+# Verbose output
+navgator scan --verbose
+```
+
+### 2. Check Status
+
+```bash
+navgator status
+```
+
+Output:
+```
+NavGator - Architecture Status
+
+========================================
+Last scan: 1/26/2026, 12:44:09 PM (0h ago)
+Total components: 15
+Total connections: 23
+
+COMPONENTS BY TYPE:
+  npm: 8
+  service: 4
+  database: 2
+  infra: 1
+
+CONNECTIONS BY TYPE:
+  service-call: 12
+  api-calls-db: 8
+  frontend-calls-api: 3
+```
+
+### 3. Analyze Impact
+
+Before changing a component, see what's affected:
+
+```bash
+navgator impact "Stripe"
+```
+
+Output:
+```
+NavGator - Impact Analysis: Stripe
+
+========================================
+Component: Stripe
+Type: service
+Layer: external
+Purpose: Stripe payments
+
+INCOMING CONNECTIONS (3):
+These files/components USE this component:
+
+  src/api/payments.ts:45
+    Symbol: createPaymentIntent (function)
+    Code: await stripe.paymentIntents.create({...})
+
+  src/api/subscriptions.ts:23
+    Symbol: createSubscription (function)
+    Code: await stripe.subscriptions.create({...})
+
+  src/webhooks/stripe.ts:12
+    Symbol: handleWebhook (function)
+    Code: stripe.webhooks.constructEvent(...)
+
+========================================
+Files that may need changes if you modify Stripe:
+  - src/api/payments.ts
+  - src/api/subscriptions.ts
+  - src/webhooks/stripe.ts
+```
+
+### 4. View Connections
+
+```bash
+# All connections for a component
+navgator connections "BullMQ"
+
+# Only incoming connections
+navgator connections "users" --incoming
+
+# Only outgoing connections
+navgator connections "users" --outgoing
+```
+
+### 5. Generate Diagrams
+
+```bash
+# Full architecture diagram
+navgator diagram
+
+# Summary (top connected components only)
+navgator diagram --summary
+
+# Focus on specific component
+navgator diagram --focus "Stripe"
+
+# Specific layer
+navgator diagram --layer backend
+
+# Save to file
+navgator diagram --output architecture.md --markdown
+```
+
+## CLI Reference
+
+### `navgator scan`
+
+Scan project and update architecture tracking.
+
+| Option | Description |
+|--------|-------------|
+| `-q, --quick` | Packages only, skip code analysis |
+| `-c, --connections` | Focus on connection detection |
+| `-p, --prompts` | Enhanced AI prompt scanning with full content |
+| `-v, --verbose` | Detailed output |
+| `--clear` | Clear existing data before scan |
+| `--ast` | Use AST-based scanning (requires `ts-morph`) |
+
+### `navgator status`
+
+Show architecture summary.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+### `navgator impact <component>`
+
+Show what's affected by changing a component.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+### `navgator connections <component>`
+
+Show all connections for a component.
+
+| Option | Description |
+|--------|-------------|
+| `--incoming` | Only incoming connections |
+| `--outgoing` | Only outgoing connections |
+| `--json` | Output as JSON |
+
+### `navgator list`
+
+List all tracked components.
+
+| Option | Description |
+|--------|-------------|
+| `-t, --type <type>` | Filter by type (npm, service, database, etc.) |
+| `-l, --layer <layer>` | Filter by layer (frontend, backend, etc.) |
+| `--json` | Output as JSON |
+
+### `navgator diagram`
+
+Generate Mermaid architecture diagram.
+
+| Option | Description |
+|--------|-------------|
+| `-f, --focus <component>` | Center on specific component |
+| `-l, --layer <layer>` | Show specific layer only |
+| `-s, --summary` | Top connected components only |
+| `-d, --direction <dir>` | TB, BT, LR, or RL (default: TB) |
+| `--no-styles` | Disable color styling |
+| `--no-labels` | Hide connection labels |
+| `-o, --output <file>` | Save to file |
+| `-m, --max-nodes <n>` | Max nodes to show (default: 50) |
+| `--markdown` | Wrap in markdown code block |
+
+### `navgator prompts`
+
+Scan and analyze AI prompts in the codebase.
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Show full prompt content |
+| `--json` | Output as JSON |
+| `--detail <name>` | Show detailed view of specific prompt |
+
+**Example output:**
+```
+AI PROMPTS DETECTED
+============================================================
+
+Total prompts: 5
+Templates: 4
+With tools: 0
+
+By Provider:
+  anthropic: 2
+  openai: 3
+
+By Category:
+  summarization: 2
+  classification: 1
+  unknown: 2
+
+PROMPT: SYSTEM_PROMPT
+  File: src/ai/summarizer.ts:8-10
+  Provider: anthropic
+  Category: summarization
+  Purpose: System prompt for article summarization
+  Tags: has-system-prompt
+  System: "You are a helpful assistant that summarizes articles..."
+  Confidence: 100%
+```
+
+## What Gets Detected
+
+### Components
+
+| Type | Examples |
+|------|----------|
+| **Packages** | npm, pip, cargo, go, gem, composer |
+| **Frameworks** | Next.js, React, Django, FastAPI, Express |
+| **Databases** | PostgreSQL, MongoDB, Redis, Supabase, Prisma |
+| **Queues** | BullMQ, Celery, SQS, RabbitMQ |
+| **Infrastructure** | Railway, Vercel, Docker, Kubernetes, GitHub Actions |
+| **Services** | Stripe, OpenAI, Anthropic, Twilio, SendGrid, AWS S3 |
+| **AI Prompts** | Claude/OpenAI prompts with full content, variables, purpose |
+
+### Connections
+
+| Type | Description |
+|------|-------------|
+| `service-call` | Code → External service (Stripe, OpenAI, etc.) |
+| `api-calls-db` | API endpoint → Database table |
+| `frontend-calls-api` | Frontend component → API endpoint |
+| `queue-triggers` | Queue job → Handler function |
+| `prompt-location` | AI prompt definition location |
+| `prompt-usage` | Code that uses an AI prompt |
+
+## Storage
+
+Data is stored in `.claude/architecture/` within your project:
+
+```
+.claude/architecture/
+├── components/           # Individual component JSON files
+│   ├── COMP_npm_react_a1b2.json
+│   └── COMP_service_stripe_c3d4.json
+├── connections/          # Connection records
+│   └── CONN_service_call_e5f6.json
+├── index.json           # Quick lookup index
+├── graph.json           # Full connection graph
+├── hashes.json          # File hashes for change detection
+└── snapshots/           # Point-in-time backups
+```
+
+## Claude Code Integration
+
+### Hooks
+
+NavGator includes hooks that integrate with Claude Code:
+
+**SessionStart**: Checks if architecture data is stale (>24h) and suggests running `/nav-scan`.
+
+**PostToolUse (Bash)**: Detects package manager commands (`npm install`, `pip install`, etc.) and reminds to update architecture memory.
+
+### Slash Commands
+
+When installed as a Claude Code plugin:
+
+| Command | Description |
+|---------|-------------|
+| `/nav-scan` | Scan project architecture |
+| `/nav-status` | Show architecture summary |
+| `/nav-impact <component>` | Impact analysis |
+| `/nav-connections <component>` | View connections |
+| `/nav-diagram` | Generate diagram |
+| `/nav-check` | Health check (outdated packages) |
+| `/nav-export` | Export to markdown |
+
+### Skill Activation
+
+The **Architecture Awareness** skill activates when you mention:
+- "what packages", "dependencies", "tech stack"
+- "what version", "upgrade", "add library"
+- "what uses X", "what calls Y"
+- "impact of changing"
+
+## AI Prompt Tracking
+
+NavGator includes comprehensive AI prompt detection and tracking. Use `--prompts` flag or the dedicated `prompts` command.
+
+### What Gets Tracked
+
+| Field | Description |
+|-------|-------------|
+| **Location** | File path, line numbers, containing function |
+| **Content** | Full prompt content (up to 2000 chars per message) |
+| **Provider** | Anthropic (Claude), OpenAI, Azure, Google |
+| **Variables** | Template variables (`{var}`, `{{var}}`, `${var}`) |
+| **Purpose** | Extracted from nearby comments |
+| **Category** | summarization, classification, extraction, chat, etc. |
+| **Usage** | Where the prompt is called (file, line, function) |
+
+### Prompt Scanning Example
+
+```bash
+# Scan only prompts
+navgator prompts
+
+# Detailed view of a specific prompt
+navgator prompts --detail SYSTEM_PROMPT
+
+# Full scan with enhanced prompt tracking
+navgator scan --prompts --verbose
+
+# JSON output for tooling
+navgator prompts --json
+```
+
+### Prompt Categories
+
+NavGator automatically categorizes prompts:
+
+- `chat` - Conversational prompts
+- `summarization` - Content summarization
+- `extraction` - Data extraction
+- `classification` - Categorization tasks
+- `code-generation` - Writing code
+- `code-review` - Reviewing code
+- `agent` - Tool/function use
+- `translation` - Language translation
+
+## AST-Based Scanning
+
+For more accurate connection detection, install `ts-morph`:
+
+```bash
+npm install ts-morph
+```
+
+Then use the `--ast` flag:
+
+```bash
+navgator scan --ast
+```
+
+AST scanning provides:
+- Accurate import tracking
+- Method chain following (`stripe.customers.create()`)
+- Higher confidence scores
+
+Without `ts-morph`, NavGator uses regex-based scanning which is faster but may miss some patterns.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NAVGATOR_MODE` | Storage mode: `local` or `shared` | `local` |
+| `NAVGATOR_PATH` | Custom storage path | `.claude/architecture` |
+| `NAVGATOR_AUTO_SCAN` | Auto-scan on session start | `false` |
+| `NAVGATOR_HEALTH_CHECK` | Enable health checks | `false` |
+| `NAVGATOR_SCAN_DEPTH` | `shallow` or `deep` | `shallow` |
+| `NAVGATOR_CONFIDENCE` | Confidence threshold (0-1) | `0.6` |
+| `NAVGATOR_MAX_RESULTS` | Max results per query | `20` |
+
+## Example Workflows
+
+### Adding a New Integration
+
+```bash
+# 1. Check current architecture
+navgator status
+
+# 2. Install package
+npm install stripe
+
+# 3. Update architecture
+navgator scan --quick
+
+# 4. Implement integration
+# ... write code ...
+
+# 5. Full rescan to detect new connections
+navgator scan
+```
+
+### Before Database Migration
+
+```bash
+# 1. Check what uses the table
+navgator impact "users"
+
+# 2. Review affected files
+navgator connections "users" --incoming
+
+# 3. Generate diagram for documentation
+navgator diagram --focus "users" --output migration-plan.md --markdown
+
+# 4. Make changes to each affected file
+# 5. Rescan to verify
+navgator scan
+```
+
+### Understanding a New Codebase
+
+```bash
+# 1. Full scan
+navgator scan --verbose
+
+# 2. See overall architecture
+navgator diagram --summary
+
+# 3. List all services
+navgator list --type service
+
+# 4. Understand a specific component
+navgator impact "Supabase"
+```
+
+## Dependencies
+
+**Required:**
+- `commander` - CLI framework
+- `glob` - File pattern matching
+
+**Optional:**
+- `ts-morph` - AST-based scanning (install separately)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read the contributing guidelines first.
+
+## Links
+
+- [GitHub Repository](https://github.com/tyroneross/navgator)
+- [Issue Tracker](https://github.com/tyroneross/navgator/issues)
+- [Claude Code](https://claude.ai/claude-code)

package/agents/architecture-advisor.md

@@ -0,0 +1,109 @@
+---
+name: architecture-advisor
+description: Specialized agent for architecture decisions, dependency management, and impact analysis. Use when planning significant changes to the tech stack.
+color: "#3B82F6"
+tools: ["Bash", "Read", "Glob", "Grep", "WebSearch"]
+---
+
+# Architecture Advisor Agent
+
+You are an architecture advisor specialized in analyzing technology stacks, understanding component relationships, and planning safe changes.
+
+## Your Capabilities
+
+1. **Stack Analysis**
+   - Understand current project architecture
+   - Identify frameworks, databases, queues, and services in use
+   - Map connections between components
+
+2. **Impact Assessment**
+   - Determine what's affected by proposed changes
+   - Identify file:line locations that need updating
+   - Prioritize changes by criticality
+
+3. **Compatibility Checking**
+   - Verify new packages work with existing stack
+   - Check for version conflicts
+   - Identify peer dependency issues
+
+4. **Migration Planning**
+   - Plan safe upgrade paths
+   - Sequence changes to minimize risk
+   - Identify rollback strategies
+
+5. **Security Review**
+   - Check for vulnerable dependencies
+   - Identify security implications of changes
+   - Recommend secure alternatives
+
+## How to Use NavGator Data
+
+When advising on architecture:
+
+1. First, check if NavGator has scanned the project:
+   ```bash
+   ls -la .claude/architecture/
+   ```
+
+2. If scanned, read the index for quick overview:
+   ```bash
+   cat .claude/architecture/index.json
+   ```
+
+3. For specific impact analysis:
+   ```bash
+   npx @tyroneross/navgator impact "<component>"
+   ```
+
+4. For connection details:
+   ```bash
+   npx @tyroneross/navgator connections "<component>"
+   ```
+
+## Response Format
+
+When advising on changes:
+
+1. **Current State:** Summarize relevant architecture
+2. **Impact Analysis:** List affected components with file:line
+3. **Recommendation:** Proposed approach
+4. **Change Sequence:** Ordered steps to implement
+5. **Verification:** How to verify the change worked
+
+## Example Advisory
+
+**User:** "I want to switch from Prisma to Drizzle ORM"
+
+**Your Response:**
+
+### Current State
+Project uses Prisma for database access:
+- 12 API endpoints use Prisma client
+- 3 queue workers make DB queries
+- Connection files: src/lib/prisma.ts
+
+### Impact Analysis
+Files requiring changes:
+- src/api/users.ts:23-45 (3 queries)
+- src/api/orders.ts:15-89 (5 queries)
+- src/workers/sync.ts:34 (1 query)
+... [continue for all files]
+
+### Recommendation
+1. Install Drizzle alongside Prisma
+2. Create Drizzle schema from Prisma schema
+3. Migrate one endpoint at a time
+4. Remove Prisma after all endpoints migrated
+
+### Change Sequence
+1. `npm install drizzle-orm drizzle-kit`
+2. Create src/lib/drizzle.ts
+3. Convert src/api/users.ts (lowest risk)
+4. Test thoroughly
+5. Continue with remaining files
+...
+
+### Verification
+- Run test suite after each file
+- Compare query results between ORMs
+- Monitor for N+1 queries

package/commands/nav-check.md

@@ -0,0 +1,64 @@
+---
+description: "Run health check on architecture (outdated packages, vulnerabilities)"
+allowed-tools: ["Bash", "Read"]
+---
+
+# NavGator Health Check
+
+Run health checks on your architecture to find outdated packages, security vulnerabilities, and potential issues.
+
+**Note:** Health checks are configurable via the `NAVGATOR_HEALTH_CHECK` environment variable.
+
+## Usage
+
+```bash
+npx @tyroneross/navgator check
+```
+
+## What Gets Checked
+
+**Package Health:**
+- Outdated packages (npm outdated, pip list --outdated, etc.)
+- Security vulnerabilities (npm audit, pip-audit, etc.)
+- Deprecated packages
+
+**Connection Health:**
+- Orphaned connections (code references that no longer exist)
+- Missing imports
+- Unused dependencies
+
+## Options
+
+- `--packages`: Only check package health
+- `--connections`: Only check connection health
+- `--fix`: Attempt to auto-fix issues (careful!)
+
+## Configuration
+
+Set `NAVGATOR_HEALTH_CHECK=true` to enable automatic health checks during scans.
+
+```bash
+export NAVGATOR_HEALTH_CHECK=true
+npx @tyroneross/navgator scan  # Will include health check
+```
+
+## Output
+
+```
+Health Check Results
+====================
+
+PACKAGES:
+├── 3 outdated (2 minor, 1 major)
+│   ├── react: 18.2.0 → 18.3.0 (minor)
+│   ├── typescript: 5.3.0 → 5.4.0 (minor)
+│   └── next: 14.0.0 → 15.0.0 (major - breaking changes)
+└── 0 vulnerabilities
+
+CONNECTIONS:
+├── 2 orphaned connections
+│   ├── src/api/old-endpoint.ts:15 (file deleted)
+│   └── src/components/Legacy.tsx:42 (function removed)
+└── 1 missing import
+    └── src/utils/helpers.ts:5 → lodash (not in package.json)
+```