fable-seed

name	fable-seed
description	Generate or refresh a local AGENTS.md for a module by reading the code that already exists, so later work follows the project's real conventions instead of model defaults. Use when starting work in an unfamiliar module, when conventions keep getting violated, or when asked to "seed", "init", or "write AGENTS.md for" a directory. Pulled on demand; not always-on.

fable-seed — write the AGENTS.md the code already implies

The highest-value, lowest-effort thing before working in a module is to surface its conventions into a local file the work sits next to. In a controlled A/B (eval/technique-ab/, GPT-5.5-judged), a short local AGENTS.md stating a module's convention raised oracle adherence from 33% (no seed) to 100% (hand-written), and a file auto-generated by reading the module's existing code reached 89% (and 100% on the deterministic regex check). So auto-generation preserves ~89% of the hand-written lift.

Your job: read what's there, write down the rules it already follows — do not invent conventions the code doesn't show.

When NOT to use this

• A trivial one-file change, or a repo that already has good AGENTS.md coverage → just read it and work.
• You haven't read any of the module's code yet → read first; a seed written from a guess is worse than none.

Procedure

1. Pick the scope. One AGENTS.md per coherent module/package, not one giant root file.
2. Read 3–6 representative files in that directory. Look for conventions actually and consistently followed: units/domain types, error handling (throw vs Result), data access (parameterized vs interpolated), module shape (named vs default exports, return shapes, logging), id generation, input validation, naming.
3. Write it short and rule-shaped — ~4–8 bullet lines, ≤ ~80 words. State each as a rule a new contributor must follow, not a description of the code. Bad: "addPrices adds two cent values." Good: "Money is integer cents; functions take and return cents; format to dollars only at the boundary."
4. Only what the code shows. If a convention isn't evidenced, leave it out. If two files disagree, state the dominant one and note the exception, or omit it.
5. Don't clobber. If an AGENTS.md exists, show the change as a diff and merge — never silently replace a human-written file.
6. Report each file you wrote and the conventions captured, one line each; flag any you were unsure of as (unverified — confirm).

Expected output

A short, rule-shaped AGENTS.md (or a proposed diff to an existing one) per module worked in, plus the one-line-per-convention report.

Verification

Re-read the file you wrote: is every rule evidenced by a file you actually opened? Drop any rule you cannot point to. A specific, true convention beats a comprehensive, guessed one.

Honest bound

The A/B handed the generated file to the model, so it measures the value of the convention being present and specific; the extra value of an agent auto-discovering the file near the code is real but untested, so the true effect is ≥ the measured 89%. This is a convention aid — it does not change behavior the code doesn't already exhibit.