| 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
- Pick the scope. One
AGENTS.md per coherent module/package, not one giant root file.
- 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.
- 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."
- 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.
- Don't clobber. If an
AGENTS.md exists, show the change as a diff and merge — never silently
replace a human-written file.
- 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.
