What is a seed

A seed teaches an agent in a repository it has never seen how to acquire one named tool and make it real — detect whether it is already present, install it from an origin the seed vouches for, prove the install took, use it, wire it into the repository's harness, and account for every move.

It is written for the machine that will act on a foreign tree. Exactly one section, at the end, is written for you.

Name the tool. Never the reader's tree.

A recipe's hardest constraint is neutrality: name roles, never instances, because its subject is a transferable pattern. A seed inverts that. Its subject is one concrete tool, so it names that tool freely — the target, its version, its origin, its own install command all belong in the document, because they are the document. What a seed must still never name is the reader's tree: their paths, their filenames, the directory where their harness lives.

So the discipline shifts from transferable design to trustworthy action. The test is the recipe's test pointed at a different object: could an agent follow this in a repository whose layout you have never seen?

A fixed shape, checked by a gate, in this order.

Frontmatter carries identity, version, and the two trust anchors — the target it brings in and the origin it vouches for. The body then walks a chain in which each section earns the right to the next.

1. 01Summary — a 2–4 sentence orientation before any move: what tool this brings in, what standing it up buys the reader, and the state they're in when it's done. It's body text, so neutrality applies in full.
2. 02What it is — the tool itself: what it does, the shape of the thing that lands, and the model the reader needs before they let it onto their machine. Understanding before acquisition.
3. 03Install — the acquisition sequence, one step per heading. Its first step opens with a Detect marker (is the tool already here, at what version?), and every step closes with a literal Done when line stating the observable condition that proves it took.
4. 04Verify — the proof the whole install works, and it must run at least one real command the agent observes, not prose that asserts success. Install can lie; Verify is the acceptance at the whole-tool level.
5. 05Use — how the reader actually puts the now-installed tool to work: the first real thing they do with it, concrete enough to act on but still neutral about their own tree.
6. 06Harness — how the tool joins the repository's agent harness so future agents know it's here. Advisory: recommend a project rule only when the tool ships none of its own, or you manufacture a second source of truth that drifts.
7. 07Report — the closing section, and the only one written for a person: a fixed five-row table that accounts for what the seed just did to this repository.

The order is the argument. You cannot use a tool you haven't verified; you cannot verify one you haven't installed; you cannot install one you don't understand enough to describe. Reorder the sections and you break the chain.

Four rules, each mechanical, each with a gate.

Together they turn an install from a hopeful sequence of commands into an accountable one: it doesn't clobber, doesn't proceed on faith, doesn't execute the untraceable, and doesn't claim a success it never observed.

The Summary orients the agent; the Report is written for the person who has to accept what the seed just did. Where a recipe describes a design and can do so in prose, a seed took an action on the reader's tree — so its closing section is a fixed-shape audit, exactly five rows in order: what it is, how it works, what was done (the actual mutations this run made — the row that makes the seed accountable), how to use it, and suggest next. A human reviews many seed runs; a report whose shape changes every time is one they must re-read from scratch. The fixed table is a contract with that eye.

Read and run, never recalled. A tool's install command, its verify check, the origin it ships from — all of it lives in the tool's own current docs and in what it does when you run it, not in what you remember. The verified stamp is the proof: it says the seed was run, on a named machine, at a named release, on a named date — a snapshot of one successful install, not maintained doctrine.

A conformance verdict names a moving constitution.