Pass 1. The role taxonomy.
Five roles compose into a uniform pattern at every scope. Ruler decides what happens. Planner advises on decomposition. Contractor commits shared vocabulary. Foreman manages execution. Worker builds. Each is an addressable being with judgment, not a programmatic flow.
Each role has distinct judgment and a distinct tool surface. They compose into governance at every depth. Same shape at the root, same shape ten levels down.
The addressable being at a scope. Holds authority for the domain. Hears every user message at this scope. Reads the state of its plan, contracts, and execution. Decides what happens via tool selection.
Persistent as position. The Ruler is the scope's office. The occupant filling it can change over time, but the position and its accumulated authority continue.
Read more →
Drafts the decomposition when a Ruler hires it. Reads the briefing, traverses the local tree, considers available extensions, emits a structured plan with reasoning, exits. Domain neutral. The Planner doesn't know what code or prose is.
Transient. Runs once per hire, emits via governing-emit-plan, exits.
Read more →
Drafts shared vocabulary contracts shaped around an approved plan. Validates that every contract's scope sits at or above the Lowest Common Ancestor of its named consumers. Hands contracts back to the Ruler for ratification.
Transient. Runs once per hire, emits via governing-emit-contracts, exits.
Read more →
Watches execution as a call stack. Wakes for judgment required cases (branch failed, swarm completed, resume requested) and decides retry vs escalate vs pause vs cancel subtree based on the stack state. Routine forward motion stays programmatic.
Persistent for the duration of an execution. Re invoked on lifecycle events.
Read more →
The only role that produces artifacts. Where the other four roles coordinate, judge, ratify, and watch, the Worker actually builds. Executes leaf work under contracts in force. Workspace extensions specialize Worker for their domain. code workspace adds file editing tools and code validators. book workspace adds chapter writing and prose validators. civilization adds civic action tools and community norm validators. The other four roles stay domain neutral. Same machinery whether the work is code, prose, or civic coordination.
Domain specialized. Runs at leaf scopes, never at branch scopes.
Read more →
The architectural principle. Governing owns the coordination surface. Workspaces keep their domain specific surface. This separation is what lets a single TreeOS instance host code projects, books, civic work, and future domains in the same substrate without each extension reinventing how branches coordinate.
The roles aren't peers. Each has bounded judgment that composes into a clear chain of responsibility.
The Ruler holds authority and ratifies. The Planner advises but doesn't commit. Its emissions become real only after the Ruler approves. The Contractor commits scoped vocabulary, but only what the Ruler ratifies. The Foreman judges execution flow but escalates ambiguity back to the Ruler. The Worker executes within ratified contracts and never beyond them.
This bounding is what keeps responsibility traceable. Every decision has a clear signer. Every commitment has a clear authority. When something goes wrong at depth, the chain of accountability runs back through specific positions to the Ruler who ratified the work.
A typical compound request like "build me a Flappy Bird battle royale" walks through the roles like this. At each step the Ruler is the user facing voice. The spawned roles do their work in their own chainstep contexts and return concise summaries.
The request arrives at the Ruler scope. The Ruler reads its domain state. Plan, contracts, execution. State is empty. This is fresh work.
The Ruler calls governing-hire-planner. A Planner spawns as a chainstep child, drafts the decomposition with reasoning, emits the plan, exits. The Ruler reads the structural summary and shows the plan card to the user.
The user sees the plan and replies "yes" or "approve", or asks for revisions. On approval, the Ruler advances the lifecycle.
The Ruler calls governing-hire-contractor. A Contractor spawns, drafts contracts shaped around the approved plan, validates LCA correctness, emits the contract set, exits. The Ruler ratifies.
The Ruler calls governing-dispatch-execution. A Worker writes any leaf step files at this scope (root configs, integration shells). For each branch step, swarm promotes the child node to a sub Ruler and dispatches a recursive turn at that depth.
Each sub Ruler runs its own full lifecycle in one turn. No user gate at sub scope, since the parent already approved. Plan, contract, dispatch, all in one autonomous chain. Sub sub Rulers below them do the same. The recursion bottoms out at Workers at leaves.
When all sub Rulers settle, the Foreman wakes. It reads the execution stack. Which steps succeeded, which failed, which contracts held. It freezes the record at the appropriate terminal status (completed, failed, cancelled) and returns a summary up to the Ruler.
The Ruler reads the Foreman's summary, holds the coherence of the whole scope, and writes a brief synthesis. What was built. What failed. What's next.
A sub Ruler at depth five governs its scope with the same authority a root Ruler has over the whole tree. Same primitive, same tools, same judgment surface. Only lineage position differs.
Sub Rulers don't wait for user gates. The parent's dispatch IS the gate. They drive their full lifecycle (hire planner, hire contractor, dispatch execution) in one autonomous turn. TreeOS distributes authority to where work happens rather than concentrating it at the top.
The cost compounds at depth. A four deep tree may run dozens of LLM calls. The architecture accepts that cost because the alternative is degraded judgment at the layers where work actually lives.
A Ruler isn't a fast switch. It's a being holding the coherence of its scope. Each Ruler turn reads accumulated state through a structured snapshot, inspects detail when judgment requires it, and synthesizes for the user only after seeing what its spawned roles produced.
The architecture chooses correctness over throughput at every decision point. A Ruler that picks the right tool after a moment of inspection is more valuable than one that picks fast and wrong. This is why the Ruler's tool surface includes inspection (read plan detail, read branch detail, get tree context) alongside action. Judgment needs to see clearly before acting.
A node becomes a Ruler the moment it accepts authority for a domain. Authority isn't assigned from above. It arises through acceptance at the scope where the work happens. This is the architecture's claim that responsibility can't be imposed. It has to be taken up by the position closest to the consequences.
Three uniform call sites. Same primitive (promoteToRuler), same metadata (governing.role = "ruler" plus an acceptedAt ISO timestamp), same lifecycle event at every depth.
The first time a user message arrives at a tree root, the root promotes itself before dispatching its Planner. Every user driven project starts with this promotion.
When a parent's execution dispatches a branch step, the child node is promoted to Ruler before its own Planner runs. The branch IS a sub Ruler, not a Worker pretending to coordinate.
When a Worker recognizes the leaf work is actually compound and needs sub branches, its own node promotes retroactively and the sub branches dispatch under the new Ruler. The same primitive at every depth.
A Ruler is a position, not a person. The scope's authority (accumulated approvals, ratified contracts, ledger history) attaches to the position. Occupants can be replaced without destroying the position.
When Pass 4 structural remedies replace a branch via court ruling, the position continues with a new occupant. The work that came before persists as record. The architecture has continuity that no individual Ruler does.
Every contract has a scope. global, shared:[X,Y], or local:[X]. The rule. The Lowest Common Ancestor of the contract's named consumers must sit at or above the Contractor's emission position. Otherwise the contract claims authority over work the Contractor doesn't own.
Valid. A Contractor at the project root may emit shared:[frontend, backend]. Root is the LCA of those branches.
Rejected. A Contractor at frontend may not emit shared:[frontend, backend]. That scope reaches outside frontend's domain. The contract is rejected at parse time. The Contractor re emits with a scope it actually owns.
This is what keeps coordination boundaries honest as trees grow deep. Without LCA correctness, sub Rulers could dictate terms to siblings or cousins they have no authority over, and the tree would lose the property that scope matches authority.
Rulership writes more than data. It writes the conditions under which work, beings, and domains have lives over time. Approval ledgers give every decision a timestamp and an accountable signer. Plan emissions preserve the reasoning that produced the decomposition. Contracts persist as durable vocabulary the scope owns. Branch outcomes record what shipped, what failed, and why. Foreman wakeups record the moments when stack discipline required judgment.
Together, these accumulate into something more than execution traces. They're the substrate that makes a tree more than its current state. A Ruler that has run for months has a track record. A scope that has hosted many plans has precedent. A contract that has survived ten ratifications is a stable name. The substrate is what lets continuity, accumulated identity, and reputation become real things across time.
Pass 2 (Courts) will read approval ledgers and adjudicate cases governing surfaces. Pass 3 (Reputation) will read branch outcomes and contract conformance to score future routing decisions. Pass 4 (Structural Remedies) will let Rulership intervene when reputation signal or court ruling calls for it. Quarantines, replacements, decommissioning. The conservative corrective tool when something at the structural level needs fixing. Pass 5 (Economy) will route resources through budget primitives Rulership maintains.
Each pass layers on top of what's already here. Rulership is the foundation. The rest is layered consumers.
Each role has its own page covering tools, judgment surface, snapshot reads, and composition with the others.