A framework for building with people and AI agents

Holon-Driven Development

Every system is a tree of holons. Each holon has a manager who builds it and keeps it working.

I · Preface

Coding agents changed how software gets built. One person can now run many AI agents at once, and each of them writes code faster than anyone can review it.

The methods we use were made for teams of five to ten engineers. Scrum, code review, and design documents assume that people write the code and people hold the context. When I started building with AI agents, I kept losing the picture of my own system. Over many sessions the code and the documents drifted apart, and the AI agents bent the code around decisions that were already wrong.

The following architecture has been thought through and designed carefully to support modern development, with AI agents working alongside people. Nothing here is invented from scratch. It blends the best practices of existing methodologies into one model.

II · Overview

Holon-driven development is a mental model for building and running a product with people and AI agents without losing the picture of the whole. You draw the product as a tree of responsibilities. The product splits into parts, and each part splits into smaller parts, down to the smallest piece of work. Each part is called a holon. It is whole on its own and it is part of something bigger.

A holon is more than a box on a map. Each one carries:

Purpose
Why it exists.
In and out
What it takes in and what it gives back.
Relationships
Its parent, its children, and the holons it connects to.
Manager
The person or AI agent who builds it and keeps it working.
Context
Its rules, decisions, and tests, plus everything it inherits from the holons above.
State
Plan, build, or operate, and what is happening below it.

Because each holon carries all of this, its manager needs only that holon and the ones above it to do the work right. Nobody has to hold the whole system in their head. Managers build in parallel. When something is unclear or looks wrong, they ask the holon above instead of bending the work to fit. Anyone can still understand the whole product by opening the tree from the top.

A product as a map of responsibilities, then as layers A house sits in the middle. It splits into a kitchen and a bedroom. The kitchen holds a sink and a stove, and the bedroom holds a bed and a closet. You manage the house, a builder manages the kitchen, and an AI agent manages the bedroom. Then the map folds into three stacked layers: the house on the bottom, the rooms in the middle, and the things in each room on top.
A house drawn as a map. It splits into parts, each part gets a manager and runs its own loop. Then the map stacks into layers, one for each level.
III

The holon

Arthur Koestler coined the word in 1967, in The Ghost in the Machine. A holon is whole when you look into it and a part when you look out from it. A cell is whole, and it is part of an organ. An organ is whole, and it is part of a body. Koestler called these the two faces of a holon.

In a system we build, a holon is any part that carries its own responsibility: the product, an app, a service, a module, a single function. Each one does its own work, takes in what it needs, and gives its parent what the parent needs.

Plate I. Anatomy of a holon A circle, the holon, holds three smaller circles, its children. An arrow brings input in from the left and another carries output out to the right. From above, context comes down from the parent, and reports and questions go back up. Around the holon runs a ring with three states: plan, build, and operate, each with a small loop of its own. Dashed arrows inside the ring lead back: to build when the work is wrong, to plan when the definition is wrong. child child child back to build: the work is wrong back to plan: the definition is wrong PLAN define · ask · revise BUILD build · test · fix OPERATE run · observe · respond what goes in what comes out context goes down reports and questions go up TO THE PARENT one holon
PLATE IAnatomy of a holon. It takes something in and gives something out. Context arrives from its parent, and reports and questions go back up. Around it are its states: plan, build, and operate. Each state runs its own loop, and work goes back a state when something is wrong.
IV

The tree

Holons nest, so every system forms a tree. It is read from the product at the top down to the smallest part that does real work. You can stop at any level and still have a complete holon.

Plate II. One tree, two drawings On the left a tree: one holon at the top, three below it, and five below those. On the right the same holons drawn as circles within circles. The two drawings show the same system. READ AS A TREE = READ AS HOLONS WITHIN HOLONS
PLATE IIOne system, drawn two ways. Each branch of the tree is a holon, and each holon holds the branches below it.

The tree describes responsibility. It does not try to draw every wire. When two holons use the same code, that code can become a holon of its own. It fits best under the nearest parent of the holons that use it.

An architect draws the tree, and there is no single correct tree. A good place to split is a line of responsibility. Ask who answers when this part is wrong. When two parts have different answers, they are usually two holons.

Technology, runtime, triggers, teams, and tenants usually describe a holon rather than split it. A thin holon helps when parts of one responsibility need different states. An iOS release can wait in review while the Android release ships.

A part becomes a holon when someone needs it to understand how the system works.

V

What a holon holds

A holon holds whatever is needed to build it and keep it running. A parent's requirements bind all of its children.

