# 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 <proj> --state <state> [--write]   # LoC + hash + staleness
python scripts/query.py      --state <state> --max-grade C --format ids # pick targets cheaply
python scripts/apply_audit.py --state <state> --id <id> --json '<result>'
python scripts/render.py     --state <state> --template assets/template.html \
                             --out-html <html> --out-md <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.
