# Codemap

> Use when indexing a codebase for agent navigation, generating or refreshing CODEMAP.md files, mapping large project structure, or adding CODEMAP guidance for learning/maintenance workflows.

- **Type:** Skill
- **Install:** `agentstack add skill-htdxd-codemap-skill-codemap-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [htdxd](https://agentstack.voostack.com/s/htdxd)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [htdxd](https://github.com/htdxd)
- **Source:** https://github.com/htdxd/codemap-skill

## Install

```sh
agentstack add skill-htdxd-codemap-skill-codemap-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CODEMAP — Codebase Navigation Index Generator

Generate hierarchical `CODEMAP.md` files that help agents locate relevant code without scanning unrelated files. Core navigation: **Task Guide first → Domain filter → targeted reads**. For files over 1000 lines, generate a companion `.analysis.md` with intent-to-line-range mapping.

## Core Principles

- `CODEMAP.md` is a navigation constraint, not documentation to browse.
- Prefer positive guidance (Task Guide, Domain, Key Exports) over broad listings.
- Dependencies are a safety net, not an invitation to chain-read.
- Each CODEMAP describes only its own directory level. Child directory details belong in child CODEMAPs.

## Language Rule

Generated files use the user's request language for prose/headings. Code identifiers, file names, paths, and symbols keep original spelling.

## Before Generation: Ask Three Questions

Unless already specified:

1. **Mode**: `Learning` (read-only study) or `Maintenance` (active development).
2. **Sub-agents**: `Yes, max 3` (recommended), custom limit, or `No`.
3. **Ignore rules**: `Defaults + .gitignore` (recommended), or add custom patterns.

Mode differences:

| Aspect | Learning | Maintenance |
|---|---|---|
| Frontmatter | `mode: learning` | `mode: maintenance`, `commit: ` |
| Task Guide | suggested entry point | primary navigation, strict |
| Domain | soft focus hint | hard filter unless justified |
| Dependencies | reference material | gated by interface/impact rules |
| Updates | one-time | incremental after code changes |

## Ignore Rules

Merge in order:
1. Built-ins: `.git/`, dependency dirs, virtualenvs, build outputs, caches, logs, lockfiles, minified files, binaries, image/font assets, IDE folders.
2. Project `.gitignore`.
3. User custom patterns.

Include generated code only if it affects navigation; mark `Generated, do not edit manually`.

## Generation Workflow

### 1. Build Global Context

Read lightweight project context only:
- Prefer root `README.md` / `README.rst` / `README.txt`.
- Else metadata: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, etc.
- Else infer from structure; mark guesses `inferred, verify against code`.

Produce: purpose, architecture shape, major domains. Omit badges/changelogs.

### 2. Scan and Measure

After applying ignore rules:
- Build filtered directory topology.
- Count source files, lines, size per first-level subdirectory and project total.
- Files over 1000 lines:
  - `5` → ask: all, top 5, selected, or none.

### 3. Dispatch Work

If sub-agents enabled, choose count `K`:

| Project size | K |
|---|---|
| `15000` lines or `>3MB` | `N` |

