Map Codebase

Map Codebase

Generate PROJECT_MAP.md with project structure analysis for efficient agent navigation.

Usage

• /map - Generate new PROJECT_MAP.md
• /map --refresh - Update existing map (preserves manual notes)

Step 1: Check for Refresh Mode

If PROJECT_MAP.md exists and --refresh wasn't specified, warn and exit:

• "PROJECT_MAP.md already exists. Use /map --refresh to update."

If --refresh specified, preserve the "Architecture Notes" section for later.

Step 2: Detect Tech Stack

Run these bash commands to detect the technology stack:

echo "Detecting tech stack..."

# Node.js / TypeScript
if [ -f "package.json" ]; then
  echo "- Language: JavaScript/TypeScript"
  if [ -f "yarn.lock" ]; then echo "- Package Manager: yarn"
  elif [ -f "pnpm-lock.yaml" ]; then echo "- Package Manager: pnpm"  
  else echo "- Package Manager: npm"; fi
  
  # Framework detection
  if grep -q '"next"' package.json 2>/dev/null; then echo "- Framework: Next.js"
  elif grep -q '"react"' package.json 2>/dev/null; then echo "- Framework: React"
  elif grep -q '"vue"' package.json 2>/dev/null; then echo "- Framework: Vue"
  elif grep -q '"express"' package.json 2>/dev/null; then echo "- Framework: Express"
  fi
fi

# Rust
if [ -f "Cargo.toml" ]; then
  echo "- Language: Rust"
  echo "- Package Manager: cargo"
fi

# Go  
if [ -f "go.mod" ]; then
  echo "- Language: Go"
  echo "- Package Manager: go mod"
fi

# Python
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  echo "- Language: Python"
  if [ -f "poetry.lock" ]; then echo "- Package Manager: poetry"
  elif [ -f "Pipfile" ]; then echo "- Package Manager: pipenv"
  else echo "- Package Manager: pip"; fi
fi

Step 3: Generate Directory Structure

# Use tree if available (preferred)
if command -v tree &> /dev/null; then
  tree -L 3 -I 'node_modules|dist|build|.git|__pycache__|.venv|target|vendor' --dirsfirst
else
  # Fallback to find
  find . -maxdepth 3 -type d \
    -not -path './node_modules/*' \
    -not -path './dist/*' \
    -not -path './.git/*' | sort
fi

Step 4: Identify Key Files

echo "=== Configuration Files ==="
find . -maxdepth 2 \( -name "*.json" -o -name "*.yaml" -o -name "*.toml" -o -name "*.config.*" \) \
  -not -path './node_modules/*' 2>/dev/null | head -15

echo "=== Documentation ==="
find . -maxdepth 2 \( -name "README*" -o -name "CLAUDE*" -o -name "*.md" \) \
  -not -path './node_modules/*' 2>/dev/null | head -10

echo "=== Entry Points ==="
find . -maxdepth 3 \( -name "main.*" -o -name "index.*" -o -name "app.*" -o -name "cli.*" \) \
  -not -path './node_modules/*' 2>/dev/null | head -10

Step 5: Write PROJECT_MAP.md

Using the information gathered, create PROJECT_MAP.md with this structure:

# Project Map: [project-name]

> Auto-generated by `/map`. Last updated: [date]

## Tech Stack

| Component | Value |
|-----------|-------|
| Language | [from Step 2] |
| Package Manager | [from Step 2] |
| Framework | [from Step 2 or N/A] |

## Directory Structure

\`\`\`
[output from Step 3]
\`\`\`

## Key Files

### Configuration
- [list from Step 4]

### Documentation  
- [list from Step 4]

### Entry Points
- [list from Step 4]

## Architecture Notes

<!-- This section is preserved on /map --refresh -->
<!-- Add your own architectural notes, patterns, data flow descriptions -->

Step 6: Completion

After writing PROJECT_MAP.md:

1. Show summary: "Generated PROJECT_MAP.md"
2. List counts: "[X] config files, [Y] docs, [Z] entry points identified"
3. Remind: "Run /map --refresh after structural changes"

Agent Usage

When PROJECT_MAP.md exists:

1. Read it first before exploring unknown codebases
2. Reference Key Files to find important files quickly
3. Skip redundant tree/find commands - use the cached structure
4. Reduces file exploration by ~60% for typical tasks