Computation from routing
A handler computes values. Ordered dispatch predicates inspect the result. Edges select the next cell. Branching policy is visible in the manifest instead of being buried inside an implementation.
Clojure · contracts · agent-sized code
Architect the graph.Delegate the cells.
Mycelium is an architectural answer to context rot. It makes the application's high-level control flow explicit, wraps each unit in an executable data contract, and gives a coding agent a task small enough to understand without reading the whole system.
inputrequest
cell 01validate
in → outcell 02process
in → outterminalresponse
cell 03fallback
error → replyOur reading
Mycelium's real unit of leverage is not the small function. It is the enforced boundary between small functions.
Ordinary modular code can still hide its application logic inside a call graph. Mycelium moves that routing into data. A workflow manifest names cells, edges, branches, joins, timeouts, and schemas. The cell performs work; the graph decides what happens next.
That inversion gives an agent a fixed local contract while the compiler retains the global topology. It is a promising answer to one class of agent failure: locally plausible code that connects incorrectly.
01 / Mechanism
One state map. Two separations. Three layers of checks.
Mycelium sits on Dmitri Sotnikov's Maestro state-machine library and uses Malli for data contracts. Cells receive resources plus workflow data. They return new data. They do not call one another.
Workflow data from resources
The accumulating map carries domain state. Databases, clients, and other capabilities arrive through a separate resources argument. This improves isolation, but cells may still perform I/O and effects.
Schema plus topology
Input and output schemas constrain each cell. Graph validation checks whether required keys can reach downstream cells along every declared path. Runtime validation checks actual values.
(cell/defcell :order/compute-tax
{:doc "Compute regional tax"
:input {:subtotal :double}
:output {:tax :double}
:requires [:tax-rates]}
(fn [{:keys [tax-rates]} data]
{:tax (tax-for tax-rates (:subtotal data))})){:cells {:start :order/validate
:tax :order/compute-tax
:error :order/render-error}
:edges {:start {:valid :tax
:default :error}
:tax :end
:error :end}}Cell exists
Every graph node resolves to a registered implementation.
Route exists
Every transition points to a cell or an explicit terminal state.
Route is reachable
Dead cells and stranded paths fail validation.
Dispatch is complete
Every labelled edge has a matching ordered predicate.
Data is available
Required input keys must be produced earlier on that path.
Output conforms
Malli validates the value a cell produces at runtime.
02 / Agent workflow
The manifest is persistent context. The brief is a projection.
Mycelium can turn one cell definition into a self-contained prompt with purpose, schemas, resource requirements, example values, outgoing transitions, and implementation rules.
- 1Architect
A human or senior agent defines the workflow, boundaries, schemas, routes, and error policy.
- 2Project
cell-briefextracts one bounded implementation contract from the manifest. - 3Implement
A worker writes one handler without importing or calling another cell.
- 4Reject
Cell tests and Malli return precise input or output failures to the worker.
- 5Compose
The workflow compiler checks the whole graph, then end-to-end tests check domain behavior.
03 / Pocock × Mycelium × Chen
Three graphs, three kinds of truth.
Mycelium fits naturally between planning and execution, but the three systems should not be collapsed into one universal graph. Each exists at a different layer and changes on a different clock.
Wayfinder
What must we decide before this work is knowable?
question → evidence → decisionMycelium
What can the application receive, produce, and do next?
schema → cell → transitionFirstMate
Which implementation slice is ready, owned, reviewed, and shipped?
brief → worker → evidenceWhat does the graph represent?
Decisions and dependencies in an uncertain project.
The control flow and data contracts of the running application.
Work items, workers, claims, status, and delivery state.
Who owns the hard judgment?
The human resolves what the product should mean.
The architect chooses boundaries, routes, schemas, and invariants.
The liaison decides what can be delegated and what returns to the human.
What can an agent safely do?
Research or prototype one visible frontier question.
Implement and test one cell from a generated contract brief.
Execute one claimed slice in an isolated workspace.
What is authoritative?
Canonical Markdown decision files and their dependency links.
The workflow manifest, registered cell contracts, and tests.
Backlog, brief, runtime metadata, live inventory, and delivery evidence.
Combined workflow
Resolve the meaning. Contract the program. Govern the delivery.
Wayfinder can settle the architecture and product decisions. Mycelium can turn the approved application flow into cells and contracts. FirstMate can distribute those cell-sized or vertical implementation slices through isolated workers and a guarded review path. Pass stable references between layers. Do not duplicate their state.
04 / Evidence
A convincing demonstration, not yet a general result.
We inspected source at commit df45132 and ran the project suite on 31 July 2026. The framework's validators and tests substantiate the mechanism. The comparative benchmark needs a narrower reading.
Project suite560 tests1,245 assertions0 failures in our run
Small checkout3 subsystemsBoth approaches passMycelium adds about 75% overhead
Order V211 subsystemsBoth test suites passTraditional version retains 4 reported latent defects
Order V315 subsystemsTraditional: 17 assertion failuresMycelium: 383/383 assertions pass
Explicit contracts catch boundary mistakes.
The benchmark's central defect is a key mismatch between placement and returns code. It remains latent across development rounds, then produces 17 failed assertions when new shipping behavior activates the path. A Mycelium input contract rejects the missing key instead of allowing a silent nil.
Mycelium does not make all defects impossible.
The benchmark was designed, implemented, and interpreted inside the project. It does not report a blinded multi-model trial, repeated stochastic runs, comparable token or human effort, or independent replication. It strongly illustrates a bug class. It does not prove that Mycelium's advantage grows combinatorially in general.
05 / Limits and maturity
The contract layer is optional, the ceremony is real, and main is moving.
Programmatic cells may omit schemas, permissive schemas can say little, and validation can run in warning or off modes. The strong guarantee comes from disciplined use.
Too-large cells recreate context overload. Too-small cells create a shallow module maze, bloated manifests, and contracts that describe plumbing instead of capability.
Every prior key remains available by default. This simplifies non-adjacent dependencies but can grow payloads, blur ownership, and expose more state than a later cell needs.
The helper planner currently treats all cells as one parallel implementation group. Real dependency-aware staffing, change impact, and integration ownership still belong outside the framework.
Current defcell requires a non-empty :doc, while prominent LLM-guide examples omit it. The README still uses the former repository coordinates.
Current main was 35 commits beyond v0.1.4 during research and contains unreleased breaking schema changes. Pin exact commits and expect migration work.
06 / Verdict
Use Mycelium when the risky part is the connection between independently plausible modules.
It is most compelling for stateful domain workflows with branching, long-lived data contracts, repeated handoffs, and enough interaction pressure that reviewers can no longer reconstruct the whole call graph reliably.
When control flow is a durable domain object and schema-bound cells map to meaningful capabilities.
On one bounded workflow with costly integration errors. Compare defect escape, review effort, change surface, and cycle time.
For a tiny linear feature, a CRUD surface with little domain flow, or a team unwilling to own contracts as carefully as code.
The promising synthesis is not “let agents design everything.” It is: keep human judgment at the boundaries, make those boundaries executable, and give agents freedom inside them.
Sources and method
Source behavior first. Claims second.
Research used the project's code, tests, documentation, benchmark artifacts, and maintainer essay. Repository contracts and our test run support mechanical claims. Benchmark conclusions are labelled as the project's evidence, not independent validation.