---
name: update-codemaps
description: Workflow skill from update-codemaps.md
---

# Update Codemaps

Analyze the codebase structure and update AI navigation documentation. Use this when a project adds modules, changes architecture boundaries, introduces generated code, external systems, sensitive directories, or asks to refresh repo maps / codemaps.

## Workflow

1. Identify the existing navigation surface:
   - Prefer `docs/ai/repo-map.md` when present.
   - Otherwise use existing `codemaps/*.md`, `docs/architecture/*`, or create `docs/ai/repo-map.md` from the package template when the user asks for a reusable navigation map.
2. Scan source, config, tests, contracts, generated-code markers, imports, exports, and dependency boundaries. Use structured parsers or language tools when available; use `rg` for targeted discovery.
3. Generate token-lean navigation docs. Recommended files:
   - `docs/ai/repo-map.md` - first-read AI navigation index
   - `codemaps/architecture.md` - overall architecture when the project already uses codemaps
   - `codemaps/backend.md` - backend structure
   - `codemaps/frontend.md` - frontend structure
   - `codemaps/data.md` - data models and schemas
4. Include, at minimum:
   - project purpose and core domains
   - key directories and responsibilities
   - module entry points and truth sources
   - generated code, sensitive paths, and do-not-edit zones
   - external systems and MCP / API touchpoints
   - common verification commands
   - subdirectory `AGENTS.md` index when present
   - freshness timestamp and maintenance owner when known
5. Keep the map high-level. Do not explain every function or paste large source excerpts.
6. Calculate diff percentage from the previous version when updating an existing codemap. If changes exceed 30%, summarize the reason and request user approval before replacing broad sections, unless the user explicitly asked for a full refresh.
7. Save a short report to `.reports/codemap-diff.txt` when `.reports/` exists or when the project already uses reports.
8. If the root `AGENTS.md` lacks a code-map entry and the project is large enough to need one, recommend adding a short link instead of copying map content into `AGENTS.md`.

Use TypeScript/Node.js for JavaScript and TypeScript analysis when practical. For other stacks, prefer the project's native language tooling or LSP output when available. Focus on high-level structure, not implementation details.
