What is a Product Behavior Contract?

Most product specs describe intent. A Product Behavior Contract (PBC) describes reality.

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, PMs, 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 contracts 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.