One Markdown file that says who your product is for, how it speaks, and what it costs. Read by humans, coding agents, and buying agents. If you use impeccable, yours already exists.
# Coldframe Climate automation for small-farm greenhouses. One controller, every vent. ## Register product ## 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. ## Offer Coldframe Grower is $29/month per greenhouse. The forecast API is metered, hard-capped at $50/month. ```json product.md#pricing { "model": "metered", "hardCeiling": 50, "price": 29 } ```
The engineer reads the README. The coding agent reads AGENTS.md, shipped to 60,000+ repositories. The third reader is new: a buying agent that arrives at your domain with a job and a budget, and finds nothing written for it. It guesses your audience from your hero copy and your price from a screenshot.
PRODUCT.md is the file for all three. One grammar, two bindings:
At the repo root, next to AGENTS.md. Cursor, Claude Code, Codex, and Gemini CLI read it as design and audience context. impeccable has required this file since v1: 64,000 installs a week already write it.
The same bytes, published. A buying agent fetches the file, validates the pricing block, and negotiates a typed offer instead of a guessed one. Deploying the product publishes its definition.
A complete, conformant example. Headings are the schema: no required fields, no YAML gymnastics, prose first.
--- $id: https://coldframe.app/product.md $type: Product $context: https://schema.org.ai productmd: 1 register: product ---
$type: Product resolves to
schema.org/Product, so the file is valid linked data. Delete
this whole block and the file still conforms.
# Coldframe Climate automation for small-farm greenhouses. One controller, every vent.
## Register product
brand means design is the product.
product means design serves it. Every conformant
tool forks its posture on this one token.
## 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. Their job to be done: never lose a crop to a stuck vent again.
## Brand Personality Calm, weatherproof, exact. The voice of a neighbor who farms and codes. ### Tone Plain sentences. Celsius and Fahrenheit always paired. Alarms are rare and real; when one fires, it says what to do.
## 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. - No IoT clip art, no "smart farming revolution" copy.
## Offer
Coldframe Grower is $29/month per greenhouse. The forecast API is
metered, hard-capped at $50/month.
```json product.md#pricing
{ "model": "metered", "hardCeiling": 50, "unit": "usd-per-month", "price": 29 }
``` ## Boundaries - Not a hydroponics controller. Soil growers only, v3 at the earliest. - Not a marketplace; we never sell growers' yield data. ## Stack - agents.md: build conventions - design.md: tokens - auth.md: agent access
Draft 0.9. MUST, SHOULD, and MAY are RFC 2119. Everything else is plain English.
Layer 0. Any CommonMark document with exactly one H1
is a valid PRODUCT.md. There are zero required fields.
Layer 1. Canonical sections, identified by heading.
Tools MUST match headings through the alias
table below. Layer 2. Optional
MDXLD frontmatter
($id, $type, $context) making
the file valid linked data. $type: Product resolves to
schema.org/Product.
The primary aliases are the headings impeccable has written since v1. If you have a PRODUCT.md today, it conforms today, unmodified.
| Section | Answers |
|---|---|
| Register | brand or product. The one-token mode bit. |
| Users | Who this is for, in language they'd recognize. |
| Problem | What breaks without it, concretely. |
| Product Purpose | What it does and how success is measured. |
| Brand Personality / Tone | How it speaks. Themes and generators read this. |
| Anti-references | What it must never resemble. Normative. |
| Design Principles | The strategic design rules, numbered. |
| Accessibility & Inclusion | The floor, stated as requirements. |
| Offer | What it costs, in prose plus a pricing island. |
| Boundaries | What the product is not. |
| Stack | Links to agents.md, design.md, auth.md. Never duplicates them. |
A fenced code block whose info string is spec-qualified, like
json product.md#pricing, is a machine island: normative
typed data inside free prose. Islands MUST
be valid in their declared format. The pricing island is the
document a commerce protocol quotes when an agent asks the price.
Tools that rewrite a PRODUCT.md MUST preserve frontmatter, islands, and sections they do not understand, verbatim. The file's git history is the product's identity changelog; rewriters don't get to erase it.
The ## Register heading is canonical. Frontmatter
register: MAY mirror it and
MUST NOT disagree with it. Checkers flag
divergence.
CommonMark, one H1. Machine-checkable.
Register, Users, and Purpose present via the alias table; all islands valid. Machine-checkable, verifiable from outside.
The taste tier: sections that pass professional review, not just a parser. Judgment-bearing, evaluated rather than linted. Named for the tool that defined it.
Interview-driven bootstrap, then npx productmd check to verify Level 2.
Already on impeccable? Its init has written this file since v1. You're done.
Copy the annotated file above and rewrite every section for your product. Honesty beats polish.
The origin implementation. The design skill that made 100,000 projects write PRODUCT.md before the spec had a name.
Agent. Human. Identity. Every reader of the file proves who it is the same way, whichever kind it is.
The business substrate. Services and agents that consume the file as the definition of what they operate.
Shipping product.md across a portfolio of generated startups, every live site publishing its own definition.
Files on the open web: the counter goes live with v1.0.