---
description: Generate and maintain a cached AST repo map (symbols, imports, exports) using ast-grep for accurate drift detection and analysis
codex-description: 'Use when user asks to "create repo map", "generate repo map", "update repo map", "repo map status", "map symbols". Builds and updates AST-based repo map using ast-grep.'
argument-hint: "init|update|status|rebuild [--force] [--full]"
allowed-tools: Bash(git:*), Bash(npm:*), Read, Task, Write, AskUserQuestion
---

# /repo-map - AST Repo Map

Generate a cached repository map of symbols and imports using ast-grep. This enables faster drift detection and more accurate code context.

## Arguments

Parse from `$ARGUMENTS`:

- **Action**: `init` | `update` | `status` | `rebuild` (default: `status`)
- `--force`: Force rebuild (for `init`)
- `--full`: Force full rebuild (for `update`)

Examples:

- `/repo-map init`
- `/repo-map update --full`
- `/repo-map status`

## Execution

### 1) Load Repo Map Module

```javascript
const { getPluginRoot } = require('@awesome-slash/lib/cross-platform');
const pluginRoot = getPluginRoot('repo-map');
if (!pluginRoot) { console.error('Error: Could not locate repo-map plugin root'); process.exit(1); }
const repoMap = require(`${pluginRoot}/lib/repo-map`);
```

### 2) Parse Arguments

```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const action = (args[0] || 'status').toLowerCase();

const options = {
  force: args.includes('--force'),
  full: args.includes('--full')
};
```

### 3) Ensure ast-grep is Available

```javascript
const installed = await repoMap.checkAstGrepInstalled();
if (!installed.found || !repoMap.installer.meetsMinimumVersion(installed.version)) {
  const suggestion = repoMap.getInstallInstructions();
  const choice = await AskUserQuestion({
    questions: [{
      header: 'Install ast-grep?',
      question: 'ast-grep is required for repo-map. Install now?',
      options: [
        { label: 'Install via npm', description: 'Runs: npm install -g @ast-grep/cli' },
        { label: 'Skip for now', description: 'Show install instructions and exit' }
      ]
    }]
  });

  if (choice?.[0] === 'Install via npm') {
    await Bash('npm install -g @ast-grep/cli');
  } else {
    console.log(suggestion);
    return;
  }
}
```

### 4) Run Action

```javascript
let result;

if (action === 'init' || action === 'rebuild') {
  result = await repoMap.init(process.cwd(), {
    force: action === 'rebuild' || options.force
  });
} else if (action === 'update') {
  result = await repoMap.update(process.cwd(), { full: options.full });
} else if (action === 'status') {
  result = repoMap.status(process.cwd());
} else {
  console.log('Unknown action. Use: init | update | status | rebuild');
  return;
}

if (result?.success === false) {
  console.log(result.error || 'Repo-map failed');
  if (result.installSuggestion) console.log(result.installSuggestion);
  return;
}

if (action === 'status' && !result.exists) {
  console.log('No repo-map found. Run /repo-map init to generate one.');
  return;
}
```

### 5) Validate Results (init/update only)

After `init` or `update`, run validation using the lightweight agent:

```javascript
if (action === 'init' || action === 'rebuild' || action === 'update') {
  const summary = result?.map?.stats || result?.summary || result?.changes || {};
  const validation = await Task({
    subagent_type: 'repo-map:map-validator',
    prompt: `Validate repo-map results. Summary: ${JSON.stringify(summary)}`
  });
  console.log(validation);
}
```

## Output Format

```markdown
## Repo Map Result

**Action**: init|update|status
**Files**: <count>
**Symbols**: <count>
**Languages**: <list>
**Commit**: <hash>

### Notes
- <warnings or validation results>
```