agent-memory-seed/AGENTS.md

AGENTS — bootstrap

You are starting this project's memory from nothing. This file is self-contained: it gives you the rules, the file map you must create, what belongs in each file, and the order to do it in.

Two standing orders:

1. This file is the only mandatory read at session start. Everything else is read on demand.
2. Finish work; do not manage it. A session that produces task lists, re-prioritisation or documentation of work instead of working has failed, even if the docs are good.

---

1. Rules — non-negotiable

Delivery

• One unit = one behaviour = one test = one commit. If a request needs several tests, pick the one the user cares about and finish it before the next.
• No feature branches pre-1.0. Work lands on main, committed per unit.
• Commit every unit without asking. Push only at checkpoints the user names.
• Declare the exact file list before editing. No "while I'm here" edits, no drive-by refactors. Anything spotted outside the list becomes a one-line follow-up in HANDOFF.md.
• One pre-commit gate for code: clean build at 0 warnings, full tests, scope check, doc budgets (scripts/verify.sh "<files>"). Docs-only units run the scope check alone.

Reading

• Session start, in this order, and stop: HANDOFF.md → ai.md → the one docs/ai/<topic>.md that matches the task → <dir>/index.md for the code you will touch.
• TASKS.md is read when the question is "what's next" — never as a prerequisite to code.
• Never read the whole map "for context". If the map is a required read, the map is wrong.

Memory

• The map is corrected by the change that falsifies it — in the same commit. It is not a unit of its own; no "docs backfill" commits unless asked.
• Three kinds of truth, three homes: rules/invariants → this file; subsystem detail → docs/ai/<topic>.md; lookups (paths, ports, hosts, credential locations) → one cheat sheet. History and abandoned decisions → a decisions log, never inline in the docs.
• HANDOFF.md is current state only, overwritten not appended, hard-capped.
• A fact recorded once ends the re-derivation loop: paths, traps and recipes go in the map the first time they cost a hunt. Grep the recipes file before re-deriving anything.

Behaviour

• Do the work, then report what changed and what's next. No plans, pros/cons tables or "pitfalls" sections unless asked.
• Nothing here is novel: scan externally before building anything new, cite the reference in the commit. A second failed fix for the same symptom is a research trigger, not a persistence trigger — stop and find the established answer.
• Follow the codebase's existing conventions; don't add comments the code doesn't need; don't invent work items.

---

2. Files you must create

File	Role	Cap	Written by
AGENTS.md	This file: rules + the project's invariants	210 lines	you, rarely
ai.md	Router: what the product is, build commands, architecture table, where truth lives	100 lines	you, rarely
HANDOFF.md	Current state: branch, in flight, next action, landmines	40 lines	every session, overwritten
TASKS.md	The active queue, one line per live item	120 lines	on status change
TASKS/archive.md	Everything done, as a dated snapshot	unbounded	at trim time
docs/ai/<topic>.md	Subsystem truth — one file per subsystem	unbounded	as that subsystem changes
docs/ai/index.md	Routing table: file ↔ what it covers ↔ when to read it	—	as files are added
docs/ai/decisions.md	Retired paths + cause of death, and the permanent out-of-scope list	—	when a decision dies
docs/ai/environment.md	Lookups: hosts, ports, paths, build/run/test commands, suite map	—	when a fact costs a hunt
MyMistakes.md	Failure log + recipes registry (grep-first)	—	when something is learned the hard way
schema.md	The conventions above, restated for this repo	—	once
<dir>/index.md	One per code directory: file list + one-line purpose + links out	—	when layout changes

If a file is over cap: move detail out, never pad — the gate fails padding.

---

3. What goes in each file

HANDOFF.md (≤40)

# HANDOFF — <date> (<one-line state>)
## State        branch, worktree, unpushed commits
## Next action  the single next unit, and why it is next
## Landmines    live traps only — paths, flaky tests, do-not-touch rules
## Pending      what is blocked on the user (checks, decisions, takes)

ai.md (≤100) — # <Product> — AI guide & router, then:

• ## What it is — five lines max.
• ## Build, run, test — the actual commands, plus the pointer to environment.md.
• ## Architecture — one table row per top-level directory: path → role.
• ## Where the truth lives — table: subsystem → doc → "read when".
• ## Current state → a one-line pointer to HANDOFF.md. Nothing else.

docs/ai/<topic>.md — open with one line of "read when". Then observed reality only: how it works, the traps that cost time, the measurements that settled an argument, and the guard test that protects each rule. Date contested facts. Never re-tell the product pitch.

TASKS.md — ## Next up (the one unit, 5 lines) · ## Queue (one table row per item: id, status ☐🔶⏳⏸❌, one-line scope, detail link) · ## Pending the user · ## Release gates.

decisions.md — one dated line per decision that no longer governs, with the reason it died, plus the permanent out-of-scope list. Read only when about to re-open one.

MyMistakes.md — ## Recipes first (how-to, verbatim commands, traps). Then dated failure entries: symptom → wrong guess → actual cause → the rule that prevents it.

---

4. Create the gate

scripts/scope-check.sh — fails if any changed file is outside the declared list. scripts/verify.sh "<files>" — in this order:

1. Doc budgets: wc -l every capped file, fail with "move the detail out, do not pad".
2. Clean build: clean first, then build; any warning fails. (Incremental "0 warnings" lies.)
3. Tests: full suite; a whitelist of known-flaky names, everything else is a regression.
4. Scope check with the passed file list.

A budget that is not a failing gate gets eaten by the next append. This is the load-bearing part.

---

5. First session — do this, in order

1. Ask the user for: what the product is in one paragraph, the architecture's top-level directories, the build/run/test commands, the deployment target, and anything that must never be violated (legal, data-loss, output-corrupting). One question at a time.
2. Write AGENTS.md §1 rules as-is, then add the invariants: 10–20 lines, each stating a rule and pointing at the doc that explains it. An invariant earns its line only if violating it breaks output, destroys user data, or creates a legal/trust breach.
3. Write ai.md router, HANDOFF.md, TASKS.md (empty queue), docs/ai/index.md, docs/ai/environment.md, decisions.md skeleton, MyMistakes.md with an empty Recipes section, schema.md, and <dir>/index.md for each directory.
4. Write the two scripts and prove the gate fires (create an over-cap file, watch it fail).
5. Commit once: "docs: project memory map + gate". Then stop mapping and start working.

---

6. Anti-patterns that killed the last map

• Appending instead of replacing — the file only grows, and stale facts outlive the code.
• One task file per task, with paragraph-length status prose — a second, worse source of truth.
• Cross-references like "TASK 3 item 17" — numbers rot; cite a path or a feature name.
• Narrative history kept inline "for context" — it is 30% of the file and read by nobody.
• Splitting into more files without a router — discovery cost just moved.
• Docs commits as units of work — the cheapest thing to produce, so it replaces real progress.
• Reading the whole map every session — a tax that trains sessions to skim.