Why Builder

This page makes the case for Builder to someone who has never seen it. Like a bead, it describes Builder as it is designed to work. Each term is explained where it first appears, and the glossary lists them all.

Two complaints you have probably made

If you have built anything with an AI model, you have seen it go wrong in ways that are hard to pin down. It states something false with complete confidence. It forgets a decision you made an hour ago and argues you out of it again. It fixes one thing, breaks another, and then undoes its own fix, going around in circles. It tells you the work is done when it is not. People conclude that the models are unreliable and that they hallucinate.

If you have worked on a team, you have probably made the other complaint too. The ticket tracker is confusing, it takes longer to update than the work takes to do, and the reason behind anything sits three links away, when anyone wrote it down at all.

They are one problem

Builder treats those two complaints as one problem: the context a piece of work needs lives somewhere the worker cannot reach.

A model does good work when it has the right context at the moment it works: what the project is for, what has been decided and why, what was tried and failed, and what counts as done. When that context is missing, the model fills the gap with a plausible guess, and much of what gets called hallucination is that. When the model never saw a decision, it reopens it, and that is what going in circles looks like from the outside.

The tools most teams use scatter that context. The plan lives in a ticket tracker, the reasoning behind a change lives in a pull request description, and the decision lives in a chat thread. All of it was written down, and none of it is where a model can retrieve it when it matters. People pay for the same scatter in their own way, in time spent hunting for things and in decisions that get made twice.

Everything is memory, except canonical knowledge

Builder rests on one idea: everything is memory, except canonical knowledge, and memory is where all project structure happens.

Canonical knowledge is what your project holds to be true: its goal, its decisions, how it is built and how to work on it. Everything else is memory, a record of something that happened, whether that is a plan, a work item, a review, a conversation or an attempt that failed.

Builder routes all of it by one rule.

• Canonical knowledge goes to the Reference Room, which many systems call the knowledge base. Every change there is reviewed before it lands.
• Most memory goes to the Archives, written once and searchable from then on.
• A good deal of memory is discarded. A system that kept everything would bury what matters under what does not, so deciding what to forget is part of the design.
• Memory that every session needs all the time goes into a store kept close at hand. The first is the Chart House, which holds each project's plan and the state of its work. When another kind of memory turns out to be needed constantly, it gets a store of its own.

The consequence is the point. A project's plan, its work items and who is working on what are all memory, kept in the same system as everything else, where every agent can reach them.

Why the plan has to live inside the system

A plan kept outside the system is a plan the models do not have. A work item in a separate tracker cannot change what an agent does, because the agent cannot see it at the moment it would matter. In the Chart House, the same work item is available to every agent whenever it turns out to be relevant.

So when Builder puts an agent to work on a task, it hands the agent what that task needs: the work item, what counts as done, the decisions that bear on it and the history worth knowing, and little else. Narrow, specific context is what makes a model effective. It also makes the model cheaper to run, because an agent handed what it needs spends nothing looking for it.

What it is like to work this way

A project starts from where it is going. Before anything is built, a project writes down its destination in a few hundred words, called its bead, and every piece of work is measured against it.

Decisions stay made. A decision is recorded as canonical knowledge, and agents read it before they act, so nobody argues the same point twice, the agents included.

You can see everything in flight. Builder shows you what you are working on. Work on one thing and that is what you see. Start five and you see all five, which is as messy as it sounds, and it is how you notice you have stopped finishing things.

Work is checked before it is reported. Every change is reviewed before it lands, and an agent reports the check it ran along with what the check returned.

You learn it by using it. Your first session is with the steward, which asks what you want to build and gets the smallest real version of it running with you. It explains the system when a question comes up, in the middle of the work that raised it.

It has opinions. Builder's way of working comes from building real products with it, so you start with the results of that trial and error instead of paying for it yourself.

Who it is for

Builder is for builders. Software is the leading case, and engineers are the readers best placed to judge whether these claims hold, so please judge them. It is equally for someone who has never written a program and builds tools for their own work.

What is at stake for both is the same. Many people feel precarious about what their work becomes when a model can do much of it. We think the people who do well will be the ones who get good at directing that work, and directing it well takes tools built around what a model needs.

Where the field is

There are plenty of ideas about building with AI, and less progress than the ideas suggest. Most environments for agent-driven development still look like code editors with a chat panel, and the ones aimed at people who do not write code look like note-taking apps. Builder is arranged around two needs instead: the model's need for context at the moment it works, and the person's need to know where the work stands. We would rather it moved the field toward that than won a category.

What we are sure of

Some of this will not survive contact with the world. We are confident in the direction: context belongs where the work can reach it, and project structure is memory. We are less sure of every part built on that, and Builder will change as people use it.