Decide your architecture once. Stop paying for it twice.
Every team already has two versions of the truth — what the docs say, and what the code actually does — and they drift apart the moment a deadline gets tight. ARCH makes that impossible by construction: metadata is the only place a decision gets made. Code, schema, and runtime behaviour aren't kept in sync with it. They're generated from it, every time, on demand.
1
Source of truth
1
Hard gate at commit
8
Agent-ready tools
15
Domains, zero overlap
What drift actually costs you
Stale docs. Code that quietly disagrees with the spec. Two engineers, two vendors, or a human and an AI agent building against slightly different pictures of the same entity — and nobody notices until it ships. ARCH doesn't manage that risk. It removes the condition that causes it: there is nowhere else for a decision to live, so there is nothing left to fall out of sync.
And it stays disciplined about scope while it does this. ARCH doesn't run migrations, deploy schema, or manage environments — that's the runtime layer's job. ARCH owns exactly one thing, upstream of all of it: keep the description correct, and let everything else follow automatically.
Built on four non-negotiables
DERIVATION, NOT SYNC
Code is generated from metadata. Metadata is never reverse-engineered from code — so there's nothing to keep in sync, because there's only one copy.
A PLATFORM, NOT A DEPENDENCY
ARCH is authored once as an installable bundle every project copies in. No shared service, no uptime dependency, no version lock-step across teams.
GOVERNANCE THAT DOESN'T SLOW YOU DOWN
Ideas stay unrestricted inside a session — sketch, argue, reshape, freely. Governance shows up exactly once: at the moment something asks to become durable.
COMMITTED AND TRUSTED, KEPT SEPARATE
Passing validation and earning human sign-off are two different claims, tracked independently — so "it's in main" never quietly gets read as "it's approved."
Fifteen domains. Not one square inch of overlap.
The rules themselves are organized as fifteen numbered domains, each owning exactly one concern — from mission and structure at the low numbers, through governance, collaboration, and codegen, to platform and metadata schema at the top. No domain reaches into another's territory; a session that needs to touch two concerns cites both explicitly rather than blurring the line.
10 Mission21 Structure22 Governance23 Collab51 Codegen61 Platform71 Dev Env95 Metadata
See the mechanism that makes this safe.
One gate, one atomic merge, zero partial states. Sheet 02 walks through exactly how a session earns its way into main.
Sheet 02 / Mechanism
No partial states. No silent exceptions. Two endings, always.
Every unit of work — human-driven or agent-driven — follows the same shape: branch, iterate freely, then either commit or discard. That's not a simplification for the pitch deck; it's the whole guarantee. There is no third outcome, and nothing ever lingers half-applied once a session closes.
The loop
startbranch from main
→
previewfuzzy, disposable, warn-only
→
commitfull validation → merge to main
discardbranch closes, main untouched
Preview mode is where most of the thinking happens. Validation still runs, but only as a warning — nothing blocks iteration, and a session can stay open indefinitely while an idea gets sketched, argued with, and reshaped. Nothing about that phase is durable, which is exactly what makes it safe to move fast in.
Commit is the one hard gate
Everywhere else in the loop, an AI agent may originate metadata without asking permission first — that's the "progressive governance" belief made concrete. The single non-optional checkpoint is arch session commit: full structural and semantic validation runs against the session's current state, with no exceptions and no override.
Pass, and the merge is atomic — a new version is tagged per the project's cascade rules, canonical codegen fires against the merged state, and the branch retires. Fail, and the commit is simply aborted: the branch stays open, unchanged, and main is provably untouched. Nothing partial ever lands.
Committed ≠ trusted. A passing commit means the metadata is structurally and semantically valid — not that a human has signed off on it. ARCH tracks those as two separate axes on purpose, so "durable" and "approved" never get silently conflated.
Small slices beat one big review
The recommended rhythm is small, frequent, coherent commits rather than a single exhausting review at the end of a long session. It isn't enforced — Preview mode will happily let a session run as long as it needs to — but it's the pattern the rest of the design assumes: cheap to commit, cheap to discard, cheap to try again.
Ready to see the switching cost?
Spoiler: it's four files and one command. Sheet 03 takes you from an empty folder to your first commit.
Sheet 03 / Setup
Zero to first commit in four steps. No service to stand up.
A new project doesn't depend on ARCH as a running service — it copies in a small, self-contained bundle and runs its own independent session lifecycle from there. There's no account, no server, nothing to keep online for it to work.
What's in the bundle
Four pieces travel together: arch.py, the CLI that wraps the session lifecycle over plain git; validate.py, which checks structural and semantic rules against the metadata tree; the JSON Schemas each metadata category is checked against; and project.config.json, the one file specific to your project — its git remote, hosting target, and capability selection.
First session, start to finish
Copy the bundle in
Drop arch.py, validate.py, and the schemas into your project's repo, alongside a project.config.json you fill in once.
Open a session
Branches your metadata tree from the current main and records where it started from.
arch session start add-customer-entity
Sketch freely
Add or edit entities, domain rules, workflows, integrations. Preview as often as you like — nothing here blocks on validation.
arch codegen preview
Commit when it's solid
Runs the full validation gate. Passes merge atomically and tag a new version; failures leave the branch open to fix and retry.
arch session commit --minor
Or let an agent call it directly
The same four steps are also exposed as MCP tools, so an AI agent can run the loop without shelling out to the CLI itself — useful when the session is being driven from a chat interface rather than a terminal.
The write/read/list tools are scoped strictly to the metadata tree — an agent can populate a session's content through them, but the commit gate above still runs in full before any of it reaches main.
Now imagine four of these running at once.
One person, one session, one gate — you've just seen the whole loop. Sheet 04 is what happens when a whole team calls it at the same time.
Sheet 04 / Action Stations
Concept — proposed operating mode, not yet run
One session per person. One signal. Full speed, in parallel.
Everything on Sheets 01–03 already supports this — it's just never been named or drilled. A session is unrestricted while it's open and only checked at the door on the way out, which means there's no structural reason a team has to work one branch at a time. Call it, and every station moves at once.
How the call works
Nobody waits for a green light to start working — that's already true today. "Action Stations" is the moment a team deliberately synchronizes on it: everyone claims a station, opens a session against it, and drives it in Preview mode with no coordination overhead, because nothing they do there is visible or binding to anyone else yet. The discipline isn't in the parallelism — ARCH already gives you that for free. It's in what happens at the muster.
A station roster, illustrated
Not a real run — just what it'd look like mid-drill. Four people (or three people and an agent), four sessions, four domains, moving independently until each one is ready to report to the gate.
The military framing is a good fit because the mechanics underneath already match it — this is a translation, not a new set of rules.
Man a station
Claim a domain, run arch session start. That's the whole enlistment — no lock to request, no one to ask.
Free maneuver
Preview mode the whole way. Validation only warns, so a station can sketch, gut, and rebuild without ever blocking another station.
Report to the gate
Nothing a station did counts until arch session commit clears it. This is the only checkpoint that exists — and it's the same one every solo session already goes through.
Contested ground
Two stations touched the same entity? That's an ordinary git merge conflict, surfaced to whoever owns the overlap — not a standing lock that made everyone else wait for it.
Stand down
arch session discard. No trace on main, no penalty, no report to file. A station that didn't pan out simply didn't happen.
Action Stations
Every piece of this already exists on Sheets 01–03. The only thing "Action Stations" adds is the nerve to run four sessions at once instead of one — and trust the gate, same as always, to catch what actually collides.