gramps
b5e3dbe614
One file (AGENTS.md) that bootstraps the rest: rules, the file map to create, what belongs in each file, the first-session interview order, and the list of anti-patterns that killed the previous map (1,308-line guide, 63 task files, narrative history inline, sessions skimming 56k tokens of context). Separates four kinds of content by read frequency: rules/invariants -> AGENTS.md (every session) subsystem truth -> docs/ai/<topic>.md (only the matching one) lookups -> environment.md (grepped, never read) retired decisions -> decisions.md (only when re-opening one) Caps are enforced, not promised: scripts/verify.sh checks doc budgets before the build, so a commit that pads a capped file fails. Proven both ways — it passes clean and exits 1 on an over-cap file. scripts/scope-check.sh blocks edits outside the declared file list. templates/ holds fill-in skeletons for the seven files a project must create. CC0: copy it, rename it, sell it, no attribution needed.
36 lines
1.4 KiB
Markdown
36 lines
1.4 KiB
Markdown
# Memory map — conventions
|
|
|
|
## Why files, not a database
|
|
|
|
Grep-able, diffable, human-editable, portable; git gives versioning and history for free. Files
|
|
form a graph: each file is a node, each relative link an edge.
|
|
|
|
## Inventory
|
|
|
|
| File | Role | Entry point? |
|
|
|---|---|---|
|
|
| `AGENTS.md` | Rules + invariants | **always read** |
|
|
| `ai.md` | Router: product, build, architecture, where truth lives | yes |
|
|
| `HANDOFF.md` | Current state (≤40 lines, overwritten) | yes |
|
|
| `TASKS.md` | Active queue | when asking "what's next" |
|
|
| `docs/ai/*.md` | Subsystem truth, one file each | when the task touches it |
|
|
| `MyMistakes.md` | Failure log + recipes | grep first |
|
|
|
|
## Rules
|
|
|
|
1. **Semantic filenames.** No codes, no abbreviations.
|
|
2. **One `index.md` per code directory**, listing every file with a one-line purpose.
|
|
3. **Links over hierarchy.** Anything unreachable from `ai.md` may as well not exist.
|
|
4. **Stale facts get fixed, not appended.**
|
|
5. **Progressive disclosure.** Detail lives one level down, never crammed into the router.
|
|
|
|
## Reading order
|
|
|
|
1. `AGENTS.md` → 2. `HANDOFF.md` → 3. `ai.md` → 4. the one `docs/ai/<topic>.md` → 5. `<dir>/index.md`
|
|
→ 6. the source (always the authority over any memory file).
|
|
|
|
## Integration rule
|
|
|
|
Every change ships with the facts it **falsifies** corrected, in the same commit. Broader
|
|
restatement may be batched at a milestone.
|