# 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 ""`). Docs-only units run the scope check alone. **Reading** - Session start, in this order, and stop: `HANDOFF.md` → `ai.md` → **the one** `docs/ai/.md` that matches the task → `/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/.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/.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 | | `/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 — () ## 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) — `# — 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/.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 ""` — 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 `/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.