Skip to content
PDaCProduct Definition as Code

Product Definition as Code: Specification

Status: v0.9 draft (request for comments). Extracted from the reference implementation and under public review; see the repository README for milestones. All chapters are currently at stability level draft as defined in GOVERNANCE.md.

This is the normative specification for Product Definition as Code. It defines the terminology, the artifact contracts and their exhaustive frontmatter, identity rules, relationship vocabulary, Product Change semantics, delivery slices, the Product Handoff contract, deterministic validation and conformance criteria.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in these documents are to be interpreted as described in RFC 2119.

Human-facing explanations live in the methodology overview of the reference implementation. Where any explanatory text and this specification appear to disagree, this specification wins.

Contents

Section titled “Contents”
  1. Terminology — definitions of the terms used normatively.
  2. Artifacts — artifact types, frontmatter contracts, required body sections, lifecycle states.
  3. Frontmatter reference — the exhaustive per-kind field tables (generated from the schemas): required and optional fields, allowed values, provenance.
  4. Identifiers — stable immutable IDs, prefixes, grammar, file naming.
  5. Relationships — canonical relationship vocabulary and derivation rules.
  6. Product Changes — change structure, operations, overlay validation, lifecycle, promotion, the initial-baseline bootstrap exception.
  7. Delivery Slices — slice structure, coverage declarations, lifecycle.
  8. Handoff Contract — the Product Handoff and Product Context contracts, subgraph selection, staleness.
  9. Validation — deterministic diagnostics, stable codes, exit codes.
  10. Conformance — what it means for a repository and an implementation to conform.

Canonical authority

Section titled “Canonical authority”

Within a repository that adopts Product Definition as Code:

PathAuthority
docs/product/model/**/*.mdCanonical current product semantics
docs/product/changes/active/**/change.mdCanonical definition of a proposed Product Change
docs/product/changes/active/**/proposed/**/*.mdCanonical proposed future-state product semantics for that change
docs/product/changes/active/**/slices/*.yamlAuthoritative delivery decomposition for that Product Change
Product Handoffs, Product Context documents, graph files, generated indexes, Mermaid diagrams, traceability reportsGenerated and non-canonical

docs/product/model/index.md is a human navigation and orientation document only. It MUST NOT duplicate relationships and MUST NOT act as a generated product index.

Generated files MUST be reproducible from canonical sources at any time. Tools MUST NOT require a generated file to exist in order to rebuild it.