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.
/triage, /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 the ladder below.
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.
7 words, and the list is closed
Left alone, a project grows four words that all mean shipped —
implemented, built, done, resolved — and
once it does, nobody can tell them apart. Not you, not a teammate, and not the agent reading
your repo to work out what's left. A vocabulary nobody can enumerate is not a vocabulary.
The status has to start with one of those words; everything after is
free-form and encouraged — shipped (v0.4, read-only slice) and
building (steps 1–3 done, 4 open) both say more than the bare word.
deferred is the one most systems are missing. It means
deliberately not being built, with a written re-open trigger — a decision, not a
backlog item. It's the difference between a thing you chose to leave and a thing that just
sank. /revalidate checks it back against a world that moved before it re-enters
the build.
You don't get the whole filing system on day one
This is the part that's genuinely unlike other approaches. Most documentation systems hand you the complete taxonomy up front and leave discipline to decide how much of it you use — which is how a weekend project ends up with an RFC template. BOSS rations the vocabulary itself. In Quickstart you get 3 of the 9 — enough to capture an idea, record a signal, and log a decision you can't easily undo. The rest arrive as the project climbs, and until then they're listed where you can see them coming without being asked to use them.
| ID | What it holds | You get it at |
|---|---|---|
IDEA-NNN | A raw idea, bug, or ask | day one |
EVID-NNN | One real signal about your riskiest assumption, honestly graded | day one |
DEC-NNN | A load-bearing or hard-to-reverse call, with a falsifier. Supersede, don't edit | day one |
FEAT-NNN | An idea that earned a build contract — named slices, or a build spanning more than one release | MVP |
PRAC-NNN | A craft learning worth keeping — and sharing with a cofounder | MVP |
EXTR-NNN | A pattern extraction decision (UP into the library / DOWN into app core; PRINCIPLE #1) | MVP |
RFC-NNN | A decision document | Scale |
EXP-NNN | A lab experiment | Scale |
shipped | not there | the record claims something your repo can't show |
Parsed at build time from the docs/IDS.md that ships in the scaffold — this table
and the file in your project are the same source.
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 docs/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.