Codemap Skill

You help users understand and map repositories by creating hierarchical codemaps.

When to Use

• User asks to understand/map a repository
• User wants codebase documentation
• Starting work on an unfamiliar codebase

Workflow

Step 1: Check for Existing State

First, check if .slim/codemap.json exists in the repo root.

If it does not exist, check for legacy state at .slim/cartography.json.

If legacy state exists: move .slim/cartography.json to .slim/codemap.json, then continue with change detection.

If .slim/codemap.json exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.

If neither file exists: Continue to Step 2 (Initialize).

Step 2: Initialize (Only if no state exists)

1. Analyze the repository structure - List files, understand directories
2. Infer patterns for core code/config files ONLY to include:
   • Include: src/**/*.ts, package.json, etc.
   • Exclude (MANDATORY): Do NOT include tests, documentation, or translations.
     • Tests: **/*.test.ts, **/*.spec.ts, tests/**, __tests__/**
     • Docs: docs/**, *.md (except root README.md if needed), LICENSE
     • Build/Deps: node_modules/**, dist/**, build/**, *.min.js
   • Respect .gitignore automatically
3. Run codemap.mjs init (scripts/codemap.mjs is relative to this skill's base directory, the host prints it as Base directory for this skill):

node scripts/codemap.mjs init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"

This creates:

• .slim/codemap.json - File and folder hashes for change detection
• Empty codemap.md files in all relevant subdirectories

4. Delegate codemap writing to Fixer agents - Spawn one fixer per folder to read code and create or update its specific codemap.md file.

Step 3: Detect Changes (If state already exists)