Monorepo Structure Standard
Every file traces back to a job
The structure of a repository shared by humans and coding agents. Six directories, three root files, and one aim. Every part has a purpose.
Structure without an aim is only folders.
Most repositories grow by accretion. Files land in arbitrary places. Directory names lose their meaning. No human and no agent can say why a thing lives where it does. Monorepo starts from the aim. Every directory and every file traces back to a job someone wants to get done.
Six directories. Three ship, three support.
Three directories carry shippable code. Three more support that code and do not ship. Each carries a README that names the jobs it exists to serve.
User-facing products. Each names the personas it serves and the progress it helps them make.
Long-running services that products consume. Each names the jobs it does for its dependents.
Shared code that products and services consume, with the jobs it does for platform builders.
Documentation hubs. Every guide maps to a Big Hire or Little Hire it serves.
Shared working memory. Humans and agents record what they learn as they work.
Deployment assets: Docker, gateway, database, and load balancer. Each has its own README.
Three files. One job each. None restates another.
These three files come from the Jidoka standard that Monorepo builds on. Here they orient you the moment you open the repository. A link is cheaper than a duplicate, so each file points at the others and does not repeat them.
What the project is, who it serves, and where to find things. Every run loads it automatically.
Invariants, technical rules, git workflow, security policy. Read it on demand. Every rule is verifiable.
The canonical Big Hires. One entry per persona-outcome pair captures the progress each persona seeks.
The aim, made discoverable.
Jobs live near the code that serves them. A semantic
<job> tag wraps each one. Any human or agent
then finds every job in the repository with one
rg search. You need no map.
Why a persona hires this product over the alternatives. One alternative is to hire nothing at all. One per persona-outcome pair, in JTBD.md.
What brings the persona back each time. It lives wherever it fits best: a product, service, or library README, a design doc, or nearby code.
Stand one up in three lines.
Install the packs. Tell Claude to build the skeleton.
The structure builds on the Jidoka instruction architecture. The Kata Agent Team runs the repository as a daily loop. Read the full standard in MONOREPO.md.