dev-loop AGENTS.md

dev-llm-wiki — Agent Schema

You are the maintainer and consumer of this wiki. This file is the schema: it defines how the wiki is structured, how you route into it, how you write pages, and how you keep it healthy. Follow it exactly. When this file and your habits disagree, this file wins.

What this wiki is

A case-routed knowledge base of development best practices and edge cases, written for LLM agents to load as working context. It is not documentation for humans to browse (humans are welcome, but every formatting rule below exists to make an agent's context precise and small).

Three layers (Karpathy LLM-wiki pattern):

Layer	Path	Mutability
Schema	AGENTS.md (this file), templates/	Change only with repo owner approval
Wiki	wiki/** , INDEX.md, log.md	You create and update via the workflows below
Workflows	skills/	Change only with repo owner approval

Directory layout

INDEX.md                     # root map: domain → when to route there
log.md                       # append-only chronological change log
wiki/<domain>/index.md       # domain map: category/page → when to load it
wiki/<domain>/<category>/<page>.md
templates/page.md            # canonical page template
skills/ingest|query|lint/    # the three operations

Routing protocol (how to consume)

Routing takes one of two inputs. Planning routes from the intent — the task you are about to do. Review routes from the diff — what the code in front of you actually does. Steps 1-6 are the same for both; the review entry then adds step 7.

1. Read INDEX.md. Match your task to a domain by its "route here when" line.
   • Several domains match: route to the domain that owns the artifact you will change (SQL/schema → databases; application code → backend; a failing system → debugging). Reading a second domain's index to check is cheap and sanctioned; bulk-loading pages from both is not.
   • Best match is marked scaffold: it has no pages. Use the cross-pointers in its index if any, take the next matching seeded domain, and append a gap entry to log.md.
2. Read that domain's wiki/<domain>/index.md. Select pages by their "load when" lines — these are the routing gate. Load only pages whose line matches your situation.
3. After loading, the page's "When this applies" should confirm the match. If it contradicts your situation, drop the page and append a drift entry to log.md (index line and page trigger disagree — a lint defect), unless the page content demonstrably serves your case anyway, in which case keep it and still log the drift.
4. Sanctioned extra hops: when a loaded page routes you onward via an inline [page-id] reference or a related: id, follow it — the citing directive is the trigger. This is how constraint/index pages compose.
5. If no page matches anywhere, answer from general knowledge explicitly labeled not wiki-backed, and append a gap entry to log.md.
6. Apply the page's directives:
   • If your situation hits a listed edge case, follow the edge-case row, not the general rule.
   • Within a Do/decision table, when several rows match, apply the most specific row (rows are ordered general → specific); when a general row and a precondition-bearing row both fit, take the one that preserves the stated invariant.
7. Review entry — route from the diff, then compare the page sets. When your input is a change rather than a task, derive the match from what the diff does, not from what its plan said it would do: