CompassAlpha¶
It's how you build, not a thing you build on. CompassAlpha isn't a platform, a template, or an app you start from — it's a way of working (plus a shared rulebook) for keeping a codebase coherent when several people or AI assistants build it together. You bring your own product, your own AI agents, your own git; CompassAlpha governs how they stay consistent.
In plain words: when several people — or several AI assistants — build one product together, they each tend to solve the same problem a slightly different way, and the codebase slowly turns into a tangle no one can keep straight. CompassAlpha keeps everything consistent as it grows — so what gets built stays true to what you pictured.
Which one are you?¶
Pick the door that fits you today — each is a real starting point, not a sales funnel:
- I just have an idea — I don't write code. → Start with just an idea: plain words, no setup, no vocabulary first — you describe it and hand the technical part off.
- I'm one developer; I want to start today. → Borrow CompassAlpha (solo): two habits you can adopt this afternoon — no federation.
- I'm sizing this up for a real project or a team. → Is it worth it yet? — the honest, right-sized answer (you don't adopt the whole thing on day one).
- I have an existing codebase. → Bring it in without a rewrite: non-destructive — your code stays untouched on day one.
- I just want to understand it first. → The mental model: the core ideas, about ten minutes.
A little more precisely (for the technical reader)
You get a codebase that stays coherent as it grows — one canonical way to do each thing, enforced by an AI-agent federation against a single doctrine, never left to each agent's guess. Say a component's vision in plain words; the federation grows it down through every layer — 60K → 30K → 10K → code (zoom levels, from a high-level view down to the schema) — all bound to that one doctrine.
CompassAlpha is the source-available framework that orchestrates those multi-tier AI-agent federations on substantial codebases and doctrine work — the reference framework for GitAI (GitOps' coordination patterns applied to multi-agent AI). Coherence is what you get; the federation, the bus protocol, and git are how it's delivered. The one-liner: a framework, not a tool — the state of the federation is the state of git. How code coherence works →
This portal is the framework's constitution + adoption guide. The framework itself is the protocols, conventions, and load-bearing rules documented here. The patterns were proven by a production multi-agent federation that drove every refinement in this document.
The whole thing on one page — you do not need to understand this yet. Inheritance · the two axes + future-axis slot · work-granularity lanes · stage taxonomies · the bus protocol · load-bearing rules · trade-offs · tunables. Click to open full size.
Where to start¶
Not sure how much of the framework you need? Start with the adoption ladder — it maps adoption as rungs you climb at your own pace, and helps you find the one that fits you today (many start by simply borrowing it solo).
Have a project in mind already? Jump straight to Start from a story (new idea) or its brownfield companion (existing codebase).
Read the Foundation pages in order (~20 minutes):
- The mental model — the core ideas the framework rests on
- Framework, not tool — what CompassAlpha is, what it's not
- Origin — why GitAI — the failures that forced the framework
- The Constitution — the 8 invariant axioms + the doctrine model
- Codebase coherence — the core point of distinction
- GitAI category — where CompassAlpha fits
- Glossary — the canonical vocabulary
Jump to Getting Started:
- Start from a story — describe a new product idea in plain English and get a CompassAlpha plan (greenfield).
- Start from a story — existing project — bring an existing codebase in non-destructively (brownfield).
- Prerequisites — what you need before adopting
- Greenfield setup — fresh project path
- Brownfield onboarding — pre-AI era project path
- Cutover from a pre-AI project — step-by-step
Go to Adoption Patterns for worked examples:
- Sample doctrine cycle
- Sample Phase 3 dispatch
- Sample Day-2 cycles (QA · Ops · Compliance)
The Reference section has the full manifesto, all templates, and technical specs.
Is CompassAlpha for you (yet)?¶
First, the welcoming part: you're welcome here regardless of your size — or whether you write code at all. This section is about how much of the full framework pays off for you yet, not whether you belong. If you just have an idea and don't code, your door is Start with just an idea — plain words, no setup, hand the technical part off. If you're one developer with one AI assistant, you can borrow the core habits today. Wherever you are, there's a rung for you on the adoption ladder. With that said, here's the honest scale-fit:
CompassAlpha earns its ceremony on substantial, multi-component work built by more than one AI agent, over many cycles — a real codebase, new or existing, where keeping every part coherent across sessions and contributors actually matters.
If you're a solo developer on a small, one-off project, the full federation — two repos, three tiers, doctrine cycles — is honestly more than you need today. That's a straight answer, not a sales dodge.
But one idea is worth borrowing even with a single AI assistant and no federation: keep a small Charter (write down the one canonical way to do each recurring thing) and cite by substrate (let decisions live in git, not in a chat you'll lose). That alone prevents most coherence drift — the slow sprawl of three slightly-different ways to do the same thing — for almost no ceremony.
This is the lowest rung of CompassAlpha, and it's a real one — written up step by step, with a copy-paste Charter, in Borrow CompassAlpha (solo). Grow into the rest of the framework if and when your project does — the adoption ladder maps the climb, rung by rung, and names the signal that means it's time for the next one.
The four-layer mental model¶
CompassAlpha is structured in four conceptual layers, from most-rigid to most-flexible:
-
AXIOMS (invariant)
8 inviolable rules. Cannot be tuned away. Read once, internalize forever.
-
GUARDRAILS (protective)
What the framework prevents. Failure modes documented with recovery.
-
TUNABLES (configurable)
The customization surface. The 5-axis trade-off space. Operating presets.
-
TOGGLES (live switches)
When each parameter can flip — runtime, cycle-boundary, project-lifecycle.
Everything in Axioms and Guardrails is [INVARIANT]. Everything in Tunables and Toggles is [TUNABLE]. This is the constitutional separation.
The five design pillars¶
What CompassAlpha believes
- Protocol-first, tool-agnostic. The framework specifies how tiers behave; it does not mandate Claude Code, GPT, Cursor, or any specific harness.
- Tiered with mentor/orchestrator/doer hierarchy to minimize context pollution. Mentors orchestrate; only the doer touches substrate.
- Git as the durability and audit layer. No specialized databases. State persistence =
git commit + pushto a dedicated state-of-record remote. - Human-in-the-loop relay, NOT autonomous agents. The founder is a load-bearing relay (one-liner pings) and lost-and-found backstop — not a per-decision arbiter.
- Doctrine evolution as a first-class concern. Build cycles AND doctrine cycles, in alternating epochs.
What CompassAlpha defends against¶
The four pathologies of multi-agent AI work
- Context pollution — Agents accumulate detail they shouldn't retain
- Hallucination drift — Institutional memory diverges from substrate
- Role confusion — Mentors do labour; doers make decisions
- Trust erosion — Claims diverge from what's actually on disk
Every axiom and guardrail in the framework exists to prevent one or more of these.
Where the framework came from¶
CompassAlpha is the abstraction of patterns that emerged from running a real multi-agent AI federation on a substantial production codebase. That federation evolved through multiple doctrine cycles, hitting each of the four pathologies above and engineering solutions cycle by cycle.
The framework is published source-available, structured to be parametric: project-specific values are marked [TUNABLE] throughout, with worked examples in the manifesto.
Quick reference¶
| Need to | Go to |
|---|---|
| Understand the framework | Foundation |
| See what's invariant | Axioms |
| See what's protected against | Guardrails |
| Tune for my project | Tunables |
| Flip switches at runtime | Toggles |
| Start adopting | Getting Started |
| See worked examples | Adoption Patterns |
| Look up technical details | Reference |
| Contribute or governance | Community |
CompassAlpha is a framework, not a tool. The framework's value lies in its constitution, not in any executable. You bring your own AI agents (Claude Code is the reference); you bring your own git; you bring your own host. The framework guards how they collaborate.