gh-awudevelop-claude-plugins-session/commands/project-maps-load.md

Project Maps Load Command

Load and display project context maps with tiered loading.

Usage

/project-maps-load [--tier <1|2|3|4>] [--map <map-name>]

Options

• --tier <N>: Load all maps from specific tier (1, 2, 3, or 4)
• --map <name>: Load specific map by name
• No options: Load Tier 1 (summary + quick-queries)

Tier Levels

Tier 1 (Always loaded, ~3KB):

• summary.json - Project overview and statistics
• quick-queries.json - Pre-computed answers to common questions

Tier 2 (On demand, ~10KB):

• tree.json - Directory structure
• existence-proofs.json - File manifests and negative space

Tier 3 (When needed, ~60KB):

• metadata.json - Comprehensive file metadata
• content-summaries.json - Exports, imports, entities
• indices.json - Navigation indices by type/role/size/recency

Tier 4 (Deep analysis, ~10KB):

• dependencies-forward.json - Import graphs
• dependencies-reverse.json - Who imports what
• relationships.json - Dependency chains
• issues.json - Broken imports, circular deps, unused files

Implementation

Step 1: Check if Maps Exist

First, verify maps exist for current project:

cd {working_directory}
node ${CLAUDE_PLUGIN_ROOT}/cli/lib/map-loader.js . --staleness-only

If no maps exist (exit code 1), show error:

❌ No project maps found

Generate maps first:
  /project-maps-generate

Step 2: Parse Arguments and Determine Load Mode

Parse command arguments:

const args = process.argv.slice(2);
let loadMode = 'tier';
let tierLevel = 1;
let mapName = null;

if (args.includes('--tier')) {
  const tierIndex = args.indexOf('--tier');
  tierLevel = parseInt(args[tierIndex + 1]) || 1;
  loadMode = 'tier';
}

if (args.includes('--map')) {
  const mapIndex = args.indexOf('--map');
  mapName = args[mapIndex + 1];
  loadMode = 'single';
}

Step 3: Load Maps

For Tier Loading:

node ${CLAUDE_PLUGIN_ROOT}/cli/lib/map-loader.js . --tier {tier_level}

For Single Map Loading:

node ${CLAUDE_PLUGIN_ROOT}/cli/lib/map-loader.js . {map_name}

The loader will:

1. Decompress maps automatically
2. Check staleness and show warnings
3. Return the map data

Step 4: Display Results

Tier 1 Display (Summary):

✓ Tier 1 maps loaded

Project Overview:
  Name: {project_name}
  Path: {project_path}
  Files: {total_files}
  Size: {total_size}
  Primary languages: {languages}

Framework: {framework_name} ({framework_type})

Quick Answers:
  • Entry points: {entry_points}
  • Test location: {test_location}
  • Largest files: {largest_files}
  • Recently modified: {recent_files}

Staleness: {staleness_score}/100 ({staleness_level})

Next steps:
  • Load more detail: /project-maps-load --tier 2
  • Query specific info: /project-maps-query
  • Refresh maps: /project-maps-refresh

Tier 2 Display (Structure):

✓ Tier 2 maps loaded

Directory Structure:
{tree_visualization}

Top-level directories:
  • src/ ({file_count} files)
  • tests/ ({file_count} files)
  • config/ ({file_count} files)

File Existence:
  ✓ package.json
  ✓ tsconfig.json
  ✓ .gitignore
  ✗ jest.config.js (missing)
  ✗ .env.example (missing)

Tier 3 Display (Detailed Metadata):

✓ Tier 3 maps loaded

Detailed File Metadata: {total_files} files

By Type:
  • TypeScript: {ts_count} files ({ts_size})
  • JavaScript: {js_count} files ({js_size})
  • JSON: {json_count} files ({json_size})

By Role:
  • Source: {source_count} files
  • Tests: {test_count} files
  • Config: {config_count} files

Content Summaries:
  Top exports:
    • {file}: {exports}
    • {file}: {exports}

Indices loaded:
  • By type: {type_count} types
  • By role: {role_count} roles
  • By size: {size_buckets} buckets
  • By recency: Last {recent_days} days

Tier 4 Display (Dependencies):

✓ Tier 4 maps loaded

Dependency Analysis:

Forward Dependencies:
  • {file} imports from {import_count} sources
  • {file} imports from {import_count} sources

Reverse Dependencies (Most imported):
  1. {file} - imported by {count} files
  2. {file} - imported by {count} files
  3. {file} - imported by {count} files

Issues Detected:
  ⚠️  Circular dependencies: {circular_count}
  ⚠️  Broken imports: {broken_count}
  ⚠️  Unused files: {unused_count}

Relationship Metrics:
  • Max dependency depth: {max_depth}
  • Average dependencies per file: {avg_deps}
  • Tightly coupled modules: {coupled_count}

Single Map Display:

Show the specific map data in formatted JSON:

✓ Map loaded: {map_name}

{formatted_json_output}

Staleness: {score}/100
Size: {compressed_size} compressed ({original_size} original, {ratio}% compression)

Step 5: Staleness Warning

If staleness score >= 30, show warning (automatically done by loader):

⚠️  Maps may be outdated
   Staleness: {score}/100 - {recommendation}
   Consider running: /project-maps-refresh --incremental

Error Handling

Maps not found:

❌ No project maps found

Generate maps first:
  /project-maps-generate

Invalid tier:

❌ Invalid tier level: {tier}

Valid tiers: 1, 2, 3, or 4

Map not found:

❌ Map not found: {map_name}

Available maps:
  • summary
  • tree
  • metadata
  • content-summaries
  • indices
  • existence-proofs
  • quick-queries
  • dependencies-forward
  • dependencies-reverse
  • relationships
  • issues

Load failed:

❌ Failed to load maps: {error_message}

Try:
  1. Regenerate maps: /project-maps-generate
  2. Check file permissions
  3. Verify maps directory exists

Performance Notes

• Tier 1: Instant load (~3KB)
• Tier 2: Very fast (~10KB)
• Tier 3: Fast (~60KB)
• Tier 4: Fast (~10KB)
• Single map: Depends on map size
• All decompression happens automatically

Examples

# Load Tier 1 (default)
/project-maps-load

# Load Tier 2 (directory structure)
/project-maps-load --tier 2

# Load Tier 3 (detailed metadata)
/project-maps-load --tier 3

# Load Tier 4 (dependencies)
/project-maps-load --tier 4

# Load specific map
/project-maps-load --map summary
/project-maps-load --map dependencies-forward