> **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:

````markdown
```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](https://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](/blog/the-gap-in-your-product-knowledge). To see how the format works in practice — Markdown for humans, structured UI for everyone else — read [One file, two audiences](/blog/one-file-two-audiences).