Files

T

gramps b5e3dbe614 Seed an AI-legible project memory map that stays small

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.

2026-10-30 06:51:19 -07:00

1.4 KiB

Raw Permalink Blame History

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

Semantic filenames. No codes, no abbreviations.
One index.md per code directory, listing every file with a one-line purpose.
Links over hierarchy. Anything unreachable from ai.md may as well not exist.
Stale facts get fixed, not appended.
Progressive disclosure. Detail lives one level down, never crammed into the router.

Reading order

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.

1.4 KiB Raw Permalink Blame History