Adopt Product Definition as Code

Product Definition as Code (PDaC) is a method, not a tool. It fits whatever you already use: a backlog, an SDD framework such as OpenSpec or Spec Kit, or a coding agent on its own.

The idea is small, and it has three beats. Define once: write down what the product means, in small Markdown files people and agents can both read. Build from it: let tickets, specs and prompts point at those files instead of restating them. Change without losing track: move a decision in one place, then find every document that relied on the old wording.

You do not have to describe the whole product, or install anything to try it: every kind of file has a copy-paste template. ProductShape is the reference implementation, and it is optional.

Start with one decision

Pick a decision people keep repeating, or keep getting slightly wrong. A business rule is the easiest one. Write it in a single file with an ID, in the place it will live for good, for example docs/product/model/business-rules/br-refund-001.md:

---
id: BR-REFUND-001
type: business-rule
title: Refund window
status: active
---

## Rule

Refunds are accepted within 30 days of delivery.

## Rationale

Customers need a predictable window; finance needs a bounded liability.

## Examples

A delivery on March 1 may be refunded through March 31.

## Exceptions

None.

Those four frontmatter fields and four sections are all a business rule needs; links to other files can come later. The other ten kinds have the same ready shape on the templates page.

Then:

1. Ask whoever owns the product to read the rule and agree that it is right.
2. Point one real ticket, spec or agent prompt at the ID and the file. Before the work starts, have the agent read the rule and the code it touches and say where the two disagree.
3. Let your normal process build and test the item. If the work turns up a new product decision, bring it back as a proposed change instead of quietly editing the rule.
4. Stop there. Ask whether the clearer context was worth keeping the file, before you write any more.

That much is already useful, and it is not yet a full PDaC repository. The ID, the plain Markdown and the file shape are what let the same knowledge move into the full method later without anyone typing it again.

Where to start, depending on what you have

• A new product. Write one rule, use case or requirement from what you intend to build, starting from its template, then make it official through CHG-INITIAL. Add other kinds of file only when the product needs them. See the greenfield guide.
• A product that already exists. Recover one decision from what you are allowed to use: current documents, tests, code and conversations. Record where it came from and how sure you are, and let a person confirm it before it becomes official. See the brownfield guide.
• You already use OpenSpec. Treat your current specs as evidence, agree a product definition above them, then wire up one current document: cite the rule it depends on and let citations verify watch it. The integration adds guidance and citation checks without taking OpenSpec over. See the OpenSpec guide.
• You already use Spec Kit. Keep the constitution and the specify, plan and tasks lifecycle. Give one feature its product context, then check that feature’s documents with the integration. See the Spec Kit guide.
• You just use a coding agent. No integration needed. Give the agent the agreed files, or a prodshape context <ID> [<ID>...] briefing, keep anything long-lived in the repository and cite the product text it depends on.

For the exact files an install adds, who owns them and how to update them safely, see the existing repository guide.

PDaC next to Spec Kit and OpenSpec

Complements, not competitors: an SDD framework owns one implementation increment, PDaC owns the product meaning every increment reads from.

Question	Spec Kit, OpenSpec	PDaC
What does it own?	One implementation increment: spec, plan, tasks	The accepted product definition that outlives every increment
Where does shared product meaning live?	In each spec’s own words, or a constitution read whole	In one file per decision, cited by stable ID and content digest
What happens when meaning changes?	Each document is updated by hand, or quietly drifts	One command flags every recorded citation for a person to review

The full argument is in The layer above Spec Kit; the OpenSpec and Spec Kit guides above wire the checks into an existing repository.

Three doors, not three floors

The beats say what the method does; the doors say how much of it you adopt. They are not levels, there is nothing to configure, and they combine in any order. Enter through the one that matches the failure in front of you.

