Macula Mesh Use Build Macula for… Docs Contact

Macula

Martha, the AI software factory

A crew of coding agents plans, builds, reviews and releases software the way a good team does, while one person decides what gets built and says yes before anything ships. Martha is that crew, open source under Apache-2.0, for a developer alone or for a team.

View Martha on GitHub →

Software factories solved half of the problem years ago: a linter runs on every commit, a test suite on every push, a pipeline builds, signs and releases, and a fleet pulls its own desired state from a repository. That half is about how code is handled. The other half is deciding what the software should do, and writing it so the decision survives a team, a successor, or a coding agent. Martha is built for both halves, and the second one comes first, because it is the one that decides whether the code an agent writes tomorrow is still readable in five years.

The method the crew works with

Three practices carry the whole way Martha designs and builds. Each is old, plain, and does one job; together they make code that repeats a few predictable shapes, which is exactly the property a factory needs. The examples below are from a book club built this way, with the code public.

Event storming: find what happens first

Before anyone draws a database, the people who know the work stand at a wall and name what happens, in the past tense: a member registered, a book was procured, a reading finished. Those orange notes are the vocabulary of the business and nothing else. The commands that cause them and the rules that react to them are added only once the events are agreed. In the club, nine such events were enough: club_initiated_v1, member_registered_v1, book_procured_v1, reading_started_v1, reading_finished_v1, party_planned_v1 and three more. Anyone who runs a book club can read that list, which is the test it has to pass: the owner of the business will be reading it too.

Vertical slicing: one capability, one folder

One business capability lives in one directory with everything it needs inside: the command, the event it produces, the rule that decides, and the door the outside world knocks on. Not a folder of controllers and a folder of services with the feature smeared across both. Registering a member is one folder, and a stranger can read it without a guide:

apps/host_bookclub/src/register_member/
    register_member_v1.erl       the command
    member_registered_v1.erl     the event
    maybe_register_member.erl    the business rule
    register_member_api.erl      the door

Names say what the business does. Commands are verbs, events are facts in the past tense, the rule is maybe_ plus the verb, and the words create, update and delete are banned, since a folder called register_member tells a new reader, human or agent, more than a folder called members ever could. Where one part reacts to another, the reaction is its own folder named on_<event>_<action>, so every policy shows up as a directory: on_member_registered_v1_maybe_plan_party is a sentence you can read.

Event sourcing: the state is what happened

The state of a club is not a row that gets overwritten but the list of what happened to it, in order. Any table you need for reading is built from that list afterwards by a part of the system that only writes tables, and read by a third part that only answers questions. Writing, recording and answering are kept apart on purpose, which is the CQRS part if you like acronyms. In the club that is three applications: host_bookclub holds what the club can do, project_bookclub turns each event into rows, and query_bookclub answers a book, a member or a reading by id. Each part is small and dull, and dull is the point.

Put the three together and a desk is four files, an event is one module, a projection is one event to one table, and a query is one question with one answer. When the shapes repeat, they can be produced by a template or by a language model, and checked by a machine.

The D5 model

Simon Brown's C4 model gives architects four zoom levels for drawing a system: context, container, component and code. We use it. For the process side we have five levels of our own, each starting with D, and we call them the D5 model: four nested places and one thing that moves through them. The nod to C4 is intended. C4 says where the boxes are; the fifth D says what moves through them, and that is the point.

The D5 model A Domain contains Divisions. A Division has three Departments: commands, projections and queries. Each Department holds Desks. The Dossier moves through the desks of the command department, growing as it goes. Domain the whole business endeavour Division one cohesive piece of software: a bounded context, its own repository Department: commands what the division can do Department: projections events to tables Department: queries questions, answered Desk initiate_club Desk register_member Desk procure_book Desk start_reading Desk finish_reading Desk plan_party Desk member_registered_v1 to members Desk book_procured_v1 to books Desk get_member_by_id Desk get_book_by_id Dossier the aggregate: a folder of event slips that passes from desk to desk and grows as it goes. C4 says where the boxes are; the fifth D says what moves through them.
The D5 model on the book club. Every desk in the command department is four files; every desk in the projection department is one event to one table; every query desk is one question.

A Domain is the whole business endeavour. A Division is one cohesive piece of software inside it, the bounded context, the thing that gets its own repository. A Department is one of three roles inside a Division: commands, projections, queries. A Desk is one capability inside a Department, the folder above and the atomic unit of work. And the Dossier is the aggregate: the folder of event slips that passes from desk to desk and grows as it goes.

