What is a Product Behavior Contract?

TL;DR: A Product Behavior Contract is a .pbc.md file that documents what a module actually does today, with trust levels and links back to the code as evidence. This post explains the structure (behaviors, candidates vs. trusted claims, module maps) and what a PBC is not (not a test suite, not a requirements doc), plus how the open spec + CLI + viewer fit together.

Most product specs describe intent. A behavior spec describes reality — and PBC (Product Behavior Contract) is the format that makes it structured, versioned, and machine-readable.

It's a structured markdown file — .pbc.md — that captures how a module actually behaves, grounded in evidence from your codebase. Not what was planned, not what's in the wiki, but what the code does right now, confirmed by a human who knows the system.

Why not just use a wiki or a spec doc?

Traditional spec docs are written at a point in time and then drift. They capture what someone believed was true when they wrote them. Code keeps moving; docs don't.

A PBC is different in two ways:

1. It starts from code, not intent. The behaviors in a PBC are extracted from your actual codebase and confirmed by your team — not written from memory.
2. It lives in your repo. A .pbc.md file is version-controlled, diffable, and readable by anyone on the team. When the code changes, the spec can change with it.

The format

A PBC file is plain markdown with structured behavior blocks. Each behavior has a given/when/then shape — BDD-inspired, but not BDD-constrained. You can write prose around and between the blocks. The structure exists to make behaviors machine-readable and reviewable, not to force you into a rigid format.

Here's what a confirmed behavior looks like:

```pbc:behavior
name: Session token expiry
status: trusted
evidence: [src/auth/session.ts:42, src/middleware/auth.ts:18]
```

```pbc:preconditions
- A user has an active session
```

```pbc:trigger
60 minutes pass without activity
```

```pbc:outcomes
- Session is invalidated server-side
- User is redirected to /login
- Audit event "session_expired" is logged
```

A few things to notice:

• status: trusted — this behavior has been confirmed by a human. It's not inferred; it's signed off.
• evidence — every trusted behavior links to the files that support it. If someone changes session.ts:42, they know a behavior is affected.
• given/when/then — readable by engineers, product owners, and QA alike. No special tooling required to understand it.

Before a behavior is confirmed, it starts as a candidate with a confidence score:

behaviors:
  - claim: "Session tokens expire after 60 minutes"
    status: trusted
    evidence: [src/auth/session.ts:42]
  - claim: "All API routes enforce workspace tenancy"
    status: in_review
    falsifiers: ["3 routes bypass middleware"]

in_review means a behavior has been extracted but not yet confirmed. falsifiers means the analysis found evidence that contradicts or complicates the claim — something a human needs to look at before it can be trusted.

What a module looks like

A .pbc.md file describes a single module — Auth, Billing, Tenancy, or any domain you define. At the top is a product structure map: the modules, their confidence scores, and their review status.

modules:
  - name: auth
    confidence: high
    status: trusted
    files: 12
  - name: billing
    confidence: medium
    status: in_review
    assumptions: ["Stripe is authority-of-truth"]

This gives you a map of what's been confirmed, what's still being reviewed, and what's uncertain — at a glance, without reading code.

What it's not

A PBC is not a test suite. It doesn't run against your code and check whether behaviors pass or fail. It describes what should be true, grounded in evidence that it is true — confirmed by a human. You can build test coverage from it, but the PBC itself is a spec, not a test harness.

A PBC is not a requirements doc. It doesn't describe future features or planned behavior. It describes the present: what your product does right now, as confirmed by your team.

A PBC is not AI-generated documentation. The extraction is AI-assisted, but every trusted behavior has a human sign-off. The whole point is that the spec reflects what your team has actually verified, not what a model inferred.

The open foundation

The .pbc.md format is a public, vendor-neutral spec. Your behavior specs are plain markdown — you own them, version-control them, and can read them without any tool. The spec ships with reference CLI tooling (validate, list, stats) and a browser viewer that renders structured PBC blocks as rich UI — all open source at github.com/stewie-sh/pbc-spec.

Stewie is the product built on top of this foundation — the AI analysis, grounding workflow, and living spec synthesis. Open format, proprietary intelligence.

For the problem that led to this format, read The gap between what your product does and what your team thinks it does. To see how the format works in practice — Markdown for humans, structured UI for everyone else — read One file, two audiences.