# codemap — agent instructions This repository **is the codemap tool**: it builds and incrementally maintains an interactive architecture map + per-module code-quality audit for any codebase. It is a Claude Code skill, but the engine is tool-agnostic — **Codex, Cursor, Aider, or any agent that can read instructions and spawn sub-tasks can drive it.** ## Read these first - **`SKILL.md`** — the full workflow and the `init / check / update / test / fix` commands. Follow it exactly. - **`reference/STANDARDS.md`** — the fixed scoring rubric, smell taxonomy (with per-language equivalents), severity levels, and the **exact per-module audit prompt**. - **`reference/DATA_MODEL.md`** — the `modules.json` schema (the source of truth). ## Non-negotiable rules 1. **`modules.json` is the source of truth.** The HTML and MD are generated by `scripts/render.py` — never hand-edit them. 2. **Every module's score comes from a separate, independent sub-task** (one module per sub-task), using the prompt in `reference/STANDARDS.md`. Never score many modules in one pass; never reuse one module's score for another. 3. For `fix`: keep the **four roles separate** — test-author, fixer, acceptance/verifier, auditor. A fix is accepted only when an independent acceptance step shows the pre-fix green tests are still green and the build is clean. ## The scripts (deterministic, Python 3 stdlib, no install) ``` python scripts/scan.py --root --state [--write] # LoC + hash + staleness python scripts/query.py --state --max-grade C --format ids # pick targets cheaply python scripts/apply_audit.py --state --id --json '' python scripts/render.py --state --template assets/template.html \ --out-html --out-md ``` Use `query.py` (`--format ids|paths|findings`) to target work without reading the whole `modules.json`. Only scoring / fixing / test-writing need the model; everything else is a plain script call.