Initializing — flave gets a repo, a master spec, and a thesis worth building
An all-day PM grilling session turned a loose idea — 'polyglot markdown, but it recreates Pages and Keynote' — into a 24,000-word master spec with 20 decisions resolved on the record. The thesis moved twice under questioning and landed somewhere better than it started: flave is a document that keeps its workings. This entry initializes the repo that will build it.
Why Care?
Because the idea that arrived in the morning is not the idea that got specced, and the difference is the whole point of writing specs before code.
It started as “polyglot, user-extensible markdown — except we totally recreate Word, desktop publishing, and Keynote, built for agents.” Ambitious, and pointed at the wrong thing. Five candidate differentiators were put up against the only competitor that actually matters — “ask Claude for a self-contained HTML file” — and three of the five turned out to be real felt pains while the lead one was not.
What survived was sharper than what went in:
Flave is a document that keeps its workings. Publish it and people see the conclusion. Send the file itself and they get the evidence, the data and its sources, the reasoning, and the design vocabulary that produced it.
Pages and Keynote turn out to be positioning, not the job. Those are pure presentation tools with no concept of a private layer. The honest neighbours are literate-document tools — Jupyter, Quarto, Observable — and the claim against them is that they compile in one direction. Nobody sends a colleague a .qmd expecting them to work in it. A .flave is built to be exchanged and worked in.
What Landed
The master spec — ~24,000 words, 18 sections, 20 decisions resolved on the record with their dates and reasoning, 12 still open, 11 considerations parked for later. Every resolution carries what it changed and, where applicable, which earlier recommendation it overturned.
A build order that is deliberately small. Most of the spec is designed and parked. §1.1 names v0 as an editor and nothing else: markdown in a pane, rendered output beside it, and the ability to define your own syntax triggers. Five slices, each with a done-condition you can check in ten seconds. Slice 1 is the estimate.
A scaffold — README.md, context-v/specs/, changelog/, splash/.
Decisions Worth Reading
A few that moved the design materially:
- No mouse-driven layout. The owner’s constraint — “there is no real reason for the user to need to use the mouse to edit the layout” — went further than the capability ceiling being proposed, and made fixed-geometry surfaces tractable by deleting the entire class of “what does dragging across a page break mean” problems.
- Frames cascade like CSS.
builtin < theme < pack < document, most local wins, with a promotion path from a one-document experiment to a shared team standard. This downgraded the spec’s top risk from Critical to Medium. - Agents are fully autonomous, bounded by the undo horizon. Everything Jujutsu’s operation log can reverse is unrestricted; only operations that leave that region need a gesture. This overturned an earlier recommendation to gate history rewrites — which had imported git’s anxieties into a tool chosen specifically to remove them.
- Drift is recorded, never prevented. An earlier draft had brand-lock constraints that would have prompted before deviating from a template. Removed: “I can’t imagine if every time I was changing a layout in Keynote from our team’s standard template it said ‘Are you sure you want to do this?’ No way.”
- Audiences are (clearance × register), not strip-and-redact. Subtractive redaction can express “the LP doesn’t see the appendix.” It cannot express “concise and punchy for the public.”
Also Included
The spec’s reuse map was verified on disk rather than assumed, which produced an honest correction: astro-knots/packages/* is starter-copy and prior art, not a dependency graph — @knots/tokens is 49 lines of hand-written CSS and @knots/svelte is an empty index plus one Button. Only lfm was ever a true package, which is why it was extracted. Conflating “inherit code” with “inherit boundary” is how reuse plans become fiction, so the map now distinguishes them per row.
AstroMarkdown.astro was read (313 lines) rather than described from memory, which downgraded the renderer from “the one genuinely new package” to a mechanical Svelte port of a known file.
What’s Next
Run slice 1. It is small enough that a loop costs half a day rather than a project, and once it lands there is a real velocity number instead of a guess — which is cheaper than any further planning, including the spec that says so.