Every capture leaves an object behind
Talking to an AI produces a transcript, and a transcript is not a record: you can't grep it, link to it, or hand it to someone. So the verbs that matter write files instead. Not a summary of the conversation: a durable, addressable thing with an ID.
And because they are records, they read back: boss playbook renders them as
the company in sixteen chapters, boss design as
the design space, boss board as
the board. Three generated pages; the records are the only thing you write.
The status vocabulary is closed, and the record types arrive by rung; you
get the few you need on day one, not the whole filing system. Both are reference, both are
generated from the manifests, and both read better against your project than
against the superset: boss help --html writes them out for the types you
actually have. The closed list is what makes the board renderable; a typo would otherwise
become an invisible card, and boss records catches it before it does.
/idea, /decide and the evidence verbs are there on day one;
/spec arrives with MVP mode. 9 record types exist in total and
you're handed 3; see boss help --html.
Progress is derived, never maintained
"Where am I?" is the question a founder asks most often and documentation answers worst, because the obvious fix is a status document, and a status document is a second source of truth that starts lying in about a week. You update the files, you forget the board; or you update the board, and now two things disagree and nothing tells you which one is wrong.
So BOSS doesn't keep one. Status lives in the frontmatter of the file the work is actually about, and the board is drawn from the folder when you ask for it.
boss board reads the folder and draws the
columns on demand. There is no board file and no status doc to update, which is why nothing here
can quietly disagree with anything else. The empty column is drawn on purpose — a
stage with nothing in it is the most useful cell on the board.head -6 docs/ideas/IDEA-014.md --- id: IDEA-014 type: idea owner: product-lead status: exploring # the only place this is recorded --- boss board # reads the folder, draws the columns, keeps nothing
If the board looks wrong, the fix is to change the work, never the view. There is no view to
fix. When a card's one-line summary isn't enough, boss board <ID> opens that
one in full and boss board --detail puts a line under every card, still a read of
the files, just a closer one.
Going stale and giving up are both first-class
Nearly every documentation system is optimised for writing and has no verb at all for the two things that actually happen most: a document quietly stopped being true, or you stopped working on the thing. Both get handled here, which is most of why the pile stays navigable.
What's borrowed, and where this still leans on you
Very little here is invented. DEC records are architecture decision records,
which Michael Nygard wrote down in 2011: short, dated, superseded rather
than edited. Rendering a view out of file frontmatter is what note tools and project
databases have done for years. Treating a written artifact as a means of deciding rather
than a deliverable is Marty Cagan's point about discovery, and it predates
all of this. Everyone we learned from is on the credits page.
What's actually ours is narrower and worth stating plainly: the ceremony is rationed
by mode rather than issued all at once, and some of these documents are read by the
tool at runtime rather than only by people; a loop file in .boss/loops/ isn't a
description of a process, it's the thing that makes BOSS speak up. That's the composition,
not the parts.
Two of these were rules in your project and not yet mechanisms, and one still is. You don't
allocate the number by hand any more; boss id IDEA computes it, reading every
.md under docs/, filenames and prose, because a number
reserved in an index is taken even when no file exists yet. That closes the hole this page
was written to disclose: two files claimed the same number in BOSS's own repo on the same
day, and every reference to it was ambiguous until a person spotted it.
boss records now ships the other half: the checker that catches a duplicate ID,
an off-list status, and a broken promotion link. It also asks the question the rules never
could: a status is a claim about your code, so proof: names the file that would
not exist if the thing weren't done, and the check runs both ways. The expensive direction is
a finished feature whose record still reads exploring, a thing you might build
twice, or hand to an agent that rebuilds it, because the agent believes your docs.
What is still a rule and not a mechanism: nothing stops you writing a status
by hand that isn't on the list, or skipping boss id and typing a number. The
checker tells you afterwards. Detection is not prevention, and this page would rather say so
than let you find out. This paragraph was itself stale for four releases after the
checker shipped, which is the whole subject of the page, arriving on time.
None of this is set up. It's in the folder from the first command, and it's plain Markdown; readable, editable, deletable, and yours whether or not you keep using BOSS.
Then who shows up to help, or the guide for what to do rung by rung.