Purpose
Why it exists, in a sentence its parent would agree with.
In and out
What it takes in and what it gives back.
Lives in
The repos and folders that hold its code and infrastructure.
Runs on
Where it runs, like a scheduled cloud job or a phone.
Entry points
What starts it, like a schedule, an API call, or a tap.
Reads and writes
The data it uses and the data it changes.
Requirements
What it must satisfy. Inherited by every holon inside it.
Rules
Conventions and constraints for the work done inside it.
Procedures
The steps it carries out, in order.
Decisions
Questions already answered, kept where they apply.
Tickets
Work still to be done.
Tests
Proof that it does what its definition says.

The list is open. Add whatever your holons need.

A tree is easier to trust when every file belongs to one holon and every data store has one holon that writes to it. Then a script can check that the tree still matches the system.

Holons connect through their in and out, and both sides define the link so either side can test it. A flow through several holons, like a data pipeline, fits best with the nearest parent that holds all of its steps. The parent decides the order and the rules between steps. If a holon needs to know about its sibling, the work it holds probably belongs to its parent.

VI

The manager and the states

Every holon has a manager: the one responsible for it. The manager plans it, builds it, runs it, and watches it. A manager can be a person or an AI agent. Both act on the holon, so both are agents in this sense.

The manager can change over time. A person may plan a holon and then hand it to an AI agent that builds it and keeps it running. The holon keeps its context through the handover, so the next manager starts where the last one stopped.

Holon-driven development does not decide who manages what. You decide, holon by holon. Today a founder may manage the product while AI agents manage single functions.

The manager delegates each child to its own manager and reports to the manager of the parent. It works like a team. When a manager needs a decision that its context does not answer, it asks the manager of the parent, the way an engineer asks their tech lead. An AI agent running a holon does the same and asks the person or AI agent above it. This happens most in Plan. A decision that changes the purpose can travel all the way up to the top of the tree. The answer is recorded on the holon where it was made, so every holon below it inherits it.

Every holon is in one state at a time. By default there are three, and each runs a loop of its own.

  1. Plan. Define the holon, ask the parent's manager what is unclear, and revise until it can be built.
  2. Build. Build, test, fix, and test again until the tests pass.
  3. Operate. Run, observe, and respond to what happens.

Work moves back when it has to. Back to Build means the work is wrong and the definition still holds. Back to Plan means the definition is wrong, or what the holon should do has changed. A holon can keep operating while one of its children is back in Plan.

A holon's state is its own. It never comes from its children. A parent that is live stays in Operate while a new child is planned or built, and it reports which parts below it are in other states, so its manager always knows what is live. The parent goes back to Plan only when what it promises its own parent changes.

The three states are a default. Each holon defines its own states to match how its work is done. One may add Review between Build and Operate. Another may end with Retire.

VII

Context goes down, questions go up

A manager works with the context of its own holon and of every holon above it. It does not need its siblings. The holons above it already carry the purpose, the requirements, and the rules.

When a manager meets something its context does not answer, or a decision that looks wrong, it first answers what it can inside its own holon. If the question is bigger than the holon, it goes to the manager of the parent, and further up if the parent cannot answer it either. The manager does not change the work just to make a check pass. It moves the holon back to Plan and waits for the answer.

The answer is recorded on the holon where it was decided. From there it flows down as context to every holon below it, so a sibling that meets the same question later already has the answer.

Plate III. The context of one function A tree from the product down to one function. The path from the product to that function is drawn in ink: the product, a container, a component, a module, the function. Every other branch is faint and marked as outside its context. A dashed red arrow shows a question going up from the function to its module. the product a container a component a module the function the context of the function a question goes up outside its context INK: WHAT IT READS · FAINT: WHAT IT CAN SKIP
PLATE IIIThe context of one function. Its manager reads the holons above it and can skip everything else.
VIII

Define, then build

AI agents make building cheap. You can delete a holon and rebuild it in hours. What costs time is an open question that nobody answered before the work started.

So define the tree first, as deep as you can see. Once a holon is defined, its children can be built in parallel, each by its own manager. If one child needs another to run, write that in the definition. Change the tree whenever the work teaches you something.

IX

Reading the whole

Anyone can understand the system by reading its tree. Open the product and see its parts. Open a part and see its parts, down to a single function and what it touches. You don't need to read every line to know how it works.

Where the tools allow, the folders can follow the tree, with a holon file at each folder's root.

The holon comes from Koestler. What this adds is a manager and a loop of states at every holon. Older methods were made for teams of people. Now AI agents build next to people, and every holon needs someone who keeps it working.

X

Beyond software

The model does not depend on code. A building is a tree of floors, rooms, and systems. A city is a tree of districts, streets, and services. Anywhere many people and AI agents build one thing together, the same tree works.

XI

An example

Use case: A house

Use case: A social app

Here is the same idea for an engineer. It is a small social app where people write posts, follow each other, and read a feed. The product splits into containers, the parts that run on their own: a mobile app, a web app, an API and a worker. Inside each container, components are cut by responsibility, then modules, then functions. Each part has someone responsible for it.

