The foundational documents

August 19, 2026 · View on GitHub

Created before any prose, saved in the project repository, and read by agents rather than inferred by them.

Each has exactly one owner. A second document describing structure, voice or scope is drift, and the resolution is always to fold it back and delete it — never to keep both and remember which one is current.

DocumentPathOwnsShips?
Brief as givenspec/brief.mdThe original framing, uneditedNo
Interviewspec/interview.mdThe gaps, filledNo
Book specspec/spec.mdWhat it is, who for, scope, lengthNo
Style guideguides/style-guide.mdVoice, register, prose conventionsNo
Graphics style guideguides/graphics-style-guide.mdVisual languageNo
Outlineoutline/outline.mdArc, chapter map, boundaries, orderNo
Chapter briefsoutline/briefs/<id>.mdOne chapter's contractNo
Continuity ledgercontinuity.mdWhat has been established, and whereNo
Manifestbook.tomlStructure, status, continuity keysNo

Nothing on this list appears in the printed book. They are production apparatus.

The outline never ships

Stated explicitly because the drift is natural and common: an outline becomes a preface, then a "how to read this book" chapter, then chapter zero.

It exists purely to guide the writing agents and any human co-author. A reader does not want the plan; a reader wants the book. The one legitimate descendant of an outline in a finished reference work is a table of contents, which is generated from the manifest.

The chapter brief is the load-bearing document

A brief is what a writer gets instead of the rest of the book. Everything that would otherwise come from reading adjacent chapters has to be in it:

SectionReplaces
ArgumentKnowing what this chapter is for
What the reader can do afterwardsKnowing where it lands
Assumed by this pointHaving read the earlier chapters
EstablishesKnowing what later chapters will lean on
Must coverThe plan
Must not coverNoticing you are writing a neighbour's material
SourcesHaving done the research
Neighbour summariesHaving read the chapters either side

"Must not cover" is the section people leave out and the one that prevents the overlap which shows up as repetition in the assembled manuscript.

If briefs are thin, writers compensate by reading — and the architecture collapses back into one large context, quietly, without anything failing.

The continuity ledger

The book's memory: every term, claim, running example and promise it has established, with the chapter that established it.

It is the mechanism by which chapter twelve knows what chapter three said without chapter twelve's writer having read chapter three. Four kinds of entry earn their place:

  • Terms — so nothing is defined twice, differently
  • Claims — positions taken, which later chapters may build on but not re-argue
  • Running examples — with their details fixed, so two chapters do not give the same example different numbers
  • Promises — "we return to this in chapter nine" needs a chapter nine that does, or the promise gets cut

A fifth section records deliberate repetition, because a reference work sometimes should restate itself for readers who open it in the middle. Recording those decisions is what stops the continuity pass from "fixing" them.

The manifest's establishes / requires keys are the machine-checkable shadow of this document: a chapter may only require what an earlier chapter establishes, and the linter enforces the ordering.

Why the brief is kept unedited

The first statement of what someone wants is evidence. Once paraphrased into a spec, the original framing — what was emphasised, what was assumed, what was left out — is unrecoverable.

It also makes the spec auditable. Anything in the spec that cannot be traced back to the brief is an addition, and additions should be visible as additions rather than passing as the user's own requirements.