The desk is why the factory stops being a metaphor. It is small enough to describe on one sticky note, strict enough to template, and complete enough to test on its own. Give one desk to one person or one agent as a work package, ask for the failing test first, have a second pair of eyes pass the change, and let a person say yes before it reaches main, and the tenth desk comes out with the same quality as the first. A desk is a unit of work, and so it is also a unit you can estimate and price.

The loop, end to end

The four phases every team knows, analysis, architecture, implementation and operations, kept their purpose in Martha and lost their paperwork. A coding agent forgets everything between sessions, and a hand-off document nobody reads is a hand-off that never happened, so each phase lands somewhere a machine and a person can both read. The result is one loop that repeats for every change, small or large:

  1. An idea becomes an issue. It opens with one line, Purpose (<kind>): <outcome>, stating what a person can do afterwards. Plans never live in files; the issue is the plan, and what ships becomes documentation in the repository.
  2. The owner passes the gates by applying labels: gate:vision, gate:boundary, gate:design. The issue timeline records who applied which gate and when.
  3. The work becomes packages. Each desk, or a small group of them, is a work-package issue with a member's name on it.
  4. The Supervisor assigns. It writes a short brief: the goal in one line, the deliverables, the rules that apply, and whether the work is a build (tests and a commit) or a claim about the world (which also gets an adversarial design review). The Supervisor coordinates and never does a member's work itself.
  5. The member builds, red before green, in its own git worktree, and commits as it goes. Builders run on an inexpensive model; reviewers run on a stronger one. That keeps cost down without lowering the bar.
  6. A reviewer passes the range. One review per package. Every bug it finds is required: the member fixes it and the reviewer checks the fix, and that repeats until the review passes. A green CI run on the exact commit is part of the hand-off, so the reviewer reads a run, not a promise.
  7. One menu to the owner. Martha checks the range against the origin's tip first, so a stale base never reaches a menu, then puts everything one change needs, the exact commit range for main, the tag, the fleet commit, in the order they run, in a single yes/no question.
  8. CI ships it. A v* tag builds the image, checks it, signs it by digest and attests its SBOM and provenance. Libraries publish to hex.pm or npm from the same tag; nobody publishes by hand.
  9. The fleet rolls itself. The release job pins <semver>@sha256:<digest> on a canary, waits for the canary to report that version, then pins every other box. Each box pulls the fleet repository every two minutes and applies what changed. Nobody logs in to restart anything; a deploy is a reviewed commit and a rollback is a revert.
  10. The issue closes with evidence. The closing comment says whether the purpose was met, citing a test, a commit or a live check.

What Martha is made of

Martha in context The crew in the middle, with the owner above, GitHub to the left, the registries and the fleet below, the Macula mesh to the right with its board, memory, mail and graph services, and beyond the mesh another crew under its own owner. The owner ideas, planning gates, and a yes on every tag, every publishing push, every spend The crew, run by Martha Supervisor: briefs, one ask per change Members: long-lived sessions with a role card each Reviewers: one review per package, on the review model Dashboard, ledger, handover and refresh Approval before any launch; a gate on every tool call a core no coding tool owns drives Claude Code; adapters kept thin GitHub issues: plans, work packages labels: gates, lanes commits, PRs, v* tags CI: lint, tests, sign, attest the fleet repository Registries ghcr.io: signed images, SBOM and provenance hex.pm, npm: packages The fleet every box pulls its desired state from git runs semver@sha256 pins, canary first, signatures checked before an image runs The Macula mesh team mode, and between crews rooms conversation across machines and crews mcl-kanban: the board one board per repository, one card per issue mcl-rag: shared memory what one crew learned, another can ask mcl-mail: letters they wait while the reader is offline mcl-graph: a knowledge graph one per crew, composed across crews one identity per member post-quantum, signed on every call Another crew, run by Martha its own owner, its own repositories, its own yes rooms, services gates, yes / no one menu per change issues, commits CI on a v* tag: build, sign, publish signed digests pin commits a reviewed fleet commit calls, rooms
Martha in context. Solo mode is the left and middle of this picture. Team mode adds the mesh on the right, and through the same mesh another crew, under its own owner, with its own repositories and its own yes.

Two modes, one tool

SoloTeam
Whoone developer on one machineseveral people, several machines
Needsnothing else: no mesh, no accountthe Macula mesh
Who may approve a push or a releaseyouthe people the team names

The mode is a table of who may do what, not a different program. Solo is a table with one person allowed to do everything; team is a table with roles. You start solo and move to team without changing tools. The mesh that joins a team is also what joins crews: two crews under two owners meet in its rooms and can use the services it offers, and each keeps its own repositories and its own yes.

