/codemap

name: codemap
description: Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping

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)

1. **Run codemap.mjs changes** to see what changed:

node scripts/codemap.mjs changes \
  --root ./

2. **Review the output** - It shows:

• Added files
• Removed files
• Modified files
• Affected folders

3. **Only update affected codemaps** - Spawn one fixer per affected folder to update its `codemap.md`. 4. **Run update** to save new state:

node scripts/codemap.mjs update \
  --root ./

Step 4: Finalize Repository Atlas (Root Codemap)

Once all specific directories are mapped, the Orchestrator must create or update the root `codemap.md`. This file serves as the **Master Entry Point** for any agent or human entering the repository.

1. **Map Root Assets**: Document the root-level files (e.g., `package.json`, `index.ts`, `plugin.json`) and the project's overall purpose. 2. **Aggregate Sub-Maps**: Create a "Repository Directory Map" section. For every folder that has a `codemap.md`, extract its **Responsibility** summary and include it in a table or list in the root map. 3. **Cross-Reference**: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.

Step 5: Register Codemap in AGENTS.md

**OpenCode auto-loads `AGENTS.md` into agent context on every session.** To ensure agents automatically discover and use the codemap, update (or create) `AGENTS.md` at the repo root:

1. If `AGENTS.md` already exists and already contains a `## Repository Map` section, **skip this step** - the reference is already set up. 2. If `AGENTS.md` exists but has no `## Repository Map` section, **append** the section below. 3. If `AGENTS.md` doesn't exist, **create** it with the section below.

## Repository Map

A full codemap is available at `codemap.md` in the project root.

Before working on any task, read `codemap.md` to understand:
- Project architecture and entry points
- Directory responsibilities and design patterns
- Data flow and integration points between modules

For deep work on a specific folder, also read that folder's `codemap.md`.

This is idempotent - repeated codemap runs will detect the existing section and skip. No duplication.

Codemap Content

Fixers are responsible for writing `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:

• **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
• **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
• **Data & Control Flow** - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
• **Integration Points** - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.

Example codemap:

# src/agents/

## Responsibility
Defines agent personalities and manages their configuration lifecycle.

## Design
Each agent is a prompt + permission set. Config system uses:
- Default prompts (orchestrator.ts, explorer.ts, etc.)
- User overrides from ~/.config/opencode/oh-my-opencode-slim.json
- Permission wildcards for skill/MCP access control

## Flow
1. Plugin loads → calls getAgentConfigs()
2. Reads user config preset
3. Merges defaults with overrides
4. Applies permission rules (wildcard expansion)
5. Returns agent configs to OpenCode

## Integration
- Consumed by: Main plugin (src/index.ts)
- Depends on: Config loader, skills registry

Example **Root Codemap (Atlas)**:

# Repository Atlas: oh-my-opencode-slim

## Project Responsibility
A high-performance, low-latency agent orchestration plugin f