If line count and size disagree, use the larger `K`. Assign first-level directories by greedy bin packing. Keep root loose files with main agent if small (``. Sort by architectural importance.
- Cap at ~15 entries. Child CODEMAPs handle detailed symbols.

### Files

Columns vary by directory type:

- **Root**: `File | Domain | Function`
- **Mid-level / Leaf**: `File | Domain | Deps | Function`

`Deps` column (compact notation):
- `←` = files outside this directory that this file imports.
- `→` = files outside this directory that depend on this file.
- Example: `← core/errors.py | → main.py, chat/service.py`
- `→` >5 files: `→ N files (foundational); rg "SymbolName" --type py -l`
- Omit `Deps` column entirely when no file in the directory has cross-dir dependencies. Use `—` for individual files with no deps.

Rules:
- One row per immediate file. **Never list files from child directories that have their own CODEMAP.**
- `Domain` must match local Task Guide / Subdirectories values. `—` for trivial re-export files.
- `Function`: one concise sentence. For large files, append `→ see .analysis.md`.
- Skip pure re-export `__init__.py` if exports are captured in Key Exports.

### File Dependencies

Columns: `File | Imports (in-dir) | Exposed To (in-dir)`.

Rules:
- Same-directory relationships only. Only for immediate files (not child directory files).
- Mid-level directories: list only files directly in the directory itself, never files in child subdirectories.
- Maintenance mode: read `Imports` only when an imported interface contract is unclear. Read `Exposed To` only when changing a public signature, return type, or documented semantics.
- Learning mode: reference only; do not chain-read unless current logic is unclear without it.

### Parent-Child Decoupling

When a child directory has its own CODEMAP:
- Parent does NOT list the child's internal files in Files, File Dependencies, or Key Exports.
- Parent only references the child directory in Subdirectories and Task Guide.
- Child-internal symbols appear only in the child's Key Exports.

---

## Large File Analysis (.analysis.md)

For source files over 1000 lines, create `.analysis.md` beside it.

### Structure

```markdown
---
source: filename.py
lines: 1842
generated_at: YYYY-MM-DD
---

> One-sentence summary.

## Feature Index

| Intent | Lines | Notes |
|---|---|---|

## Symbols

| Symbol | Type | Line |
|---|---|---|

## Logical Sections

| Lines | Content |
|---|---|
```

### Rules

- **Feature Index** is primary. Map concrete learning or development intents to exact line ranges. Notes: same-file coupling only. If no intent maps to a section, omit that row.
- **Symbols**: top-level public symbols only (classes, functions, constants). Not internal helpers.
- **Logical Sections**: high-level structural segments only, **5-10 rows max**. Provides structural overview and serves as fallback when Feature Index has no match. Do not expand to function-level granularity.
- Optional **Class Hierarchy** only when inheritance depth >2.
- No code snippets, API signatures, or implementation detail paragraphs.
- In maintenance mode, agents read only matched line ranges from Feature Index; Logical Sections is the fallback.

---

## Navigation Protocol (Project-Level Injection)

Install exactly one protocol block into project `AGENTS.md` or `CLAUDE.md`. Choose by mode.

### Learning Mode Block

````markdown
## CODEMAP Navigation Protocol

This project uses hierarchical `CODEMAP.md` index files for code navigation. Files over 1000 lines may have companion `.analysis.md` structural maps.

### Navigation Rules

1. Start from root `CODEMAP.md`. Read Task Guide first.
2. Task Guide match: Target = primary read set. Also Check = conditional candidates (decide after reading Target).
3. No Task Guide match → filter Subdirectories by Domain, enter only matching-domain subdirectories.
4. Drill down layer by layer; consult local Task Guide at each level before reading source files.
5. Container directories (no source files): read only Task Guide + Subdirectories.
6. Large files: read `.analysis.md` Feature Index first, match Intent to line ranges. Use Logical Sections as fallback.
7. Batch-read final target files in parallel.
8. No speculative expansion: extend read set only when already-read code proves the need.
````

### Maintenance Mode Block

````markdown
## CODEMAP Navigation Protocol

This project uses hierarchical `CODEMAP.md` index files for code navigation. Files over 1000 lines may have companion `.analysis.md` structural maps. For development tasks, these rules are strict navigation constraints.

### Navigation Rules

1. Start from root `CODEMAP.md`. Read Task Guide first.
2. Task Guide match: Target = primary read set. Read Also Check only when the task explicitly involves it, target code proves the need, or public contract impact requires it.
3. No Task Guide match → filter Subdirectories by Domain. Non-matching domains are excluded unless already-read code gives a concrete reason.
4. Drill down layer by layer; consult local Task Guide at each level before reading source files.
5. Container directories (no source files): read only Task Guide + Subdirectories.
6. Large files: read `.analysis.md` Feature Index first, match Intent to line ranges. Use Logical Sections as fallback.
7. Batch-read final target files in parallel.
8. No speculative expansion: each additional file requires an explicit reason.

### Dependency Gating

The Deps column in Files tables marks cross-directory dependencies:
- `←` (imports): read only when the imported interface contract is needed to understand the current file.
- `→` (exposed to) ≤5 files: read only when changing a public signature, return type, or documented semantics.
- `→` >5 files (foundational): run the search command provided in CODEMAP, filter by Domain, then read only justified matches.
- No chaining: do not read dependencies-of-dependencies unless a specific contract gap remains.

### Update Rules

After code changes, the agent autonomously evaluates:
- File/directory add, delete, move, rename → regenerate affected directory CODEMAP, update parent Subdirectories and Task Guide paths.
- Public symbol signature/return type change → update Key Exports and related Task Guide entries.
- Internal implementation change only → no update. Exception: update `.analysis.md` when Feature Index mapping becomes invalid.
````

---

## Edge Cases

- **Monorepo**: map each package root plus a top-level package index.
- **Deep nesting**: layer-by-layer drill-down; each level's map stays local.
- **Huge flat directory** (`>200` files): group Files rows by Domain subheadings.
- **Generated code**: include only when navigation needs it; mark `Generated, do not edit manually`.
- **No metadata/README**: infer cautiously; mark uncertainty.
- **Task Guide gaps**: acceptable. Fall back to Domain filtering and Key Exports.
- **Foundational files** (>5 dependents): provide grep command, require Domain filtering.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [htdxd](https://github.com/htdxd)
- **Source:** [htdxd/codemap-skill](https://github.com/htdxd/codemap-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-htdxd-codemap-skill-codemap-skill
- Seller: https://agentstack.voostack.com/s/htdxd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.