Product Behavior Contract (PBC) is a Markdown-first specification format for describing what a product promises to do.
Try the live viewer → · What is a Product Behavior Contract? →
PBC is meant to sit in the shared space between product, engineering, QA, and design:
- product-facing enough to read as a real contract
- structured enough to parse, lint, normalize, and project
- flexible enough to start in fluent Markdown and become more formal over time
PBC is a format for authoring the canonical WHAT layer of a product:
- behaviors
- rules
- states
- actors
- workflows
- stable declarative configuration that materially affects behavior
PBC is designed to combine useful parts of DDD, BDD, PRDs, and structured specification without collapsing into any one of them.
Short version:
PRD explains why.
PBC specifies what.
Code/tests/runtime prove how.
Most teams already have PRDs, tickets, design notes, tests, and code.
What they often lack is a canonical authored WHAT layer for product behavior:
one place that states what the product promises to do in a form that product,
engineering, QA, and tools can all work from.
PBC exists to fill that gap.
The core distinction is:
- CommonMark/GFM solve authoring and rendering.
- PBC gives humans, tools, and agents a typed, lintable contract for what the product promises to do.
That means PBC is not just "Markdown with a style guide", and it is not just a pure YAML/JSON schema either:
- Markdown/GFM alone are too convention-based. Headings and tables stay readable, but they do not declare product-behavior meaning strongly enough for deterministic validation.
- Pure YAML/JSON are too machine-centered. They carry structure, but lose the shared human document surface that product, design, QA, and engineering can all review directly.
PBC keeps both:
- Markdown as the readable authored shell
- structured
pbc:*blocks as the canonical machine-parseable contract surface
This becomes even more important as autonomous coding agents take on more implementation work. Agents usually have execution context, but not behavioral context. Without an explicit contract layer, they can build the wrong thing quickly and confidently. PBC gives them the missing grounding layer: valid states, rules, transitions, exceptions, and promised outcomes.
For a deeper explanation, see docs/philosophy/pbc-markdown-first-direction-v0.md.
PBC uses Markdown as the human authoring shell and fenced pbc:* blocks as the
machine-readable contract surface.
That choice is deliberate:
- Markdown stays readable in raw form.
- Structured blocks let tools parse the canonical parts deterministically.
- Teams can keep narrative context, diagrams, and review notes near the contract without making prose the canonical data model.
- JSON remains derived output, never the authored source of truth.
PBC is BDD-inspired, but not BDD-constrained. Given / When / Then is useful
for atomic behaviors, but PBC does not require the whole document to be
rewritten as Gherkin.
PBC documents are normal Markdown files with embedded fenced blocks such as:
pbc:glossarypbc:actorspbc:statespbc:behaviorpbc:rulespbc:configpbc:provenancepbc:grounding
This gives authors two layers:
- fluent Markdown for product-facing explanation
- disciplined semantic islands for canonical structure
- the current draft specification: docs/specs/pbc-spec-v0.6.md
- the GFM appendix: docs/specs/pbc-spec-appendix-gfm.md
- a short Markdown-first philosophy note: docs/philosophy/pbc-markdown-first-direction-v0.md
- a quickstart for reading and writing PBCs: docs/quickstart.md
- worked examples: examples/
- a CLI for validation, listing, and stats: cli/
- a browser-based viewer for interactive PBC exploration: viewer/
This repo ships two reference tools for local evaluation. Both are intentionally minimal — they exist to prove the format is machine-readable and to give teams something concrete to run, not as production-grade tools. Neither is published to a package registry yet; run them locally as shown.
Structural validation and inspection for PBC files:
cd cli && npm install && npm run dev validate ../examples/
cd cli && npm run dev list ../examples/ --type behaviors
cd cli && npm run dev stats ../examples/
cd cli && npm run dev init my-feature.pbc.mdNote: This is a reference implementation run via
npm run dev. It is not yet published to npm —npm i -g @pbc-spec/cliwill not work.
See cli/README.md for full documentation.
A browser-based viewer that parses pbc:* blocks and renders them as
interactive panels, SVG state diagrams, and live validation results — from
the same .pbc.md file that reads cleanly in any Markdown renderer:
cd viewer && npm install && npm run devThis gives teams the best of both worlds: technical contributors read and author in Markdown, while other stakeholders get a richer visual interface — from the same source file, with no export step.
Live demo: pbc.stewie.sh
Note: This is still a reference implementation for local exploration. The hosted viewer is a lightweight static demo, not a production product surface.
See viewer/README.md for details.
| Language | Component | Status |
|---|---|---|
| TypeScript | CLI | Reference — not yet published to npm |
| TypeScript | Viewer | Reference — not yet published |
Building an implementation in another language or framework? Open a PR to add it here.
This repo is not:
- a hosted runtime or product workflow
- the semantic grounding/runtime workflow
- a general-purpose requirements management system
Current ownership boundary:
pbc-specowns format, philosophy, examples, CLI tooling, viewer, and versioning- product/runtime implementation repos own implementation behavior and support
- STATUS.md
- docs/quickstart.md
- docs/specs/pbc-spec-v0.6.md
- docs/specs/pbc-spec-appendix-gfm.md
- ROADMAP.md
- examples/README.md
- cli/README.md
- viewer/README.md
- The PBC spec is live — and it's open source — the launch story and motivation
- What is a Product Behavior Contract? — deep dive into the format and why it exists
- One file, two audiences — how the same
.pbc.mdfile works as Markdown and structured UI
Stewie is built on PBC as the open format for structured product behavior contracts.
Using PBC in your product or tooling? Open a PR to add yourself here.
Licensing is path-based. See LICENSING.md for the full mapping.
- Spec, docs, examples — CC BY-SA 4.0
- CLI and viewer (
cli/,viewer/) — Apache-2.0
This is the first public PBC package.
The goal of this repo is to make the format legible, useful, and easy to evaluate on its own, with lightweight reference tooling for local exploration. Deterministic engines and hosted runtimes are separate implementation surfaces.