Overview
The Bot Assembly specification
Section titled “The Bot Assembly specification”Stability: stable.
This index names the chapters and states the publication’s version policy.
Changelog — what changed here, and why.
An assembly is a folder. A runtime executes it. Everything below is one element of that format, in one document.
File over app
Section titled “File over app”This format is built on one bet, borrowed from the essay of that name: the files outlive the program. An assembly is markdown and scripts a person can read in any editor, carry in git, and understand without the runtime existing — the folder is the program, and the app is just the thing that runs it today. That is why placement is the graph instead of a workflow engine’s database, why the record is JSONL instead of an API, why configuration is frontmatter instead of a console, and why nothing an assembly does is expressed anywhere a reader cannot see. It is an anti-framework: when this runtime is gone, the folders still say exactly what the work was.
Its running mate is progressive disclosure: an agent is told what exists — skills, subflows, inputs, by name and one line — and reads the rest only when it deliberately reaches for it (prompt construction, skills).
Start with the worked example, which shows the parts assembled. The invariants hold everywhere and are the law beneath it; the witness ledger names, for each one, what in this repository would fail if a runtime stopped honoring it.
Version and compatibility
Section titled “Version and compatibility”This publication is unreleased. It targets 0.1.0, the first public alpha, and the release that sets that string is the one that ships. The runtime, specification, and examples match within that release. Individual tickets do not bump a shared version or counter. A later pre-1.0 release may change assembly and record contracts without migration. Early alpha users may need to update assemblies and may need the matching older runtime to read an older record. Version 1.0 is the first promised cross-version compatibility boundary.
Stability labels distinguish settled and provisional requirements inside the current publication. A runtime’s conformance claim names the publication version it implements. Claiming conformance to 0.1.0 does not itself claim conformance to a later pre-1.0 publication or to 1.0.
The shape of an assembly
Section titled “The shape of an assembly”stage · flow · assembly · home · slots · skills
Gating
Section titled “Gating”gating · checklist · schema · gate · hooks
Arranging stages
Section titled “Arranging stages”graph · loop · choose · parallel · fan-out · subflow · descend
Running one
Section titled “Running one”runtime · refusals · invocation · prompt · auth
Reading one afterward
Section titled “Reading one afterward”record · session · inspection · management · conformance