Inside the
software factory.

You have an idea, project X really needs feature Y

You are using a tool you built and think, “This needs a --dark-mode flag.” The programmer in you wants to switch tasks, fire up an agent, and get it done. But, this will be a distraction that will surely open up other distractions, ad infinitum. Here’s another way. The Yesod way. Tell your coding harness: new feature request: add a --dark-mode flag to my spline reticulator CLI.

Your coding harness has the Yesod skill loaded, so it knows that a registered tool can accept a feature request:

yesod tool <tool-name> feature-request "Add a --dark-mode flag"

You do not have to leave the work you are doing and follow the idea down a rabbit hole. Intake records it in the place you trust the factory to revisit.

An agent finds a bug - what to do?

An agent is running a process that uses several of your tools. This time reticulate-splines stops with ERROR: no-splines. The harness knows that when a Yesod tool should work and does not, it can capture a bug report:

yesod tool reticulate-splines bug-report "we were trying to reticulate the splines of a city with no trains and got ERROR: no-splines"

The agent can add all kinds of data, like how to reproduce the bug, the error message, anything it thinks will be helpful. The Yesod agent skill lets coding harnesses know that they can do this. This way, every execution of your tools, successful or not, becomes an opportunity for improvement.

A Trusted Capture System

The captured feature request or bug report is called a Yesod note. The main idea of a note is that it gets captured and it holds the idea. Later, you can have a brainstorming session with your agent and flesh out the details. The important thing is that both you and your agents know that notes are associated with your tools and can be captured. That trusted capture is partly inspired by David Allen’s GTD method: get the thought out of your head and into a system you know you will return to.

Adding --auto-plan authorizes the factory to continue beyond capture and see the idea through until it is completed or explicitly blocked.

Station 1: Planning Agent

The planner starts with the note and the actual tool or repository behind it. It inspects the source, resolves important ambiguity, defines the intended outcome, and writes acceptance criteria that another agent can act on.

The plan becomes a root Bead with child Beads. Dependencies between the beads guide the executing agents in implementing the feature. Having a tree of beads guide the work enables less-powerful (and less expensive) models to complete the tasks without spending excessively on tokens. Planning agents are ephemeral in nature, but may exist for planning several related features.

Beads express an execution plan within a feature. You can also express dependencies between notes. For example, “add dark-mode theme” depends on “add theme support.”

Station 2: Complexity Estimator

Complexity estimation happens after the work has shape. The estimator records Easy, Medium, or Advanced. Factors that influence complexity include the number of files to be touched and whether the change affects security or external services (e.g., AWS). The estimate informs model choice; the dispatcher makes the selection. Complexity estimation is not an exact science, and is an area of active research for Yesod.

Resources

• Beads

The dispatcher is where everything comes together. This is what feeds the LLMs. The dispatcher sends grounded Yesod notes to runners, which start a coding harness + model specially prompted to follow the plan as described in the beads.

Because runner agents are not worried about testing, deployment, or anything else, they can stay singularly focused on delivering the requested outcome. It is this singular focus and guidance from the beads that allows simpler models to punch above their weight here.

The runners do their work in an isolated environment and work to execute the plan. At the end of a code-related task, the result is a merge request.

The refinery is the final step in the process. It is the natural bottleneck in the system. It is straightforward to launch a bunch of parallel feature developments, but eventually they need to all end up as coherent parts of the same codebase.

The name ‘refinery’ is borrowed from GasTown, but I think it is a perfect name. The implemented features are ‘raw materials’, and the refinery is taking those raw materials and assembling the final product. The refinery starts with deterministic Git merge preparation.

When that preparation finds a merge conflict, the refinery can dispatch one bounded AI-powered repair agent to resolve the recorded conflicts. The repair agent cannot approve or merge the work. Its repaired branch must re-enter the refinery and pass the complete deterministic microVM test gate.

This is the end of the line for the factory—a completed piece of work. As a coding factory, this might be a merged commit. Or, configure it to run the tests and send a verified merge request.

For another factory, it might be documentation, research, analysis, configuration, data, an operational change, or a decision. Those are examples, not limits.

The important thing is that the factory produces a piece of work. This work is true to the original intent set out in the Yesod note, and the evidence trail remains attached.