Your engineers live in Markdown. Your product manager wants something they can actually read. You don't need two documents.
Most spec formats make you choose.
Write in Markdown and your PM opens the file on GitHub, squints at the YAML blocks, and asks for a summary in Notion. Write in a visual tool and your engineers treat it as a secondary artifact — something to consult occasionally, never the source of truth.
PBC doesn't ask you to choose.
The file is just Markdown
A .pbc.md file opens in VS Code, renders on GitHub, and reads like any other document. The narrative prose explains context. Tables summarize states. Headings give structure.
An engineer reviewing a PR sees a diff they can read. A new hire reads the file and understands what the billing module promises to do. No special tooling required.
This is the baseline. It has to work here first.
The blocks are the contract
Embedded inside that Markdown are pbc:* fenced blocks — YAML content that a parser can extract deterministically.
```pbc:states
- id: active
definition: Paid subscription is current.
user_access: full
- id: past_due
definition: Payment failed, grace period in progress.
user_access: full
- id: expired
definition: No active subscription remains.
user_access: none
```
In a Markdown renderer, this looks like a code block. To a tool, it's a typed list of states with known structure — IDs, definitions, access levels.
The block is invisible friction. It doesn't interrupt the reading experience. But it makes the document machine-readable in a way that plain prose never can be.
The viewer unlocks the second experience
Drop the same .pbc.md file into pbc.stewie.sh and something different happens.
The viewer parses every pbc:* block and renders it as structured UI:
- Actors become cards with type badges — human, system, external
- States become a table and an SVG state diagram with transition edges
- Behaviors become an accordion — each one grouped with its preconditions, trigger, outcomes, and exceptions
- Rules become a scannable table
- Config becomes a collapsible tree
Click a state in the diagram and every related behavior and transition highlights across all panels. The document becomes navigable.
Your PM doesn't need to read YAML. Your designer doesn't need to know what a fenced code block is. They open the viewer, drop in the file, and see the contract as structured UI.
One source of truth, two reading experiences
The file doesn't change. No export step. No sync problem. No "the Notion doc is out of date again."
The engineer edits the .pbc.md file directly — same workflow as any other Markdown document. The structured blocks update automatically. The next time anyone opens the viewer, they see the current state of the contract.
This is what Markdown-first actually means in practice. Not just "we write in Markdown." The format is designed so that the structured semantic layer lives inside the human document, not alongside it.
Try it
The viewer is live at pbc.stewie.sh with three working examples — billing, authentication, and workspaces. Open one, explore the panels, then look at the raw .pbc.md source.
The spec and all tooling are open source at github.com/stewie-sh/pbc-spec.