Codemap

---
name: codemap
description: "To generate, populate, and use a project codemap"
license: Apache-2.0
user-invocable: false
---

<codemap>

<role>

Workspace cartographer. Produces a lightweight, top-level structural map of a project — folder/module layout, key entry points, and ownership — for fast architectural orientation.

</role>

Precedence: **LSPs** > **graphify** > **gitnexus** > **shell scripts** — use the first that is **REQUESTED** and available.

Keep CODEMAP.md initialized and updated REGARDLESS.

Do not guess or try to figure out those above => if tools existed you would know that already => fallback to scripts and processes below.

<lsp>
IF LSP tools are already in current context:
- The Language Server Protocol (LSP)
- Use already available tools / capabilities in context
- Combine with semantic search / code index tools already available in context 
- Prefer LSP over Grep/Read for code navigation
</lsp>

<graphify>

IF graphify is already **REQUESTED** in current context:
- querying the codebase, tracing dependency paths between symbols, or explaining concepts (`graphify query/path/explain`): MUST USE SKILL `graphify`
- building or incrementally updating the knowledge graph (`/graphify <path>`, `--update`): MUST USE SKILL `graphify`
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost)

</graphify>

<gitnexus>

IF gitnexus is already **REQUESTED** in current context:
- code graph queries, exploring code, debugging errors, analyzing impact, or refactoring: MUST APPLY SKILL FILE `assets/gitnexus-use.md`
- running CLI commands, indexing, checking status, cleaning index, or generating wiki: MUST APPLY SKILL FILE `assets/gitnexus-cli.md`
- Worked examples: READ SKILL FILE `assets/gitnexus-examples.md`
- After modifying code, run `npx gitnexus analyze --force` in the workspace root

</gitnexus>

<core_concepts>

- The codemap is a structural orientation tool — folder/module layout, entry points, recursive file counts, and short per-directory descriptions. It feeds structural awareness into planning and discovery; it does not capture symbol-level or call-graph detail.
- The output is written to `CODEMAP.md` at the workspace root: markdown headers = workspace-relative path + recursive children count + short (<10 words) description, listing only immediate children file names per directory, 3-4 levels deep.
- Noise, caches, build artifacts, binaries, and `.gitignore`-excluded files are excluded (the scripts use `git ls-files`).

</core_concepts>

<how_to_generate>

1. Get the generator for the current OS (Unix/macOS: make executable first):
   - Unix/macOS: READ SKILL FILE `assets/codemap.sh.txt`
   - Windows: READ SKILL FILE `assets/codemap.ps1.txt`
2. Execute the script:
   - Unix/macOS: `codemap.sh [WORKSPACE_ROOT] [MAX_DEPTH]`
   - Windows: `codemap.ps1 -WorkspaceRoot <path> -MaxDepth <n>`
   - Defaults: current directory, depth 4. Writes `CODEMAP.md` to workspace root.
3. Read the generated `CODEMAP.md` and incorporate it into the current task's discovery notes or working context.

</how_to_generate>

<how_to_use_output>

- Treat the codemap as the structural baseline for planning and discovery — use it to locate entry points, module boundaries, and ownership before diving into code.
- For large workspaces, the codemap is the partitioning input: USE SKILL `large-workspace-handling`, which scopes subagents against `CODEMAP.md` headers.
- Keep only current structural state in `CODEMAP.md` — no deltas, no changelogs.

</how_to_use_output>

</codemap>