Skip to content

BuilderOS 3.1.0

Choose a tag to compare

@mariomile mariomile released this 24 Oct 18:24
· 49 commits to main since this release
a17d0a7

After 3.0.0: what existing projects meet when the rules change, two sessions on one initiative, work that waits on a round, how a model-driven product behaves, the craft of what the person sees, a backend designed, secured and measured before it ships, flows drawn as diagrams the person edits, a video of every feature working, and the value, the stake and the go-to-market of a bet. Analysis and decisions (1B, 3A, 4A) in the project thread "Cosa migliorare ancora" (cosa-migliorare-ancora-2026-10-21.md); the backend and the interface bar in "Design eccellente e backend solido" (round 1, recommended options); diagrams and demo videos in "Diagrammi dei flussi e video e2e" (1A with an editable page and Pele, 2A with the video outside the codebase, 3A, 4A). What a person opens, clicks and receives (production from the first slice, a build tried before it is accepted, the project page, the messages a product sends, languages, help) in "Trovare cosa manca davvero a BuilderOS" (cosa-manca-davvero-2026-10-24.md, 1A 2A 3A 4A). The value of a bet, the stake and go-to-market in "Decidere cosa costruire con probabilità e GTM" (probabilita-gtm-scommesse-2026-10-24.md, 1A 2A 3A 4A).

Changed: gates check facts, not form

Measured on a hollow project (tests/fixtures/hollow): every artifact a gate asks for exists and nothing it describes does. Sixteen conditions of gates 4 and 5 passed on it; tests/scripts/hollow.test.mjs now requires each to fail and say why.

  • Files hold what they claim. Design versions, reference screens, captures and step screenshots must be real images (PNG, JPEG, GIF, WebP read by their headers), prototypes and previews HTML with visible text, recordings real video (4.9, 4.10, 4.21, 5.9, 5.15). One capture cannot stand for several states, and captures must match a reviewed width.
  • Runs run something. A captured command that only prints or exits (echo, true, printf, …) fails wherever a run is evidence; the demo's run must run its test; a performance row's number must appear in its run's output (5.14); the production check must call the production host (5.16). Instrumentation needs a data tag or a captured run, never a code tag (5.3).
  • The guardrail exists. 5.8 opens the file the guardrail names and finds a Verify command in it; 5.10 finds each quality check's tool there.
  • Reviews say what was looked at. A craft critique or security review where every row is a bare "none found" fails (5.12, 5.13).
  • Users, money and tests are read, not mentioned. A plan to meet users is not a session (4.13); "said they would pay" is an opinion, an act is a pre-order, a payment, a signature (4.14); 4.22 reads the channel test and any test-first card against their stop lines, on every track.
  • Person fields quote the person. The message hook appends each message to .builderos/person-log.jsonl, which the guard keeps out of hand edits. Chosen by, Accepted, Tried by, Rules decided by, Authorized by, --accepted-by, and the reasons of a kill, a jump or an override quote it; a quote the person never wrote fails. Without the log the field passes, marked unverified.
  • Tests decide. record N --kill "reason" at phases 0 to 6; an override waives conditions by name (--waive 4.22,5.8), never several by accident; the bet's appetite shows in the briefing and, once spent, in every message line.
  • A change costs what it touches. Six things always (scope with **Touches:**, criteria, impact on what it touches, tests against the baseline, the scope check, rollback); interface, copy, data, personal data, permissions, money, messages, contracts and stack each call in their own conditions. A slice editing a screen or a schema it did not declare fails the scope check. A label rename passes gates 4 and 5 on one page each.
  • Every move has its command. bos.mjs init, resume, reframe, jump. The project page names what the current phase waits on from people.
  • Order. The real-user session follows the flows, on a clickable prototype design-direction builds; the go-to-market, the test and the appetite come before the person picks the bet; slice zero lives in the accepted plan; the demo is recorded after the person tried the build. Frame, discover, define and ship return the person's round instead of choosing in a subagent; the build reviewer runs steps 7 and 8 only.
  • One place per fact. One Cheapest test template with its Result; the price in PRODUCT.md, drafted at initialization with the rest of ## Business; the channel in Go-to-market; one stage model, with Signal, Resonance and Orbit as its go-to-market names.
  • Each gate file lists its attested conditions, the ones resting on a fact outside the repository that the script checks only by citation.

