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.
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.
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:
- 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. - The owner passes the gates by applying labels:
gate:vision,gate:boundary,gate:design. The issue timeline records who applied which gate and when. - The work becomes packages. Each desk, or a small group of them, is a
work-packageissue with a member's name on it. - 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.
- 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.
- 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.
- 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.
- 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. - 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. - 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
Two modes, one tool
| Solo | Team | |
|---|---|---|
| Who | one developer on one machine | several people, several machines |
| Needs | nothing else: no mesh, no account | the Macula mesh |
| Who may approve a push or a release | you | the 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:
- mcl-kanban, a board. One board per repository and one card per GitHub issue. An agent claims a card with one call on the mesh, and when two claim the same card at once only one gets it, so two crews on one board never take the same work twice. The owner ranks the cards. Martha leaves the board off; the crew works from its issues and briefs.
- mcl-rag, shared memory. It re-ingests the repositories, ours and upstream ones alike, and takes deposits from agents; every answer carries the source it came from. A member starting on an unfamiliar repository asks it first, and what one crew learned another can ask.
- mcl-mail, letters. A mailbox per citizen of the mesh, person, agent or service, that holds a letter while the reader is offline. The sender is always the identity the mesh verified, so nobody writes their own from. It is how a crew reaches a crew that is not on duty.
- mcl-graph, a knowledge graph. Each instance keeps its own relational graph and answers queries over the mesh; whoever consumes them composes one graph from many. A crew keeps its own, and a crew of crews reads them together.
The pieces
- The crew declaration. One file in the project,
.martha/martha.json: who is on the crew, each member's role and model, and the mode's table of who may do what. Written once, never written over. - Approval before any launch. Martha shows every file that would start code and the checkout's tree, and takes one word: yes. The fingerprint covers both, so a config or a tree that changed since cannot start a member.
- A gate on every tool call. Every member holds a shell, so every piece of text that arrives is a possible command. The gate is a check on who sent it, run before anything is acted on, with an allow-list of tools that only read; everything else counts as executing. A crew that wants the strict rule, where text Martha cannot trace stops every later shell command in that session, turns it on in the declaration.
- The dashboard. One row per member: its state, its package, a progress bar, context use, cost, and what it waits on. A row reads "needs you" when the coding tool itself is asking something, and the owner's own terminal rings once when that happens.
- The ledger. Every hand-off, verdict, release and fix after shipping is written down, by package, so anyone can see who did what and why.
- Handover and refresh. When a session's context fills, Martha asks it for a handover, clears it and resumes it from its role card, brief and handover, so a long piece of work survives any number of context resets. A parked member stays parked across a clear, a restart or a refresh.
- One line per fact. A hand-off, a verdict or a yes names its package, its commit range and its CI run, and a malformed line is refused where it is written instead of sent.
- Acts that touch the repository run outside the session. Checking a range and its CI runs, landing a batch of passed work, fast-forwarding main onto the commit the owner said yes to, opening and finishing a worktree: each is answered by Martha's launcher, so nothing that acts runs inside a member's own shell.
- The owner's list. The acts only the person at the keyboard can do, each command shown in full under what it does, and taken off by their own check once a pull request is merged or a tag exists. Routine asks that belong to no change queue up and are offered together in one menu at a pause.
- A core no coding tool owns. Martha drives Claude Code. The core keeps its adapters thin, so another coding tool can be added without touching what decides. An adapter gives the core only what a coding tool physically has: a clock, stores, running a process, delivery in and out, registering a tool. Nothing that decides anything lives in an adapter. A behaviour one coding tool needs and another does not is a slice in the core, never a branch in an adapter.
- Nothing private gets in. A private issue link, an internal host name, a home path or a real node id fails CI by name, in the code and in the text members post on GitHub.
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 person | Needs the owner |
|---|---|
| Assigning a package and writing its brief | Applying gate:vision, gate:boundary, gate:design |
| Building red then green, lint and tests locally and in CI | A 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 rounds | Ranking the backlog when the order matters |
| Checking a range against the origin's tip before it reaches a menu | The approval before a member is launched |
| Progress rows, the ledger, handover and refresh | Anything 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
- Work that survives the agent: plans in issues, decisions in labels, progress in a ledger, and handovers that let a session pick up exactly where its previous context left off.
- A crew that keeps itself busy on the work you ranked, and asks you one clear question per change.
- Releases that build, sign and roll out canary first without anyone touching a server.
- Code that a newcomer, human or agent, can navigate by reading folder names.
- A unit of work, the desk, small enough to estimate and hold to, which is what lets a developer alone or a small firm commit to a price and keep it.
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.