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.aiproductmd: 1register: 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 aphone 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 arerare 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 ismetered, 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
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.
npx productmd check to verify Level 2.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.