Agent-legible VariantGrid: knowledge layers, vg introspection commands, verification loops, .claude harness

🤖 Written by Claude

Plan: [claude/plans/agent_system.md](https://github.com/SACGF/variantgrid/blob/master/claude/plans/agent_system.md)

A design for making the whole system legible and drivable by an agent (and easier for humans along the way), grounded in a survey of the repo and of `vg-test2` on 2026-08-31.

**Organising idea:** every thing has a *Name, Place, Inspector and Doc*, and a CI check that the four agree. Facts are generated where possible, prose cites symbols that are checked, and CLAUDE.md is capped and routes rather than accumulates.

**Main pieces**
- Knowledge layer: root CLAUDE.md as a constitution + routing table; nested `/CLAUDE.md` files; `claude/domain.md` glossary; generated `claude/maps/` checked like `makemigrations --check`; research docs slimmed to narrative with checkable citations; module contract docstrings (13% coverage today).
- `manage.py vg` command family: `status`, `inspect`, `page`, `browse`, `tests --changed`, `logs`, `sql --explain`, `settings`, `map`, `outline`, `docs check`, `health`.
- Verification loops fastest-first: edit hooks → `vg tests --changed` → `vg page` → parallel suite; `variantgrid_autotests` stays the deployment-scale net.
- Committed `.claude/` harness: hooks, permission allowlist, a few skills, two subagents; a memory policy that pushes project facts into the repo.
- Accretion protocol: definition of done, plan `Status:` lines, ratchets in `vg health`. One-off command retirement and migration squashing are scheduled for after the major deploy.

Phased: Phase 0 (one day: CLAUDE.md restructure, hooks, `vg status`), Phase 1 (maps, `vg page`, test selection, app CLAUDE.md files), Phase 2 (`inspect`, `logs`, `browse`, docs check, skills), Phase 3 (ongoing ratchets).

Start with claude/plans/agent_system.md, then inspect the root CLAUDE.md and manage.py entry point. Begin with the explicitly scoped Phase 0 work: the CLAUDE.md restructure, hooks, and vg status command. Done means those Phase 0 items are implemented and the stated verification loops and health checks can be followed.

Written by the indexing model from the issue text.