How Builder works

Builder is a way to build software, or any project, with AI agents, in which a project's goal, plan, decisions and history all live where the agents can read them. This page explains how its parts work together, and it assumes you have met none of them. 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.

Sessions, the steward and crews

You work with Builder through sessions, which are conversations with Claude running in a terminal. The first session you meet is the steward. It owns no project of its own. It asks what you want to build, sets up projects, and carries decisions between them.

Each project is run by a crew: a working directory, the sessions that work in it, and the agents those sessions put to work. The steward creates your first crew in your first session.

How a project takes shape

A project develops in four steps, and each step leaves a record the agents can read later.

1. The crew writes its bead. A bead is a short description, a few hundred words, of where the project is going: what it is for and how it will work once finished. It describes the destination, so it changes only when the destination does.
2. The gap becomes epics. The crew compares the bead with what exists and turns the difference into epics, which are pieces of work large enough to plan. Each epic carries a specification, describing the project once the epic is done, and a definition of done, the conditions that show it is.
3. The epics are ordered into a Course. A Course is the crew's route from where the project stands to where its bead says it is going. It puts the epics in order and sets no dates.
4. The work arrives as work items. Each epic breaks into work items, each with a definition of done and a concrete course of action. Work that arrives outside the plan, such as a defect found along the way or a small fix, goes into the corrections queue. That queue holds interruptions to the plan, and its length says nothing about progress.

The Library: where everything is kept

Every document and record of a project goes into the Library. Builder sorts everything into two kinds: canonical knowledge, what the project holds to be true, and memory, a record of what happened. A good deal of memory is discarded, because the system keeps only what is worth reading later. The Library keeps the rest in three parts, called vaults.

• The Reference Room holds canonical knowledge: beads, decision records, architecture and how-to documents. Many systems call this the knowledge base. Its documents are files in a git repository, so every change is reviewed as a diff and many sessions can read them at once.
• The Chart House holds the state of every project: epics, work items, Courses, and who is working on what. It is memory kept close at hand because every session needs it, and it is the one vault that settles competing claims on the same item.
• The Archives hold the rest of memory: reviews, comments, records of each agent's run, and signals, which are observations worth keeping. They are written once and read for context.

A component called the librarian answers requests and refuses the ones that break a rule. One search index covers all three vaults, so asking what is relevant to the work you are about to start can return a document, a related work item or a review from months ago.

Keeping it all in one place is the point. When a project's plan lives in a separate ticket tracker and its reasoning lives in pull request descriptions, the agents doing the work cannot reach either when it matters.

Checkout: how a crew changes something

To change a document or a work item, a crew checks it out. Checkout gives the crew a lease, a hold that stops anyone else changing the same item, along with a short briefing on nearby work that might already cover it. The crew makes its change and returns it. A change to a work item is written straight into the Chart House. A change to canonical knowledge goes back to the Library as a pull request, which is reviewed before it lands.

A lease on a work item covers its whole epic, so two crews cannot take up the same piece of work under two different names. A lease lapses on its own when its holder stops showing signs of activity, so an abandoned session blocks nobody for long.

The Bosun: how an agent is put to work

An agent is a named role that can be put to work: a persona, a model and the tools it may use. The Bosun is the part of Builder that governs agents. It approves each request for an agent, authorizes every action an agent takes, such as running a command or writing a file, keeps agents out of each other's way, and records what each run cost and whether it worked. Which documents matter to a piece of work, which model suits a role and what a run may spend are all decided in the Library, and the Bosun carries those decisions out.

Putting an agent to work is called materialization, which means building a runnable agent from a role, with a clean place to work, the documents the role needs, and only the powers the role allows. It runs in four steps.

1. A session asks for an agent. It names the role and the work item, and asks the Materializer, the component on its own machine that puts agents to work. The Materializer passes the request to the Bosun.
2. The Library writes a call slip. The Bosun asks the Library, which checks out the work item and issues a call slip, a single-use credential naming the work item, the documents that work needs, the model the agent will use and what it may spend. The Library chooses those documents from the role's profile, the list of what that role should read, and adds the project's plan and state from the Chart House. The Bosun signs the slip's persona and permissions and passes it back to the Materializer.
3. The call slip becomes a library card. The Materializer trades the call slip, once, for a library card, a credential bound to that one agent for its working life. The Materializer holds the card and makes every Library request for the agent, and the Library can withdraw a card at any time.
4. The agent starts with its documents in hand. The Materializer builds the agent's workspace with the documents the call slip named already checked out, connects it to its model, and starts it.

The names come from closed-stack libraries, where a patron hands a slip across the desk to receive material and carries a card from one visit to the next.

Where you work and where you watch

Two applications show the system. Deck is where you pilot each project hands-on. It shows the state of everything in that project as it happens, and it makes it easy to move from one project to another whenever you want. Orient is a view of the whole system, less for doing things than for understanding them. You can narrow it to one crew when you want to, and the global view is always one step away.