One Markdown file. Three readers.
AGENTS.md tells your agents how to work. PRODUCT.md tells them what they're building — who it's for, how it speaks, and what it costs. Read by humans, coding agents, and buying agents.
The engineer reads the README. The coding agent reads AGENTS.md. And the buying agent — the one that arrives at your domain with a job and a budget — reads marketing copy and guesses. Meanwhile the person accountable for the product's actual definition, the product manager, keeps that definition scattered across a PRD in a drive folder, a deck from the last board meeting, a pricing page, and a brand guide: four artifacts, no known address, none of it typed, all of it re-derived — badly — by every tool in the chain.
Build conduct already solved this for itself: AGENTS.md is one file at a
known place, and every coding agent reads it. The product itself — the
thing all that conduct serves — has no equivalent file. PRODUCT.md is
that file: who it's for, how it speaks, what it costs, in one Markdown
document with two bindings. At build time it sits at the repo root beside
AGENTS.md, and coding agents read it as design and audience context. At
sell time the same bytes publish at https://yourdomain/product.md, and
a buying agent fetches the file and quotes its typed pricing island
instead of guessing from a screenshot.
That specimen is the spec's own annotated example — a fictional product
(Coldframe), labeled as such; its figures are illustrative mechanics,
not anyone's prices. Three things carry the whole design. Layers:
Layer 0 is any CommonMark document with one H1 — the floor is on the
ground; Layer 1 is canonical sections identified by heading — headings
are the schema, and there are zero required fields; Layer 2 is optional
MDXLD frontmatter, where $type: Product resolves to the AI superset of
schema.org/Product. Normative prose: a MUST NOT sentence inside a
section is machine-extractable — generators are bound by the sentence,
not merely informed by it. Machine islands: a fenced block with a
spec-qualified info string is typed data inside free prose — that exact
JSON is what an agent-commerce offer quotes.
---
$id: https://coldframe.app/product.md # Layer 2 — optional MDXLD frontmatter
$type: Product
---
# Coldframe
Climate automation for small-farm greenhouses. One controller, every vent.
## Users
Market growers running 1 to 6 hoop houses, checking conditions from a
phone in the field with dirty gloves on. They know growing, not HVAC.
## Anti-references
- Generated output MUST NOT use dashboard-grid "mission control" layouts.
- MUST NOT default to dark mode: this app is read in full sunlight.
## Offer
Coldframe Grower is $29/month per greenhouse.
```json product.md#pricing
{ "model": "metered", "hardCeiling": 50, "unit": "usd-per-month", "price": 29 }
```
Non-entrenchment is a stated property, not a gap: this is draft 0.9,
and 1.0 waits on two independent implementations — today there is one,
partial, and not ours. Even the spec's most contested token is filed as
contested on its own page: impeccable's v4 record retired the
## Register mode bit in favour of per-surface visitor modes, and
whether this spec keeps it is an open question in the public tracker,
not a decree.
Each door below was checked cold on 2026-07-31 and carries its own state and its own evidence URL — never one URL evidencing several. Serving is a liveness fact, not an adoption claim: nothing here asserts external adopters, file counts, or traffic. Where a serving surface's CONTENT is wrong, that is an amber on the next slide — a green here means the door answers, exactly that.
The apex serves: 200, the whole specification on one page — layers, canonical sections, machine islands, conformance — under the live title "PRODUCT.md, the open standard for describing a product." (That a public reconciliation branch recuts "standard" to "specification" — unmerged, undeployed — is the next slide's first amber, not rounded away here.)
The sell-time binding is demonstrated on the spec's own domain: /product.md answers 200 as text/markdown with the site's own PRODUCT.md — the file the specification describes, served as a file.
The machine index serves: /llms.txt answers 200 as text/markdown with the map of the surface.
The capability card serves: /.well-known/agents.json answers 200 as
JSON — name, interfaces, endpoints, "monetization": null — no login,
no signup.
The reader-classification surface serves: /icp.json answers 200 as JSON, classifying the three reader classes — coding agent, buying agent, human — so an agent can self-classify before consuming the file.
The dedicated repo is public: spec text CC-BY-4.0, site code MIT — the dot-org-ai org's sole .md repo, per the org's own listing.
Four ambers, worn in the open. The first two share one root cause — the repo's reconciliation commits sit on a public branch, reconcile/foundation-anchor-and-accuracy, that main has never merged — so the live deploy and main agree with each other, and both predate the corrections. The fix is a merge AND a deploy, and this record does not pretend either has happened.
The spec's premise is two bindings, same bytes — and today the domain passes it: live /product.md is byte-identical to main's PRODUCT.md, diffed cold. What lags is the correction itself: the public branch reconcile/foundation-anchor-and-accuracy (commits 150d321, 40d514a) recuts "standard" to "specification" (in the Foundation's vocabulary, a standard is an externally governed body mirrored verbatim — O*NET, NAICS, GS1 — and this is a specification we author), adds the Foundation provenance paragraph, and adds the Offer, Boundaries, and Stack sections — and none of that has reached main or the live surface. The bindings agree with each other; both lag the branch that corrects them.
The sharpest amber: the live apex, llms.txt, icp.json, and agents.json
all instruct npx productmd init — and this project publishes no CLI.
An agent that obeys those surfaces today executes an unrelated
publisher's package. The correction exists only on the unmerged public
branch, whose icp.json says plainly "There is no productmd CLI" —
main's own surfaces still carry the instruction. Until the branch
merges and deploys, the domain's machine surfaces misdirect the exact
readers the spec exists to serve.
The npm name productmd resolves to an unrelated publisher's package —
a different project by a different author ("Spec-as-code framework for
AI-native product teams," repository ethancstuart/product-md). Posted as
a live fact so the amber above is checkable in one request: do not run
it expecting this specification.
The 1.0 gate, stated at its true distance: today's one external
implementation is partial — a file impeccable v4 writes reaches Level 1
here and not yet Level 2, because its record renamed sections and
retired ## Register, and the alias table is owed. 1.0 does not ship on
this record's say-so; it ships when two implementers agree.
The specification is authored under The Org.AI Foundation — the root of the .org.ai estate, which presents the hierarchy and homes nothing. The origin implementation is not ours and the spec says so: impeccable has written a PRODUCT.md since its v1, its product record is the practice this spec descends from, and the two records diverged when impeccable's v4 renamed sections and retired the Register axis. Convergence is the goal, filed as work:
The convergence path is public in this spec's own tracker: issue 1, "Align with pbakaus's product.md standard" — open, with the deltas and a proposed path.
And filed upstream, in the origin implementation's tracker: impeccable issue 427, "Aligning the PRODUCT.md record with a second implementation (product.md)" — open.
The estate holds thirteen live .md zones — apis.md, ast.md, ctx.md, dbx.md, mdx.md, motion.md, product.md, scrape.md, src.md, svcs.md, todos.md, workflow.md, workflows.md — and the family thesis is this record's thesis at estate scale: a .md domain is a filename with an apex, the repo-root convention and the published URL sharing one name. The family's liveness is mixed and is filed as mixed: a full census the day this record filed found three sibling apexes serving under their own identities (posted below, one Claim each), mdx.md answering 500, apis.md and svcs.md 522, and the remaining six zones not answering at all. What product.md alone holds is the conjunction — the only .md zone with both a dedicated public repo and a filed G4 record — the family's first record, claimed at exactly that size.
A sibling apex serves under its own identity: motion.md answers 200 — "motion.md - Write videos in Markdown. Render them with code."
A second sibling serves under its own identity: todos.md answers 200 — "todos.md | Tasks and plans for agents."
A third sibling serves under its own identity: src.md answers 200 under its own name.
The family narrative graduates from thesis to pattern when a second .md door files its own G4 record. Until then, "family" names an estate position, a handful of serving doors, and exactly one filed record — never a filed family.
Boundary rules, so the family never blurs into the estate's other
markdown surfaces: mdx.do sells how documents work — a grammar and
toolchain for documents in general; this record prescribes what one
document says, and a conforming PRODUCT.md needs neither MDX nor the
toolchain (Layer 0 is plain CommonMark). schema.org.ai answers what
a thing IS — the type substrate a PRODUCT.md's Layer 2 resolves into
when it declares $type: Product. agents.md is the external sibling
convention for build conduct — not the estate's, linked and never
duplicated.
B2D-shaped adoption with the product owner in the developer seat: in the agent era the PM ships like a developer — reads the whole spec on one page, copies the annotated example, commits the file. There is no sales motion, no demo call, and no revenue event anywhere on this record; the conversion is a shipped PRODUCT.md, and the spec's own success line is "reads for three minutes and ships the file in five." The read side is B2A, live in kind today: llms.txt, the capability card, and the reader-classification surface serve so agents can consume the spec the way the spec teaches — with the machine-surface misdirection amber on the bindings slide worn where it belongs.
What the estate earns from a free spec is position, stated as position:
every shipped PRODUCT.md normalizes a typed, addressable product
definition — the exact artifact the estate's buying-agent rails read on
the other side — and every Layer 2 file resolves its $type into
schema.org.ai. Adoption compounds the file format; the estate holds the
filename. No revenue, valuation, or adoption figure appears in this
record, and none is gated behind a placeholder — on this record there is
genuinely nothing to count yet, and it says so.
The strongest evidence in this record is the subject practicing itself: the site is described by its own PRODUCT.md, published at its own /product.md — fetchable cold, as markdown, right now. And the record you are reading extends the same practice: a product defined in one Markdown file, pitched by one Markdown file, in an estate whose canonical records are Markdown files. The drift between the public reconciliation branch and everything it has not yet reached — main and the published file alike — reported in amber above rather than discovered by a stranger — is what the discipline looks like when it is real: the spec's own surfaces are held to the spec's own rule, in public, including when they lag it.
The spec is one page, at product.md — it serves today.
If this was forwarded to you: product.md is the open specification for describing a product in one Markdown file — who it's for, how it speaks, what it costs — read by humans, coding agents, and buying agents, authored under The Org.AI Foundation, spec text CC-BY-4.0. It is the first record of the estate's .md family, where the domain is the filename. What serves is posted with a URL you can resolve cold; what does not is pending with the gate that flips it — including the two it wears most openly: a reconciliation branch its repo has not yet merged or deployed, and machine surfaces that still instruct a CLI this project does not publish. Judge the spec by whether it holds itself to its own file — and if you own a product definition, ship yours.