What TODO.md is
A TODO.md is a markdown file whose task lists are the
list. The syntax is the one everybody already writes — GitHub-Flavored
Markdown task list items, - [ ] for open and - [x]
for done, nested however the work nests:
## Now
- [x] Register the domain
- [ ] Write the register index
- [ ] Decide what the placeholder rows say
That is not a proposal; it is a description. There is no heading you must
use, no section you must include, and no ordering rule. A file that a
human wrote by hand last year is already a valid TODO.md.
What this standard adds
Three keys of frontmatter. That is the entire substance of it.
---
$id: https://todo.md.org.ai/TODO.md
$type: ItemList
$context: https://schema.org.ai
---| Key | What it says |
|---|---|
$id | The file's own address — the URL another document cites when it means this file. |
$type | What the file is, named in a vocabulary that already has a word for it. |
$context | Where that vocabulary lives. Always https://schema.org.ai here. |
ItemList is not a word we coined. It is
already in the vocabulary —
“a list of items of any sort” — and a list of things to be done is
a list of items. Its members are
ListItems. Looking
the type up cost nothing; coining TodoList would have cost
every reader who already knows ItemList.
Frontmatter is inert to a markdown renderer: GitHub, a static-site generator and a terminal pager all skip it. A file that carries these three keys is still an ordinary file of its kind for every tool that has never heard of this register — which is the only reason it is safe to add them.
Optional tokens, borrowed from todo.txt
Where a project wants more than a checkbox, the tokens from the
todo.txt format carry over unchanged in meaning. They sit
inside the item text, after the checkbox, and mean nothing special to a
markdown renderer:
| Token | Means |
|---|---|
(A) (B) (C) | Priority, highest first, immediately after the checkbox. |
+project | The project the item belongs to. |
@context | Where, or with whom, the item can be done. |
key:value | Any other field. due:2026-08-01 is the common one. |
- [ ] (A) Write the register index @web +md.org.ai due:2026-08-01
These are conventions, not requirements. A
TODO.md with no token anywhere in it is a perfectly good
TODO.md, and a tool that does not parse them still reads the
file correctly.
The canonical file
/TODO.md is served from this host as
text/markdown. It is the example and the template at once —
copy it into a repository and delete what does not apply. The bytes below
are that file.
---
$id: https://todo.md.org.ai/TODO.md
$type: ItemList
$context: https://schema.org.ai
---
# TODO
The canonical example of a `TODO.md`. Everything below the frontmatter is
ordinary GitHub-Flavored Markdown: a heading, some sections, and task lists.
Everything above it is the whole of what this standard adds.
## Now
- [x] Register the domain @ops +infra
- [x] (A) Serve this file as `text/markdown` @web +infra
- [ ] (A) Write the register index @web +md.org.ai due:2026-08-01
- [ ] (B) Draft AUTH.md @spec +md.org.ai
- [ ] Decide whether it describes the file or the flow
- [ ] Find an existing `$type` before coining one
- [ ] Ask three people to break it @outreach +md.org.ai
## Later
- [ ] (C) CONTEXT.md, SKILL.md, DESIGN.md @spec +md.org.ai
## Done
- [x] Pick a `$type` that already exists: `ItemList` @spec +md.org.ai
---
## What a reader may assume
A `TODO.md` is a markdown file whose task lists are the list. A tool that
understands nothing but GFM still reads it correctly; a tool that understands
the frontmatter additionally knows what the file *is*, what vocabulary its
words come from, and what to call it when linking to it.
The optional tokens above are borrowed from `todo.txt`, unchanged in meaning:
| token | means |
| --- | --- |
| `(A)` `(B)` `(C)` | priority, highest first, immediately after the checkbox |
| `+project` | the project the item belongs to |
| `@context` | where or with whom the item can be done |
| `key:value` | any other field; `due:YYYY-MM-DD` is the common one |
They are conventions, not requirements. A `TODO.md` with no token in it is a
valid `TODO.md`.
Status — read this before citing anything here
This is our own convention, written in this estate — the markdown task list is everyone's, and only the frontmatter profile of it is ours. It is new. It carries no version number, because there is nothing yet to have changed from, and version numbers on a two-week-old convention are theatre.
No adoption is claimed. No count of implementers is given here, because the honest count is the one we would rather not print. If that changes, this paragraph changes with it.
There is no 1.0 and there will not be one until the shape has survived people other than its authors trying to break it. Until then every page in this register is a proposal published so that it can be broken.