Here is one project drawn as a tree. It is a house being renovated. The house splits into rooms, each room holds things, and each thing breaks into jobs and tasks. Each part has someone responsible for it.

Plate IV. A house The house is drawn as a large circle holding four rooms. The kitchen, in Build and managed by a builder, holds the sink, the stove back in Plan, and the cabinets in Build. The bedroom, managed by an AI agent, holds the bed, the closet in Build, and the lighting. The bathroom, managed by a plumber, holds the shower and the toilet. The garden, managed by a gardener, holds the lawn and the fence. Suppliers lie outside the house. HOUSE you · renovated one room at a time KITCHENa builder · buildSinkStoveplanCabinetsbuild BEDROOMan AI agentBedClosetbuildLighting BATHROOMa plumberShowerToilet GARDENa gardenerLawnFence suppliers INK: HOLONS · RED: STATES AND WHAT LIES OUTSIDE
PLATE IVA house, drawn as holons within holons. The house holds four rooms, and each room holds its things. A holon drawn in red is in a state other than Operate. The pen on each ring is that holon running its own loop, faster while it is being built.
Plate IV. A social app The product is drawn as a large circle holding four containers. The mobile app, in Build and managed by an engineer, holds the composer in Build, the feed screen and the profile screen. The web app, managed by an AI agent, holds pages and sign-in. The API, in Build and managed by an engineer, holds posting in Build, media back in Plan, feed and accounts. The worker, managed by an AI agent, holds feed updates and notifications. The push service lies outside the product. SOCIAL APP you · a small team with AI agents MOBILE APPan engineer · buildComposerbuildFeed screenProfile screen WEB APPan AI agentPagesSign-in APIan engineer · buildPostingbuildMediaplanFeedAccounts WORKERan AI agentFeed updatesNotifications push service INK: HOLONS · RED: STATES AND WHAT LIES OUTSIDE
PLATE IVA social app, drawn as holons within holons. The product holds four containers, the parts that run on their own. Each container holds components cut by responsibility. A holon drawn in red is in a state other than Operate. The pen on each ring is that holon running its own loop, faster while it is being built.

The layers in the house follow the work. A home holds rooms, a room holds items, and each item breaks into the jobs and tasks it takes to build it and keep it running. That is already how people run a house: the plumber looks after the sink, and the sink is a list of jobs.

Plate V builds the house from the ground up. The house is the base, and each holon you select opens its parts on the layer above, down to a single task.

The layers in software follow the code. A product holds containers that run on their own, a container holds components, a component holds modules, and a module holds functions. The work to build and run each part sits with its manager, so the tree keeps the same shape as the code.

Plate V builds the app from the ground up. The product is the base, and each holon you select opens its parts on the layer above, down to a single function.

I · HomeII · RoomIII · ItemIV · JobV · Task

PLATE VThe house, built from the ground up. The house is the bottom layer. Select a holon to open the layer above it. Drag sideways to turn the layers. Play the state loop to watch the stove go around Plan, Build and Operate.
PLATE VThe app, built from the ground up. The product is the bottom layer. Select a holon to open the layer above it. Drag sideways to turn the layers. Play the state loop to watch Media go around Plan, Build and Operate.

Each part answers for one thing. When the sink leaks, you open the sink, and the plumber who manages it fixes it. Nobody has to search the whole house.

Each part also moves on its own. The kitchen is being rebuilt while the family still sleeps in the bedroom. The stove is back in Plan because the family switched from gas to electric, and that decision flows down to every job under it.

Each part answers for one thing. When a post shows up twice in the feed, you open the API, then Feed, then Timeline, and the AI agent that manages it fixes the query. Nobody has to read the whole codebase to find it.

Each part also moves on its own. The API and the mobile app are in Build for image posts while the web app and the worker keep running. Media is back in Plan. The AI agent building storeImage asked where images should live, and the question went up to the engineer on Media. The answer was to move images out of the database and into object storage. It is recorded on Media and flows down to every module and function under it.

Some work crosses holons. Publishing a post starts in the mobile app, goes through the API, and ends in the worker, so that flow belongs to the product, the nearest parent of all three. The database works the same way. The API and the worker both use it, so it sits with the product until someone separate answers for it. Then it becomes its own container.

The tree leans on methods that already work. The levels come from Simon Brown's C4 model. A container is something that runs on its own, like an app, a service or a worker. Each one has a manager, and inside it the cut is by responsibility.

The cut by responsibility comes from Parnas's paper on splitting systems into modules (1972), Wirfs-Brock's responsibility-driven design (1989), and Martin's single responsibility principle (2017). Specifications and tests give each holon its definition and its check. Decision records give it a memory.