Inside the .pbc.md Product Behavior Contract format

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 is the format that makes it structured, versioned, and machine-readable.

If you're new to the idea, start with what a Product Behavior Contract is and why it exists. This post goes one level deeper — into the .pbc.md file format itself: the blocks you write, and what each one is for.

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 is declared with a pbc:behavior header, then decomposed into pbc:preconditions, pbc:trigger, and pbc:outcomes — 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 behavior looks like:

```pbc:behavior
id: AUT-BHV-009
name: Session token expiry
actor: auth_policy
description: The product invalidates an idle session after 60 minutes without activity.
```

```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
```

```pbc:provenance
- src/auth/session.ts:42
- src/middleware/auth.ts:18
```

A few things to notice:

• id and actor — every behavior has a stable id and an owning actor, so it can be referenced, traced, and reasoned about across the contract.
• pbc:preconditions / pbc:trigger / pbc:outcomes — the given/when/then, readable by engineers, product, and QA alike. No special tooling required to understand it.
• pbc:provenance — links the behavior back to the files that support it. If someone changes session.ts:42, they know which behavior is affected.

On top of the format, a tool like Stewie layers a review state — whether a behavior is still a candidate or has been confirmed by a human, and what evidence contradicts it:

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.