the layerEVERYONEwrites

the missing LAYER

Every serious project has a second product nobody ships: the intent. Why this exists, what's done, what's next, what we decided and when. Today that layer is scattered — a README that's half true, tickets in one silo, the spec in another, and the agent's context in none of them.

The formats on offer force a bad trade. Markdown is lovely to read and means nothing to a machine — it's a blogging language. You can't validate it, can't write a test suite for it, can't reliably parse a plan out of it. YAML and JSON parse perfectly and can't hold a paragraph of reasoning. Prose or structure: pick one. The ecosystem refuses to pick.

the DEFINITION

The name comes from org-mode, the format it grew from. In Workbooks, org is simply the grammar everything is authored in — the same way the web settled on HTML for what things look like, the ecosystem settles on org for what things mean.

born twenty years EARLY

Org-mode appeared in the Emacs world around 2003, as a way to keep notes, to-dos, and schedules in plain text. It sits in the lineage of literate programming — Donald Knuth's old, stubborn idea that code should live inside the explanation of why it exists, not the other way around. Over two decades it quietly grew the exact feature set agent systems are now reinventing badly: task states, timestamps, dependencies, and tangling — source code written inside the document, extractable to real files.

And here's the accident of history that makes it perfect now: those twenty years of documentation are in every model's training data. Agents don't have to be taught org. They arrived knowing it.

what one file can HOLD

A taste of what that looks like in practice — this is a real deployment, described entirely in org:

* deployment
** ENGINE_PLACE: local          # flip to "fly" → same engine, in the cloud
** DATABASE: sqlite
** TODO rotate signing key      SCHEDULED: <2026-06-20>
** notes
   single-tenant for now; revisit when the team joins.

Configuration, a scheduled task, and a paragraph of reasoning — one file, and every line of it is parseable.

"why not just MARKDOWN?"

Use Markdown! It's wonderful — for writing. The trouble starts when you ask it to run a system. There are no states, no dates, no dependencies — just headings and vibes. When an agent drifts (writes one file too many, contradicts itself across notes), Markdown has no way to even notice. You can't write a test suite for Markdown. You can for org: parse the tree, check the states, validate the dates, diff the intent.

That's the whole argument in one line: Markdown is for telling humans things. Org is for telling humans and systems the same thing at once.

where it shows UP

• Inside every workbook — the writable layer where intent, tasks, and memory live (part one).
• Toolkit manuals — the readable surface that doubles as the tool's interface (the manual is the API).
• Deployments — one declarative org file describes the whole engine setup (dev is prod).
• Workflows — plans whose tasks, states, and dependencies render straight to boards and timelines, executed by agents.
• Agent definitions — who an agent is, written in the same grammar it works in.

One grammar everywhere is the quiet superpower: every piece of the ecosystem can read every other piece, and so can you.

where it bItes

Honesty section. Plain text drifts — agents writing freely will eventually write too much, or twice, or contradictorily. Org doesn't prevent that; no format does. What it does is make drift detectable: because the layer is parseable, a checker (or another agent) can walk the tree and find the contradiction. And org is not a database — heavy structured data belongs in the workbook's SQLite, not in headlines. Use each layer for what it's for.