Added

  • Gate records carry their version. record, cover and gate --json store bos_version and the conditions skipped as not applicable, so a later release can tell "not applicable then" from "not there yet". A test keeps VERSION in scripts/bos.mjs equal to package.json.

  • Debt after a release. The briefing lists, per initiative, conditions now in force that a passed gate never checked and its artifact does not meet yet; the phase stays passed (gate-checks, Debt After a Release). An initiative whose gates passed under 2.1 now sees what 2.2 to 3.0 added.

  • bos.mjs doctor: Node, the hooks next to the script, the project copy, PRODUCT.md, TECH.md, AGENTS.md and its BuilderOS block, each initiative's state and claim, and the debt per phase with its detail. /builder-os:bos-status --doctor relays it.

  • One owner per initiative. bos.mjs claim --by "who" (--release, --take --reason), shown in the briefing and in the per-message line; a second claim is refused. Events claimed, claim_released, claim_taken; a claim older than 14 days is flagged.

  • Rounds are recorded, and the work goes on while one waits. bos.mjs round --asked N and --answered "1B, 2A" --by "who" (events round_asked, round_answered with the hours waited; pace shows the median wait). While a round waits, the agent drafts ahead on the recommended options in blocks marked **Provisional:**, kept apart from **Chosen by:** and from decisions/; the answer keeps or deletes each block (pressure-testing, Working Ahead). Gate E.2, on every gate, fails while a marker is left.

  • agent-design and gate 4.16, when the spec declares model output: autonomy per action (does, proposes, asks, never, with never enforced by withholding the tool), every asks as a tested acceptance criterion, the hand-off, injection surfaces each with a mitigation and a must-pass eval case, degradation for slow, down and wrong, and a latency budget per turn. Gate 6.10 adds **Agent traces:** to production readiness and, after PMF, **Model degradation:** to TECH.md → Operations. logs.query covers model traces. Eval case agent-autonomy.

  • Design craft. design-direction studies three to five real reference screens before drawing, and each version names the generic default it avoids; versions may embed a real typeface instead of system fonts. Gate 4.9 counts the references and checks the Avoids column. The build reviews all six states at two widths (5.9; empty and error at one width on the change track) and gets a fresh-context craft critique of hierarchy, spacing rhythm, typography, copy against the voice, focus states and motion (new gate 5.12).

  • The first day (product track, gate 4.17): a ### First day flow from the first visit to the first useful outcome, and **Activation:** in the spec citing its acceptance criterion and the tracking-plan event that measures it.

  • system-design and gates 4.18 and 4.19: the backend is designed in phase 4, after the domain and the stack. ## Architecture holds the components with what each owns, the contracts (errors, paging), every external call with a timeout, a retry rule, its idempotency and what the user sees when it fails, six scale defaults that cost little now and a rewrite later (owner key on every row, paginated lists, indexed queries, idempotent writes, slow work off the request, reversible migrations) and a capacity at ten times the stage's expected load. ## Threat model names the trust boundaries and always covers another user's or customer's data, untrusted input, abuse and secrets, each mitigation tested by an acceptance criterion. Gate 4.15 states that the scale defaults are not scale work.

  • Security and speed checked on what was built. A fresh-context security review of the diff against the threat model (new gate 5.13: access control, input handling, secrets and configuration, abuse limits, data exposure) and the performance budget measured on the built product, with a page-load row for an interface (new gate 5.14). Gate 5.10 adds static analysis, a token check with an interface, and visual regression once a look has shipped. After PMF, gate 6.10 asks for **Load tested:** in TECH.md → Operations.

  • Interface details (design-direction/references/interface-details.md): tokens enforced in the code, every state of every control, feedback within 100 ms, no layout shift, forms, keyboard, content, state in the URL, motion, themes and Core Web Vitals. The build applies it; the craft critique (5.12) adds interaction states and a row comparing each capture with the reference screens.

  • Flows drawn, and editable by the person (gate 4.20). Each flow in DESIGN.md carries a Mermaid flowchart under its steps table (entries, decisions with labeled exits, success and abandonment), and each lifecycle in the domain model a stateDiagram-v2 holding every state its transitions table names. bos.mjs flows writes design/flows.html, at no model cost: each flowchart on a hand-drawn canvas (Excalidraw, MIT, laid out by its Mermaid importer) where the person drags, adds, joins and renames boxes, turned back into Mermaid as they go; a Text tab with the source beside its drawing (Pele, Mermaid to SVG), parse errors in place, where state diagrams are edited. Libraries pinned on a CDN; offline the text stays editable. bos.mjs flows --apply flows-edited.md writes only the edited blocks back. The Mermaid text stays the record. A warning in lite mode.

  • feature-demo and gate 5.15: a video of the feature working. The end-to-end test walks the primary flow (and the first day on the product track) one asserted step per row of the flow, and the passing run captured with run-check is the one filmed, with captions, at the ICP's width, behind a switch so CI stays fast. Recordings stay out of the codebase: .builderos/media/ is git-ignored, the pull request and the release notes carry the link, and the gate fails a recording git would commit. Ladder: runner video, a recorded host browser, a screenshot per step, the person's screen recording (**Recorded by:**). ui.record joins the capability map; TECH.md gains **Demo:**, the command that records. Phase 6 links the demo in the release notes and shows it before exposure is authorized. Eval case demo-video.

  • production-setup and gate 5.16: a new product goes online in the build's slice zero, behind a password or flag, so the release opens a door instead of attempting a first deploy. TECH.md → ## Environments records production and preview (URL, how each deploys, who can see it), the domain, where secrets live, the authenticated email sender, live keys, the legal pages and cookie consent, and a production check: a captured request to the production host, or the person's tagged observation. Required on the product track; a warning on a product that already runs, whose environments init now writes from its deploy configuration. New capability deploy.run. Eval case going-live.

  • A person tries the build before it is accepted (gate 5.17). TECH.md → Verify gains Run, the one command that starts the product; every change gets a preview link; ## Tried in the build plan names who opened it, when, and what happened to each thing they found. The demo shows the flow works; trying it shows whether it is right.

  • The project on one page. bos.mjs page writes .builderos/index.html: each initiative with its track and phase, what waits on a person (open rounds, failed gates), links to every document, design version, prototype, demo and preview, production and project memory. Generated by the script, so it costs no model tokens; the roadmap regenerates it. /builder-os:bos-status --page.

  • Messages are designed like screens (gate 4.21). DESIGN.md → ## Messages: every email, notification, chat or text message the product sends, with its trigger, recipient, channel, real text, opt-out and a preview file; an agent that talks on a channel gets a row per turn type. **Messages:** none, {reason} when it sends nothing. Gate 5.9 asks for each message as received from the built product (**Messages received:**).

  • Languages and markets. PRODUCT.md → ## Markets holds the languages and countries, drafted at init; copy, dates, numbers and currency follow it, the longest translation is tested on the narrowest screen, and legal pages, messages and help exist in each language.

  • Help with every release. Release notes add **Help:**: where users find answers and what changed there (gate 6.4).

  • What a bet is worth, before choosing it (business-case, gates 3.9 to 3.11). Every option gets a rough two-year value in money; the leading one gets a table where each number has its population, its kind (data, analogy, estimate, decision), its source and three scenarios (P14, P50, P86), the value as profit with costs modeled above 10% of revenue, no false precision, a sensitivity that names the load-bearing assumption, and five questions answered (source, new or moved revenue, denominator, five times smaller, what was killed). Value that resists a number is a declared judgment.

  • A test runs when it can change the decision (gate 3.4 rewritten, 3.12 new). The 20% cost rule is replaced: a test first says which result would flip the bet; building first names why no result could (cheap and reversible, the pessimistic case still proceeds, strong precedent, unreliable measure). A test that runs carries its card before the data: the question as a number, the event, Stop below, Build above set against the second idea, the sample. Kill criteria take two thresholds with an iterate band.

  • The stake (gates 3.14, 3.15): ## Bet size with the door (one-way or two-way), the confidence, the appetite in days the build must fit, and what is lost if wrong; the evidence is held against a bar by stage and door, or the person makes a judgment call knowingly.

  • Go-to-market before and after the build (go-to-market, gates 3.13, 4.22, 6.14, 7.8). Phase 3: the trigger, the motion the price can pay for, the positioning, one channel and its test on the product track; the audience, the message and where they meet it on a feature. Before the build the channel test's result is in the spec, tagged. Phase 6 plans the launch (who hears first, message, channels, date, how each channel is counted); phase 7 reads every channel and, for a product, the GTM stage (Signal, Resonance, Orbit), which PRODUCT.md → ## Business now carries and the product review judges.

