v0.1 draft Specification family · pre-launch
Markdown as the universal transport layer for applications.
Canonical specs, open to every agent. The file owns the state.
Markdown To defines small, strict, versioned Markdown specifications
— todo@0.1, kanban@0.1, audio@0.1 —
where a conforming .md file is not a document about an application.
It is the application’s complete, portable state: readable in any viewer,
diffable in git, never captive to a tool.
kanban@0.1 round-trip
demo
--- markdownto: kanban@0.1 title: Markdown To launch --- ## Backlog - [ ] Publish conformance fixtures #infra - [ ] Draft the llms.txt endpoint [owner:: akshay] ## Doing - [ ] Build the patch engine ^t3 - [ ] Write the kanban spec doc [priority:: high] ## Done - [x] Choose the portable envelope
Drag a card between columns — or just click one to advance it. There is no checkbox: the column is the state, so a card landing in Done is ticked in the file, and one leaving Done is unticked. Every gesture is a minimal edit to the Markdown source, and the file is downloadable at any moment.
§ 01
How it works
A conforming file is parsed once into a typed intermediate representation. Everything downstream — validation, rendering, mutation — consumes that IR and nothing else. The path home is always the same file.
-
01
A plain file
You hand-write
.kanban.md. GFM task lists, Dataview-style inline fields, Obsidian block refs. Nothing to memorise, nothing invisible. -
02
A typed IR
Parsed to one canonical typed representation per spec, every node carrying its source position. Deterministic — no model guesses what a heading means.
-
03
A live app
Renderers and verbs read the IR only. The same bytes open as a checklist, a drag-and-drop board, or an audio manuscript.
-
04
Back to the file
Each edit is a semantic op through the patch engine: the smallest possible source diff, unknown fields preserved, unrelated prose untouched. Download any time.
A conforming file must be a joy to write by hand.
§ 02
The V1 specs
Three small formats, each shipping the same four local adapters —
validate, render, docs, verbs —
plus conformance fixtures from day one, so “adheres to the format” is
testable by anyone. All three are v0.1 drafts and will change.
todo@0.1
--- markdownto: todo@0.1 title: Household --- ## This week - [ ] Renew car registration [due:: 2026-08-15] - [ ] Call plumber [priority:: high] - [ ] Get two quotes - [x] Refill the water filter ## Someday - [ ] Reorganise the garage #weekend
The simplest spec — deliberately
Frontmatter plus GFM task lists, optionally grouped under headings, optionally nested. It defines the item model that kanban reuses, so both specs exercise one implementation.
- Heading
- a section (optional — a bare list is valid)
- Task item
- an item; order within a section is meaningful
- Nesting
- subtasks; parent completion is not auto-derived in 0.1
- Inline fields
priority,due,owner— unknown fields preserved
verbs
adddoneundonermmove
kanban@0.1
--- markdownto: kanban@0.1 title: Markdown To launch --- ## Backlog - [ ] Define the format schema [priority:: high] - [ ] Publish conformance fixtures #infra ## Doing - [ ] Build the patch engine ^t3 ## Done - [x] Choose the portable envelope
A board is a grouped view of the same items
In an ordinary Markdown viewer it degrades to a useful sectioned checklist. That degradation is the portability promise. This spec is where the round-trip gets proven: a drag produces the smallest possible source edit, never reformats unrelated prose, and conflicts visibly instead of overwriting.
- H2 heading
- a column; the set and order come from the document
- Task item
- a card; position within a column is meaningful
- [x]- done, wherever the card sits — and a move into the last column writes it for you
^t3- a lazy ID, pinned only because tooling touched that card
verbs
addmovedonermedit
audio@0.1
--- markdownto: audio@0.1 title: Field notes, week 32 voice: warm-narrator pace: relaxed pronunciations: agentsfs: "agents F S" --- # Chapter 1 — The idea Markdown is already the closest thing agents and humans share as a native format. [pause:: 2s] So what if the file simply *were* the application? > [narration:: skip] Producer note, not read.
A manuscript you would read anyway
Headings are chapters, prose is narration, direction lives in frontmatter and a few sparse inline fields. Chapter boundaries drive chunked generation, and caching is keyed per-chapter — so fixing a typo in chapter four never regenerates the book.
- H1 / H2
- a chapter, and a generation + output boundary
pronunciations- a frontmatter map applied throughout
[narration:: skip]- excludes a block from the audio
[pause:: 2s]- inserts silence
verbs
estimatepreviewvoicesproduce
produce is the only adapter that costs money. It runs locally in
V1 with your own provider key; the hosted, metered version is
coming.
§ 03
Agents are first-class
Agents are the primary users of the CLI, and the value over freehand editing is determinism: guaranteed-valid output, minimal diffs, no whole-file context required. The verbs are a library; the CLI is its first client.
$ mdto validate launch.kanban.md ok conforms to kanban@0.1 · 5 cards, 3 columns $ mdto kanban move t3 Done ok 1 line changed · launch.kanban.md $ mdto spec kanban kanban@0.1 — agent-facing specification 1. Purpose what the format is for 2. Grammar heading = column, item = card 3. Rationale why it is shaped that way 4. Examples valid + invalid + diagnostics 5. Verbs add · move · done · rm · edit $ mdto audio estimate week-32.audio.md 6 chapters · 18,412 narratable characters est. 14m 20s · caching keyed per chapter note produce is metered — hosted tier coming
-
Each spec owns its verbs
There is no universal mutation vocabulary. Todo and kanban overlap because they share an item model — a coincidence of domain, not a platform contract. Audio’s verbs share nothing with either. A new spec invents whatever its domain needs.
universal
validaterenderspec -
Every spec documents itself
Each spec ships an agent-facing doc versioned alongside it — purpose, grammar, rationale, examples with their exact diagnostics, and the verb reference. Agents repair and extend files far better when they know why the structure is what it is, and won’t “fix” things in the wrong direction.
consult
mdto spec kanban -
Fetchable, not scrapeable
The same doc will live at a stable URL alongside an
llms.txt, so an agent never has to scrape a human documentation site to author a conforming file. Conformance fixtures double as documentation.
§ 04
Two tiers, one contract
local
Free and deterministic
validate, render, docs and every spec’s
verbs run entirely on your machine, offline, forever. This is what keeps
the never-captive promise credible rather than rhetorical.
hosted · coming
Metered where it costs
Only produce adapters — the ones needing provider secrets and
real money, starting with TTS narration and produced episodes. A visible cost
estimate before anything is spent. Everything else stays local and free.
pre-launch Nothing here is shipped software yet. The specifications are v0.1 drafts being written in the open; the CLI, the renderers and the hosted tier are in progress.