The mesh: where crews meet

Every member on the mesh carries one identity, post-quantum, and every call it makes is signed with it. Rooms are where members talk, across machines and across crews. The mesh also offers services that a crew can use as a shared workplace. They belong to the mesh, not to Martha:

The pieces

Martha installs from a signed package at an exact version, and upgrades itself only through the installer that the running release pins, so what you run is what was built, signed and published from the repository's own tag.

The practices in code

The gate is the same on the box and in CI. Every push and every pull request runs the repository's gate: the code compiled with warnings as errors, the cross-reference check, the structural floor, the unit tests, and Dialyzer in the Erlang services. A member runs that same gate before it offers a range, and the range arrives with a CI run on its exact tip.

Complexity is capped, never baselined. Erlang: nesting two levels, functions of at most 60 lines, no nested try/catch. TypeScript: nesting three, cyclomatic complexity nine. Elixir: credo's defaults. Rust: nesting three, cognitive complexity fifteen, functions of at most 60 lines. There is no baseline file to grow into and no inline disable that outlives review: a function over the cap fails the push, and the fix is to split it rather than to widen the limit.

Secrets. Secret scanning and push protection are on for every public repository: a commit that carries a credential is refused at the push rather than found later.

Red, then green. A test is written first and seen to fail for the right reason, and only then is the code written that makes it pass. A test that was never red proves nothing.

GitOps. Every box runs exactly what a commit in the fleet repository says. Images are signed by the CI that built them, with their SBOM and provenance attached, and a box verifies all three before it runs an image. A release reaches the canary first and the rest only after the canary reports it healthy.

Small stays small. Before work starts it is classified as a build or a claim. A build, a CI job, a file move, an article like this one, gets tests and a commit and never an adversarial gate. Every piece of work opens with the one-line goal it serves, and the question asked first is what a user can do afterwards that they could not do before.

A snag becomes an issue, with a check. When a problem comes from how the crew works rather than from one piece of code, a gap in a tool, a rule nothing enforces, a step that fails the same way for every member, whoever hits it files it in the repository that owns the method or the tool, and asks for a check that fails mechanically next time. That is what makes the crew continuous: a mistake is fixed in the mechanism once, instead of by hand every time it comes back.

What we choose first. Where an ordering is ours to decide, correctness and security come first, then what a member of the public sees, then efficiency, then convenience. A faster path that costs a stranger's trust is not a faster path.

What runs by itself, and what stays with a person

Runs without a personNeeds the owner
Assigning a package and writing its briefApplying gate:vision, gate:boundary, gate:design
Building red then green, lint and tests locally and in CIA yes on every tag, on every push that publishes, on any change to the fleet, and on any delete, credential or spend, each on the exact commit range
The review and the fix-and-verify roundsRanking the backlog when the order matters
Checking a range against the origin's tip before it reaches a menuThe approval before a member is launched
Progress rows, the ledger, handover and refreshAnything public that cannot be taken back
Building, signing, attesting and publishing on a tag
Canary pin, health wait and fleet-wide pin

The owner's acts are few but deliberate: they are the points where a wrong step costs real money, real users or real trust, and a menu carrying the exact commit range makes each of them a few seconds of reading rather than an afternoon of review. A reviewed, green push to main that publishes nothing is the crew's own step: nothing reaches a user and the rollback is a revert.

Running Martha on your own work

Martha is not tied to the Macula code base. It is a way of running a crew of coding agents on any repository a developer or a team owns, and the method travels with it.

What you need

  • A GitHub organisation for your repositories, issues and CI.
  • Node, git, a terminal, and the coding tool Martha drives for each member.
  • A fleet repository if you run services: one private repository holding every box's desired state.
  • The Macula mesh only when a second person, or a second crew, joins.

What stays yours

  • Deciding what is worth building: the purpose line and the gates.
  • The yes on every tag, on every publishing push, on every change to the fleet, and on any delete or credential.
  • Any spend, and anything public that cannot be taken back.

What the factory gives you

The first storm is still the hard part, and no factory removes it. Getting the right people in front of the wall, naming the events honestly and finding where one division ends and the next begins is thinking, and it stays thinking. What the method does is make everything after the wall boring, so that the thinking is the only thing a person has to spend attention on.

The code: Martha, the book club, and the corpus of rules, templates and recorded mistakes the crew works from. The method, walked through on the book club in sixteen minutes: the video, and the article. If you want a crew working your backlog this way, tell us what you build and how many of you build it, and we will show you what the first week looks like.