CompassAlpha
busyboy77/compassAlpha
Protocolo de federação multi-agente com Git como camada de durabilidade
Ver no GitHubFramework fonte-aberta para coordenar múltiplos agentes de IA em um único repositório, usando Git como camada de durabilidade, auditoria e coordenação. Define protocolos, convenções e regras de governança para evitar poluição de contexto, drift alucinatório e confusão de papéis em operações multi-agente.
Instalação
npx convez-ai busyboy77/compassAlpha1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Orquestração de múltiplas instâncias Claude Code em bases de código substanciais
- Coordenação de equipes de agentes IA com mentoría hierárquica tier-based
- Implementação de ciclos de construção e doutrina alternados em desenvolvimento colaborativo IA
Veredito

CompassAlpha é um framework de governança rigoroso para federações multi-agente, não uma ferramenta pronta. Exige disciplina arquitetural e Git profundo; ideal para equipes que querem coordenar agentes IA sem perder auditabilidade e controle contextual.
README
A tradução para o português deste README ainda está na fila.
CompassAlpha
A framework, not a tool. Source-available federation framework for multi-tier AI-agent collaboration on substantial codebases. The reference framework for GitAI — using git as the coordination, durability, and audit layer for multi-agent AI operations.
A source-available federation framework — free for non-commercial use; commercial use requires a license.
Free for non-commercial & evaluation use · commercial use requires a license.
The whole framework at a glance: 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.
What is CompassAlpha?
CompassAlpha provides a protocol — not a tool — for coordinating multiple AI agents (e.g. Claude Code instances) across two or more parallel work axes, with a single human "founder" acting as a low-cognitive-load relay bus. The framework's value lies in the protocols, conventions, and load-bearing rules that govern how agent tiers communicate, persist state, hand off work, and avoid the four pathologies of multi-agent AI work: context pollution, hallucination drift, role confusion, and trust erosion.
Design pillars:
- Framework, not tool. CompassAlpha is a constitution + a set of conventions. You bring your own AI agents, your own git, your own host. The framework guards how they collaborate.
- Tier-hierarchy with mentor/orchestrator/doer roles — minimizes context pollution; mentor tiers never touch 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.
- Extensible by inheritance. Two axes (build, doctrine) are the default; new axes (review, ops, AI-training, pen-test, …) plug in.
What CompassAlpha is NOT
- ❌ A SaaS product
- ❌ A library you
npm install - ❌ An AI agent itself
- ❌ A monitoring dashboard
- ❌ A replacement for your CI/CD, IDE, or git host
What CompassAlpha IS
- ✅ A constitution + protocol specification
- ✅ A set of conventions for naming, structuring, and coordinating
- ✅ A pattern proven by a production multi-agent federation
- ✅ A documentation portal with worked examples
- ✅ A growing ecosystem of stamp templates, status grids, and operating presets
Quick start
For first-time visitors: read What is CompassAlpha → The Constitution → Glossary → GitAI category. About 15 minutes.
For someone evaluating adoption: read Getting Started — pick greenfield or brownfield depending on your project's state.
For someone adopting on an existing codebase: see Adoption Patterns for worked examples.
Portal structure
| Section | What's there |
|---|---|
| 00 Foundation | What CompassAlpha is, the constitution, GitAI category, glossary |
| 01 Axioms | The 7 INVARIANT rules — cannot be tuned away |
| 02 Guardrails | What the framework PREVENTS · failure modes |
| 03 Tunables | The customization surface · 5-axis trade-off |
| 04 Toggles | Live switches · when each can flip |
| 05 Getting Started | Onboarding for greenfield AND brownfield projects |
| 06 Adoption Patterns | Worked examples · Day 2 cycles |
| 07 Reference | Technical reference · manifesto · templates |
| 08 Community | Contributing · roadmap · governance |
Build the docs locally
# Install MkDocs Material
pip install mkdocs-material
# Serve locally with live reload
mkdocs serve
# Build static site
mkdocs build
# Deploy to GitHub Pages
mkdocs gh-deploy
Project philosophy
CompassAlpha emerged from one stark observation: multi-agent AI collaboration on substantial codebases fails predictably, in ways that are NOT about model intelligence. Failures are about coordination — context pollution between agents, snapshot vs live-state drift, mentor agents tempted to "help" by doing labour, trust eroding when claims diverge from disk. CompassAlpha addresses these failures with structural guardrails rooted in git and protocol, not in heroics.
The framework grew out of a real production multi-agent federation that hit each of these failure modes and engineered solutions cycle by cycle. CompassAlpha is the abstraction of those patterns.
Status
This is v0.1 DRAFT — the framework is in active development, released source-available under BSL 1.1. The framework will reach v1.0 stable after:
- A full doctrine cycle close + re-lock
- Community review pass
- Adoption by at least one greenfield + one brownfield project
Track progress in the Roadmap and Changelog.
License
Business Source License 1.1 — source-available. Free for non-commercial, evaluation, research, and internal non-production use; commercial or production use requires a commercial license from gradus (see COMMERCIAL.md). Each version converts to the Apache License 2.0 on its Change Date (2030-06-09 for v0.1). "CompassAlpha" and "gradus" are trademarks — see NOTICE.
Acknowledgments
CompassAlpha is built and maintained at gradus.pk with a series of Claude (Anthropic) sessions, and published source-available.
With recognition of the categories CompassAlpha builds upon: GitOps (DevOps community), AIOps (operations + AI community). CompassAlpha is GitAI — the same pattern applied to AI agent federations.
"State of the federation = state of git." — the GitAI insight.