Add Standard page, multi-language excludes, Codex/AGENTS.md support

2026-08-28 23:01:22 +00:00 · 2026-06-10 18:17:08 -07:00
parent 2d7c7d0afd
commit a905f01301
5 changed files with 182 additions and 6 deletions
@@ -0,0 +1,35 @@
+# 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 `generate / 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.