/related

allowed-tools: Read, Grep, Glob, Bash(fd:*), Bash(rg:*), Bash(bat:*), Edit, MultiEdit
name: "Related"
description: "Navigate intelligently between related files across the codebase"
author: "wcygan"
tags: ["code","navigate"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N`
• Current directory: !`pwd`
• Project type: !`if [ -f "deno.json" ]; then echo "Deno"; elif [ -f "package.json" ]; then echo "Node.js"; elif [ -f "Cargo.toml" ]; then echo "Rust"; elif [ -f "go.mod" ]; then echo "Go"; elif [ -f "pom.xml" ]; then echo "Java"; else echo "Unknown"; fi`
• Git status: !`git status --porcelain | head -5 || echo "No git repository"`
• Test files: !`fd "\.(test|spec)\." --type f | head -5 || echo "No test files found"`
• API files: !`fd "(api|routes|handlers)" --type d | head -3 || echo "No API directories found"`
• Component files: !`fd "components" --type d | head -3 || echo "No component directories found"`
• Config files: !`fd "config" --type f | head -3 || echo "No config files found"`

Your task

Intelligently navigate between related files in the codebase, understanding patterns like test files, API endpoints, components, migrations, and more.

STEP 1: Parse arguments and determine navigation intent

Arguments: $ARGUMENTS

Parse navigation request:

• IF no arguments: Set target = current_working_file, action = "discover_all"
• IF single argument (file path): Set target = argument, action = "find_related"
• IF two arguments (file + type): Set target = argument[0], action = argument[1]
• IF includes ":" (file:location): Set target + specific_location = split on ":"

Navigation types: test, impl, api, component, migration, config, style, story

STEP 2: Analyze target file context and patterns

Create context analysis: `/tmp/navigation-context-$SESSION_ID.json`

Determine file characteristics:

• Extract file extension and directory structure
• Identify if file is: test, implementation, API, component, model, config
• Detect naming patterns and conventions used in project
• Map directory structure and framework patterns

File pattern detection:

{
  "target_file": "$ARGUMENTS",
  "session_id": "$SESSION_ID",
  "file_type": "test|impl|api|component|model|config",
  "framework": "detected_framework",
  "patterns": {
    "test_patterns": ["*.test.ts", "*_test.go", "*.spec.js"],
    "api_patterns": ["api/*", "routes/*", "handlers/*"],
    "component_patterns": ["components/*", "*.tsx", "*.jsx"]
  }
}

STEP 3: Execute intelligent file discovery based on action type

CASE action: WHEN "discover_all":

**CRITICAL: Launch parallel sub-agents for maximum performance (8-10x faster discovery)**

IMMEDIATELY deploy 5 parallel sub-agents for comprehensive file discovery:

• **Agent 1: Test & Spec Discovery**: Find all test files, specs, and related testing infrastructure
• Focus: _.test._, _.spec._, **tests**, test/, spec/ directories
• Tools: fd with test patterns, rg for test framework detection
• Expected: Complete test ecosystem mapping with usage patterns

• **Agent 2: API & Route Discovery**: Discover all API endpoints, routes, and handlers
• Focus: API routes, GraphQL schemas, RPC definitions, service endpoints
• Tools: rg for route patterns, fd for API directories, endpoint detection
• Expected: Complete API surface area with request/response patterns

• **Agent 3: Component & UI Discovery**: Locate all UI components, pages, and templates
• Focus: React/Vue/Fresh components, HTML templates, styling files
• Tools: fd for component patterns, rg for component definitions
• Expected: Complete UI component hierarchy with prop relationships

• **Agent 4: Configuration & Infrastructure**: Find all config, build, and deployment files
• Focus: Config files, environment files, build scripts, CI/CD definitions
• Tools: fd for config patterns, rg for environment variables
• Expected: Complete configuration landscape with dependencies

• **Agent 5: Documentation & Schema Discovery**: Locate docs, schemas, and architectural files
• Focus: README files, API docs, database schemas, architectural diagrams
• Tools: fd for doc patterns, rg for schema definitions
• Expected: Complete project documentation and data model mapping

**Sub-Agent Coordination:**

• Each agent saves findings to `/tmp/navigation-agents-$SESSION_ID/`
• Parallel execution provides 8-10x speed improvement over sequential discovery
• Results synthesized into unified navigation interface with cross-references
• Present categorized navigation options with intelligent recommendations

WHEN "find_related":

• Execute targeted search for file relationships
• Use project-specific patterns and conventions
• Return ranked results by relevance

WHEN "test":

• Search for existing test files using multiple patterns
• IF not found: Offer to create test file with template
• Navigate to test or create new one

WHEN "impl":

• Find implementation file from test file
• Use reverse mapping patterns
• Navigate to source implementation

WHEN "api":

• Search for API endpoints related to component/feature
• Look for route definitions and handlers
• Check for API client code

WHEN "component":

• Find UI components related to feature
• Look for React/Vue/Fresh components
• Check for component stories and styles

STEP 4: Smart file pattern matching and discovery

FOR EACH navigation type, execute pattern-based search:

**Test File Discovery Patterns:**

# From implementation to test
target_base=$(basename "$target_file" .ts)
target_dir=$(dirname "$target_file")

# Search patterns in order of preference
fd "${target_base}\\.(test|spec)\\.(ts|js|tsx|jsx)$" "$target_dir"
fd "${target_base}\\.(test|spec)\\.(ts|js|tsx|jsx)$" "tests/"
fd "${target_base}\\.(test|spec)\\.(ts|js|tsx|jsx)$" "__tests__/"

**API Endpoint Discovery:**

# Find API routes and handlers
rg -l "(router\\.(get|post|put|delete)|app\\.(get|post))" ap