What goes wrong	What to add	What it still does not tell you
Every agent session rebuilds the same product decisions, or gets them slightly wrong	Write it down: Markdown files with stable IDs, in one agreed place	Whether what you wrote is right or complete
Meaning drifts because anyone can edit anything, and related decisions stop agreeing	Agree how it changes: the PDaC rules: typed links, an agreed definition, and changes proposed explicitly	Whether an agreed change was built, tested, released or deployed
A link or a citation breaks and nobody notices	Make it checkable: ProductShape’s checks, navigation, impact analysis and citation verification	Whether the delivery work agrees with the definition
A ticket contradicts the product or the code before anyone starts building	An agent reading the ticket, the definition and the code together: a practice, not a door, and an experiment today	Whether the work is ready, which stays a person’s call

Full PDaC is a set of rules to meet, not a level to reach: the specification says what they are.

Follow the PDaC rules when the definition has to be trusted

Same Markdown, stronger promises:

• The agreed definition lives under docs/product/model on your main branch. Graphs, indexes and reports are generated from it, never the other way round.
• Typed links, where each link says what kind of link it is, let a tool check what depends on what.
• The first agreed version arrives as a change called CHG-INITIAL. After that, every change of meaning is proposed as a Product Change, checked against the current version, and agreed by a person in review.
• A Product Change says what the product should now mean, not that the work was built, tested, released or deployed.
• The definition and the delivery can move at different speeds, sharing a pull request or running apart.

You can follow these rules with plain files and any tool that implements them. If you want ProductShape to do the checking, install it once you know you want that:

npm install --save-dev --save-exact @prodshape/cli@latest
npx --no-install prodshape init --dry-run
npx --no-install prodshape init --gitignore
npx --no-install prodshape change create CHG-INITIAL

init creates four files, not a whole folder structure. Move your first file under the new change’s proposed/ directory, list its ID under operations.add, then check it against what is already agreed:

npx --no-install prodshape change validate CHG-INITIAL

A person approves the meaning. Once the change says approved, prodshape change apply CHG-INITIAL moves the file into docs/product/model, and merging that reviewed result makes it official: apply never commits and never agrees to anything by itself. The governed citation-first walkthrough runs the whole loop end to end.

With a first version in place, the tool can check and explore what the files say:

npx --no-install prodshape validate
npx --no-install prodshape inspect BR-REFUND-001
npx --no-install prodshape impact BR-REFUND-001

validate checks file shapes, IDs, declared links, lifecycle rules, any change in flight and the state of every citation. inspect and impact show what is connected to what. None of it reads meaning the way a person or an agent does.

Add citations when a document has to survive the rule changing

An ID says which rule a document depends on. A citation adds a content digest of the exact words it relied on, which pays off when a spec, task or prompt outlives today’s conversation and somebody needs to know the rule underneath it moved.

For example, produce the citation for the refund rule, then paste the result next to the sentence in specs/refunds.md that depends on it:

npx --no-install prodshape cite --id BR-REFUND-001 --file docs/product/model/business-rules/br-refund-001.md
npx --no-install prodshape citations verify specs

Change the refund rule later and the check reports that citation as stale, naming the file and line someone needs to look at. It also spots a citation pointing at something that is no longer there, and a copied-in quote that no longer matches the original.

A clean citation proves only that the target still exists and still says the same thing, not that the spec, the ticket or the code agrees with the rule. An agent can judge that; a person decides what to do about it.

Let agents read meaning, and tools check structure

Before work starts, an agent can:

1. Read the incoming item as written.
2. Read the product files and the code it touches.
3. Run validate, inspect, impact and context for evidence anyone can reproduce.
4. Keep four things apart: what the product says, what the code does, what the tool reported, and what the agent is guessing.
5. Point out contradictions and missing decisions, and recommend something.

The person decides whether the work is ready. Ready work goes into your usual process with the product context attached; anything new it reveals about the product comes back as a proposed Product Change.

This review is an experiment today, not a feature: ProductShape has no readiness command and no check that judges meaning. Its commands supply the structural evidence; the agent does the reading.

Who decides what

ProductShape checks structure, links and citations. Agents read the product and the code and ask questions. People decide what the product should be and have the last word.

Start with one repeated decision, one ID and one real ticket. That is a whole first step, and a fine place to stop.