Upgrading. Bets fail 3.9 to 3.14 until ## Value, ## Go-to-market and ## Bet size are written, and 3.4 until the test order states its reason; product-track specs fail 4.22 until **Channel result:**; releases fail 6.14 until ## Launch; outcomes fail 7.8 until ## Go-to-market read. Designs fail 4.20 until each flow and lifecycle is drawn; build plans with an interface fail 5.15 until ## Demo is recorded. Specs with model output fail 4.16 until ## Agent behavior is written; product-track specs fail 4.17 until the first day is designed; design directions fail 4.9 until **References:** and the Avoids column are there; build plans fail 5.9 until all six states and **Widths:** are reviewed, 5.12 until ## Craft critique has all eight aspects, 5.13 until ## Security review and 5.14 until ## Performance; specs fail 4.18 and 4.19 until ## Architecture and ## Threat model are written (or declared not applicable with the reason); TECH.md fails 5.10 until the quality checks name static analysis (and a token check with an interface); releases with model output fail 6.10 until **Agent traces:**. Designs fail 4.21 until ## Messages is written or declared none; build plans fail 5.16 on the product track until TECH.md → Environments exists (a warning on the other tracks) and 5.17 until ## Tried and the Run command are there. Gates already passed stay passed and show these as debt. Run bos.mjs vendor once in each project, then bos.mjs doctor.