Skip to content

Origin — and the GitAI insight

Every rule in this framework is a scar. Here is how each one was earned.

New here? In plain terms: this page is the true story of why CompassAlpha exists. One founder tried to get several AI assistants to work together on a single real codebase, watched it go wrong in the same handful of ways every time, and built a set of rules so it would stop. If you ever want to know what a particular rule is for, the answer is almost always on this page — every rule maps back to a specific thing that broke.

CompassAlpha did not begin as a framework. It began as a frustration — a founder with one substantial codebase, several capable AI agents, and no working way to make them collaborate without the work quietly corrupting itself. The framework is the abstraction of what finally made that collaboration hold. This page tells that story, and shows why each artifact and each role was carved out.


The four pathologies of multi-agent AI work, each mapped to the axiom or guardrail that defends it

Each predictable failure of multi-agent work is answered by a specific defense — the framework is the set of those defenses, not a hope.

The setup

Picture a single founder running multiple AI-agent sessions against one real, non-trivial codebase — not a toy demo, but a system with many modules (call them Auth, Billing, Reporting) that have to stay coherent with each other. Each individual agent is genuinely capable. Any one of them, given a clean brief and a bounded slice, does excellent work.

The trouble was never the agents' competence. It was what happened between them — and across time. The moment two sessions had to coordinate, or one session had to pick up where another left off, the work began to rot in predictable, recurring ways. Four perspectives, four characteristic failures.

The mentor who "helps"

The senior session — the one meant to orchestrate, hold the plan, keep the altitude — would reach down and do the work itself. Helpfully. It would open the substrate, edit the Billing module, run the build, read the test output. By the end it had a perfect mental model of the slice and a context window stuffed with file diffs, stack traces, and half-finished edits. It could no longer orchestrate, because it had become a doer with amnesia about the bigger picture. The "help" was the damage.

The doer who improvises

The junior session — the one meant to implement a bounded slice — would receive a brief that was almost complete and confidently fill the gaps from imagination. Missing an acceptance criterion? It invented one. Unsure which Auth contract to honour? It picked the plausible-looking one. The output looked finished and was subtly, expensively wrong, because nobody had told it the part it improvised.

The session that "remembers"

A fresh session would assert, with total confidence, that "we decided last cycle to denormalize the Reporting tables." Except no such decision existed on disk. The agent had reconstructed a memory that felt true and was not. Acting on it propagated a fiction downstream as fact.

The founder who loses trust

And the human — the founder — would be told "done, it's committed and pushed," go to look, and find the disk did not match the claim. Once that happens twice, the founder can no longer step back. They have to verify everything by hand, which collapses the entire premise of delegating to agents at all. The trust anchor was gone.


The four failures

Those four perspectives are four named pathologies — recurring, predictable ways the work breaks — and they show up in every ad-hoc multi-agent setup, not just this one:

  1. Context pollution — a tier absorbs detail it shouldn't carry (the helpful mentor), and its judgement degrades.
  2. Hallucination drift — confident assertions that never happened on disk (the false memory) propagate as fact.
  3. Role confusion — tiers do work that isn't theirs (the mentor doing labour, the doer making decisions).
  4. Trust erosion — claims diverge from disk, and the human can no longer delegate.

CompassAlpha's entire defensive structure exists to prevent these four. They are catalogued as the framework's guardrails, and each axiom is traceable to the pathology it was carved to stop. If you weaken an axiom, you re-introduce its pathology — every time.


The requirements those failures forced

Sitting with the wreckage, a small set of non-negotiable requirements emerged. Not from theory — from incident:

  • A tier must do only its own job. Orchestrators orchestrate; only one tier touches the substrate.
  • A tier must carry only its own granularity. Senior tiers must not absorb slice-level detail; that is what poisons their judgement.
  • No claim may precede the disk. State must be durable before it is disclosed, or trust cannot survive.
  • No assertion may rest on memory. Every load-bearing fact must be re-derivable from a citable artifact, never from "I recall."
  • Coordination must survive death. A session can crash, a host can power down mid-turn — and the work must resume from exactly where it was, with no human re-explaining anything.
  • Parallel work must not clobber. Two sessions writing at once must be safe by construction.

Notice what every one of these requires: a single, durable, inspectable, append-only state of record — one shared place that survives crashes, that you can read at any time, and that you only ever add to (never silently rewrite) — held in common by all the agents and the human. The question became — what could possibly be that shared place (the substrate)?


Why git is the glue — the GitAI insight

The answer was sitting in plain sight, already present in every project: git.

This is the core realization the framework is named for — GitAI: the state of the AI-agent federation is the state of git. The same insight GitOps had for infrastructure ("state of infrastructure = state of git, automation reconciles") applies cleanly to AI orchestration, with the AI tiers themselves as the reconcilers. Git turned out to satisfy every requirement above at once:

  • State of record. What is committed and pushed is what is true. Chat is ephemeral; the repo is canonical. A claim that isn't in git didn't happen.
  • Durability across power-down. A flush means commit + push, not merely a file write. Local disk is volatile; the remote is the durable source of truth. A power-down loses at most the current in-flight turn.
  • Audit trail. Every message is a committed file; every state change is a commit. The federation's complete history is the git log — reconstructable, attributable, immutable at the tag boundaries.
  • Resume-from-anywhere. Disaster recovery is git pull. A fresh session pulls origin, reads its own folder and inbox, and continues. No human re-briefs it.
  • Parallel isolation, race-safe by construction. Each tier writes only in its own path; a push to a single ref is atomic — if two sessions race, one wins and the loser must fetch-rebase-retry. Nobody silently overwrites anybody.

