Repo Map

---
name: repo-map
version: 1.0.0
description: "Scan your projects directory and maintain a structured repository map with tech stacks, git metadata, and cross-repo context. Use when you need to find repos, understand project relationships, check what changed recently, or get cross-project awareness. Triggers on: 'show me the map', 'which repo', 'project overview', 'what repos do I have', '/repo-map'."
---

# Repo Map — Cross-Project Awareness for AI Agents

You have access to a repository map system. When the user asks about their projects, repos, tech stacks, or needs cross-project context, use this skill.

## What to Read

1. Read the repo map markdown file at `{MAP_DIR}/REPO-MAP.md` for structured descriptions, categories, and relationships
2. Read `{MAP_DIR}/last-scan.json` for machine-readable scan data including recent commits, tech stacks, and file counts

Replace `{MAP_DIR}` with the actual path to the MAP directory in the user's projects root.

## How to Respond

Based on the user's question:

1. **"Which repo does X?"** — Search the map for matching tech stacks, descriptions, or categories. Return the repo name, path, and relevant details.

2. **"What changed recently?"** — Check `last_commit_date` and `last_modified` fields in last-scan.json. Sort by most recent. For deeper history, run `git log --oneline -5` in the relevant repos.

3. **"How do these projects relate?"** — Look at the Cross-Cutting Themes section in REPO-MAP.md. Check for shared tech stacks, GitHub orgs, and lineage notes.

4. **"Project overview"** — Summarize the Quick Reference table: category counts, key repos per category, and overall stats (total repos, how many have git, how many have CLAUDE.md).

5. **"Find repos using [technology]"** — Check both `detected_stack` in last-scan.json AND the Stack field in REPO-MAP.md (the markdown may have more detail from manual annotation).

## Keeping the Map Current

If the user mentions a new project or you notice the scan is stale (check `scan_date` in last-scan.json):

```bash
bash {MAP_DIR}/scan-repos.sh
```

This regenerates last-scan.json. For a full reconciliation that also updates REPO-MAP.md:

```bash
bash {MAP_DIR}/update-map.sh
```

## Setup Instructions (First Time)

If the MAP system doesn't exist yet, help the user set it up:

1. Create the MAP directory:
   ```bash
   mkdir -p ~/Projects/MAP
   ```

2. Create `scan-repos.sh` — a shell script that:
   - Iterates over all directories in the projects root
   - For each directory, collects: name, is_git, last_commit, remote_url, branch, has_claude_md, has_readme, has_package_json, detected_stack (from manifest files), file_count, subdir_count, last_modified
   - Uses `jq` to safely encode all strings (prevents shell injection from repo names or commit messages)
   - Writes atomically (temp file + mv) to prevent partial reads
   - Detects tech stacks from: package.json (Next.js, React, Vue, Express, TypeScript, Electron, Vite, Tailwind, Prisma), Cargo.toml (Rust), Package.swift (Swift), go.mod (Go), pyproject.toml/requirements.txt (Python)

3. Create `update-map.sh` — runs the scan then invokes Claude Code to reconcile REPO-MAP.md

4. (Optional) Schedule daily updates via launchd (macOS) or cron (Linux):
   ```bash
   # macOS launchd example — runs at 10:32am daily
   cat > ~/Library/LaunchAgents/com.user.map-updater.plist << 'EOF'
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <key>Label</key>
       <string>com.user.map-updater</string>
       <key>ProgramArguments</key>
       <array>
           <string>/path/to/MAP/update-map.sh</string>
       </array>
       <key>StartCalendarInterval</key>
       <dict>
           <key>Hour</key>
           <integer>10</integer>
           <key>Minute</key>
           <integer>32</integer>
       </dict>
       <key>StandardOutPath</key>
       <string>/path/to/MAP/cron.log</string>
       <key>StandardErrorPath</key>
       <string>/path/to/MAP/cron-error.log</string>
       <key>EnvironmentVariables</key>
       <dict>
           <key>PATH</key>
           <string>/Users/you/.local/bin:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
       </dict>
   </dict>
   </plist>
   EOF
   launchctl load ~/Library/LaunchAgents/com.user.map-updater.plist
   ```

   **Important:** Include the path to your Claude CLI binary in the PATH. Check with `which claude`.

$ARGUMENTS