Specification Book

Schema-Based Graph Object Model

A specification is a graph of typed objects

Every object carries a kind and a name, an optional id, optional properties, an optional description, and optional child objects. Which object kinds are allowed, how they may nest, and which properties they carry is defined per context by the YAML schema configuration — not hard-wired into the tool.

Versatile Markdown Mapping

Authored as plain Markdown, not as a foreign format

Objects are written as ordinary Markdown headings, property lists, and description prose — readable and diff-able in any editor and any code review. The very same object model maps onto nested sections (the complex format) or onto compact bullet point lists (the concise and group formats).

Wiki-Style Object Linking

Objects reference each other through Wiki [[xxx]] links

References are resolved against the locally-unique ids and names of all objects across the entire corpus, so a fact lives in exactly one place and every other place points at it. In the HTML and PDF exports the references become navigable links onto precise anchors.

Strict Validation

The schema configuration is enforced, not suggested

The YAML schema configuration defines the allowed object kinds, hierarchies, and properties, whose values are constrained by an expression language (regex, enum, tags, list, and reference). Beyond the plain values it constrains the uniqueness and presence of a property among the sibling objects, the shape of a reference-valued property (local, symmetric, and/or acyclic), and it can declare the child objects of an object kind a finite state machine, whose reachability, dead-ends, and livelocks are then checked. Violations are reported as file- and line-precise diagnostics.

Diagram Visualisation

Diagrams derived from the object model itself

Object kinds can declare graph, hub, or grid diagrams in the schema, whose nodes and edges are derived automatically from the object model and its references — so a diagram can never drift away from the specification it depicts. The rendering is done by the sibling project Gradia, which is specialized in rendering object models. Hand-written Mermaid and D2 diagrams can be embedded in addition and are rendered in the very same theme colors.

HTML Export for Developers

One self-contained document for daily reading

A single HTML document with a title page, a table of contents (also as a slide-in side panel), a diagram of contents, a fuzzy full-text search, embedded images, PDF pages, Mermaid/D2 diagrams, and syntax-highlighted code listings, the folding and maximizing of all of them, reference coverage tables,a scroll progress meter, description popups, and a light/dark theme toggle. It can even be previewed live in the browser, updating in place on every change while the scroll position survives.

Full Theming Support

Dark and Light Theme

The specification can define its own base accent color (default is RGB #336699), plus optionally also the signal color, for coloring the specification's texts, tables and diagram boxes. In the HTML rendering you can even ad-hoc toggle between a light and a dark variant of this theme.

PDF Export for Customers

A polished, paginated document to hand over

The PDF export prints the HTML rendering through Chromium and post-processes it with page numbers, headers and footers, a brand bar, and a hierarchical PDF outline. The paper size (A4, Letter, or Legal) drives the pagination and scales the diagrams down to fit onto a single page. This export format is especially intended for creating contract-relevant binding specification documents in customer contexts.

AI/LLM Comprehension

Machine-readable, so agents read and write specifications

The specbook describe command can tell an AI/LLM about the particular specfication schema, so AI agents can directly read and write the SpecBook Markdown files. An easy integration into a typical agent harness like Claude Code exists through the a dedicated /specbook skill and companion specbook mcp command

The Corpus

Objects as Markdown

Every object is a plain Markdown heading with a kind and a name, an optional id, an optional property list, an optional description, and optional child objects. Depending on the schema, an object kind maps onto nested sections (the complex format) or onto compact bullet point lists (the concise and group formats).

Objects reference each other through Wiki-style [[xxx]] links, resolved against the locally-unique ids and names of all objects across the whole corpus. Exactly the artifact files the schema's file fields reference are loaded — every other Markdown file below the base directory is left alone.

The Schema Configuration

Rules as YAML

The YAML schema configuration declares the allowed object kinds, how they nest, and which properties they carry. Every property value is constrained by a small expression language, and beyond the plain values the configuration also constrains the structure the objects and their references may form.

Several configurations can be merged into one effective schema (objects deeply, list elements by identity), and a bundled standard configuration applies whenever none is given at all. Violations are reported as file- and line-precise diagnostics, and both lint and export fail on any error among them — so a partial or invalid specification is never exported.