Git was not adopted as a convenience. It was the only substrate that met the requirements without inventing new infrastructure. The deeper this idea is pressed, the more the framework follows from it — which is why git sits at the bottom of the constitution as Git foundations.


Why each piece was carved out

With git as the substrate, each remaining failure mode forced a specific, named structure into being. None of these is decoration; each closes a wound.

Tier grammar — three tiers, and mentors never touch substrate

The "helpful mentor" and the "improvising doer" are the same disease from two ends: roles bleeding into each other. The cure is a fixed grammar of exactly three tiers per axis — Mentor-1 (top orchestration), Mentor-2 (dispatch orchestration), and Doer (the only tier that touches the substrate). Three, not two, because a single mentor cannot both hold cycle-level strategy and run individual dispatches without polluting one with the other; and not four, because deeper nesting hits practical spawn limits and adds coordination cost without adding clarity. Mentors orchestrate and never touch substrate — this is the hard-labour rule, and it is what keeps a senior session's context clean enough to actually lead. The full grammar lives in tier grammar.

The Charter, Invariants, and Primitives — one constitution, shared contracts

When multiple agents build Auth, Billing, and Reporting in parallel, they will re-implement the same concept three incompatible ways unless something forbids it — the codebase-coherence problem. So the federation has exactly one constitution — the Charter — not one per team or per module. Under it sit two cross-cutting artifacts: Invariants, the rules that must hold everywhere always (maximally locked, not tunable), and Primitives, the single canonical definition of each shared concept that every module reuses (locked at the center, extensible at the edge). This is the constitutional spirit applied to doctrine itself — tight at the core, flexible at the rim — and it is laid out in full in the constitution.

The Ledger — live state on disk, "as of last tagged return"

The "session that remembers" fails because its truth lives in its head. The cure is that every tier's live cycle state lives in a Ledger file on disk, not in any session's memory. And it carries a precise contract enforced by the firewall: a mentor tracks only its own granularity, and "current WIP" in a mentor's notes means "as of the last tagged return," never "live." A mentor that auto-reads a sub-tier's folder manufactures false drift, because a sub-tier's in-progress snapshot contradicts the mentor's higher-altitude view by design. The disciplined, periodic snapshot of all this is the status grid — printed at every session start and end so state is always visible and always on disk.

The bus protocol — inbox-in-destination

Agents that coordinate through a chat relay lose the message the moment the chat scrolls. So coordination is files, not conversation: a sender writes a message into the recipient's own inbox folder, commits, and pushes; the founder pings "pull and read your inbox"; the recipient pulls and consumes only the blocks addressed to it. The message is durable, attributable, and routed by construction — no proprietary message bus, no lost context. This is the bus protocol.

Persistence law — flush before disclose

The trust-erosion failure has exactly one structural cure: state reaches disk and origin before it is disclosed to the human. Nothing load-bearing in chat. When a tier says "done," the disk already agrees, because the flush happened first. This single ordering rule is what lets the founder step back from verifying everything by hand — it is the persistence law, and the trust anchor depends on it.

Provenance law — cite by substrate, never memory

The hallucinating session is disarmed by a rule that no claim may rest on recollection: every load-bearing assertion must be cited to a substrate artifact — a committed file, a tag, a Ledger line — never to institutional memory. A fresh tier grounds itself against artifacts and must surface an original observation to prove it actually read them, rather than parroting. This is the provenance law.

Two reference axes — build and doctrine

Finally, the work itself has two distinct modes that must not run simultaneously: building against a settled constitution, and amending the constitution. Running both at once races the very rules being changed. So the framework declares two reference axes — a build axis (Mentor-1 / Mentor-2 / Doer producing code deliverables while the Charter is LOCKED) and a doctrine axis (Mentor-1 / Mentor-2 / Doer producing constitutional amendments while the Charter is UNLOCKED) — alternating temporally as a first-class state machine. Each axis names its own three tiers and inherits every rule from the Charter; declaring a new axis is just declaring its bindings. See axis declarations.


Why this is published

None of the above was designed in the abstract. Every rule on this page was forced by a real failure in a real production multi-agent federation running against a substantial live codebase, iterated over many cycles until the work stopped rotting. The framework is the abstraction of those proven patterns — stripped of any one project's domain, generalized to the universal vocabulary of Mentor-1 / Mentor-2 / Doer, Charter, Ledger, and bus.

It is published source-available by gradus so that other founders facing the same four pathologies don't have to re-earn every scar to find the structure that heals them.


Remember this

  • Every rule has a story. Nothing in CompassAlpha is decoration — each rule exists to stop a specific failure that actually happened: agents drifting out of their lane, inventing memories, claiming work that wasn't really saved, or quietly corrupting each other's output.
  • There are four failures, over and over. Context pollution, hallucination drift, role confusion, and trust erosion. If you only remember one thing, remember these — almost everything else in the framework is a defense against them.
  • Git is the shared source of truth. "If it isn't committed and pushed, it didn't happen." That single idea — the work's real state lives in git, not in any chat — is what makes the whole thing survive crashes and let you stop double-checking everything by hand.
  • Want the bigger picture? See the mental model for how these pieces fit together at a glance.

Next: The Constitution →