Colibri System
One document. One system. One truth.
This is the canonical master document for Colibri. Any fact that conflicts with this document is stale. This document replaces the mixed signals previously spread across
colibri-master-context.md,greek-vocabulary.md,CLAUDE.md,AGENTS.md, andindex.md. Those files will be brought into alignment with this one during R73.
1. Identity — What Colibri Is
Colibri is one runtime with three axes:
| Axis | Promise | Key concepts |
|---|---|---|
| Execution | Work is defined, ordered, and delivered. Every task moves through a 7-state pipeline with explicit writeback. | α System Core · β Task Pipeline · γ Server Lifecycle · ε Skill Registry |
| Intelligence | Work is routed to the right model, reasoned about in hash-chained steps, and auditable after the fact. | δ Model Router · ζ Decision Trail |
| Legitimacy | Work is provable, constrained, and governed. Not only the result, but the right to the result. | η Proof Store · θ Consensus · ι State Fork · κ Rule Engine · λ Reputation · μ Integrity Monitor · π Governance · ξ Identity |
Three definitions, all true at once:
- Technical: a Node.js MCP server that orchestrates tasks, routes model calls, records thoughts, and builds Merkle proofs.
- Architectural: a three-axis control plane — execution · intelligence · legitimacy — glued through a single SQLite database and a single middleware stack.
- Philosophical: a system of legitimized agentic activity. Outputs are not only correct; they carry a cryptographic right to be trusted.
ν Integrations is cross-cutting (not an axis). It bridges the runtime to Obsidian, GitHub, Claude API, and editor tooling.
2. Current Ground Truth (R75 Wave I, 2026-04-18)
Numbers below are what the repository actually contains today. They supersede every count in every older doc.
| Fact | Value |
|---|---|
| Phase 0 progress | 100% on non-deferred tasks (28/28 shipped). P0.5.1/P0.5.2 shipped as Phase 0 library stubs per ADR-005 §Decision (PR #149 scoring, PR #150 fallback). src/ was re-established during R75 Wave A and now carries the live TypeScript runtime. |
| Greek concepts defined | 15 (α β γ δ ε ζ η θ ι κ λ μ ν π ξ). 8 ship code at colibri_code: partial (α β γ δ ε ζ η ν); 7 remain colibri_code: none (θ ι κ λ μ ξ π spec-only for later phases). Frontmatter graduation landed in R75 Wave H.2 (7 concepts) and Wave I (δ). δ ships as library-only Phase 0 stubs per ADR-005 §Decision — interface present, formula replacement for Phase 1.5. |
| Documentation files | ~193 active .md under docs/ |
| Algorithm extractions | 49 files in docs/reference/extractions/ (22 original R45–R50 + 27 function-level R53) |
| Protocol specs | 19 in docs/spec/ |
| Implementation guides | 13 in docs/guides/implementation/ |
| Greek concept map | 15 concepts mapped to runtime layers in docs/world-schema.md; individual narratives under docs/3-world/ (execution / physics / social) |
| Skills | 23 canonical colibri-* in .agents/skills/ (MIRROR copy in .claude/skills/). ams-* stubs were removed in R75. |
| Phase 0 task breakdown | 63 sub-tasks in docs/guides/implementation/task-breakdown.md (P0.1.1 – P0.9.3) |
| Per-task agent prompts | 9 files in docs/guides/implementation/task-prompts/ (P0.1 – P0.9) |
| MCP tool surface (shipped) | 14 tools over stdio: 5 β Task (task_create, task_list, task_get, task_update with FSM-routing, task_next_actions) · 4 ζ Audit (audit_session_start, thought_record, thought_record_list, audit_verify_chain) · 2 η Proof (merkle_finalize, merkle_root) · 1 ε (skill_list) · 2 System (server_ping, server_health). R74.5 planned 19; implementation closed/deferred 5 and added 1 (see ADR-004 R75 Wave H amendment). The donor AMS “484-tool” count is heritage, not a Colibri target. |
| Phase 0 runtime modes | 4: FULL, READONLY, TEST, MINIMAL. Selected via COLIBRI_MODE. No AMS_* env namespace is read by Phase 0 code. |
| Phase 0 middleware | 5 stages: tool-lock → schema validate → audit enter → dispatch → audit exit |
| Stack | TypeScript 5.3+ (ESM, NodeNext) · @modelcontextprotocol/sdk · Zod 3.23 (v4 was planned; v3.23 shipped) · better-sqlite3 · merkletreejs · gray-matter · Jest (ESM). Chevrotain is deferred to Phase 1 (κ Rule Engine). |
| Entry point | src/server.ts — shipped (Wave A, P0.2.1). |
| Database file | data/colibri.db — shipped (Wave B, P0.2.2). Created at runtime in WAL mode. (data/ams.db is HERITAGE — the AMS donor task store, kept only as the writeback target through the Phase 0 bootstrap.) |
If you see a number or path different from this table anywhere else in the repo, the other place is stale.
3. The 15 Greek Concepts — Canonical Table
All 15 concepts are concepts, not agents. They describe parts of the runtime. Any earlier document that referred to ξ, ο, π, ρ, or σ as doc-loop agent roles is using a now-retired naming. Agent roles are named in §4 and do not collide with concept letters.
| # | Letter | Name | Axis | Status | Target module |
|---|---|---|---|---|---|
| 1 | α | System Core | Execution | Shipped (Phase 0) | src/server.ts, src/db/ (middleware inlined in src/server.ts) |
| 2 | β | Task Pipeline | Execution | Shipped (Phase 0) | src/domains/tasks/ |
| 3 | γ | Server Lifecycle | Execution | Shipped (Phase 0) | src/server.ts (boot/shutdown) |
| 4 | δ | Model Router | Intelligence | Shipped Phase 0 stubs (Wave I — P0.5.1/P0.5.2, library-only per ADR-005 §Decision; full multi-model routing Phase 1.5) | src/domains/router/ |
| 5 | ε | Skill Registry | Execution | Shipped (Phase 0, axis closed Wave H — P0.6.1–P0.6.3 capability index) | src/domains/skills/ |
| 6 | ζ | Decision Trail | Intelligence | Shipped (Phase 0, Wave G closed) | src/domains/trail/ |
| 7 | η | Proof Store | Legitimacy | Shipped (Phase 0, Wave F complete) | src/domains/proof/ |
| 8 | θ | Consensus | Legitimacy | Spec-only (Phase 3) | src/domains/consensus/ |
| 9 | ι | State Fork | Legitimacy | Spec-only (Phase 5) | src/domains/fork/ |
| 10 | κ | Rule Engine | Legitimacy | Spec-only (Phase 1) | src/domains/rules/ |
| 11 | λ | Reputation | Legitimacy | Spec-only (Phase 2) | src/domains/reputation/ |
| 12 | μ | Integrity Monitor | Legitimacy | Partial (Phase 4) | src/domains/integrity/ |
| 13 | ν | Integrations | Cross-cutting | Shipped (Phase 0, Waves F/G — library-only; no MCP tools) | src/domains/integrations/ |
| 14 | π | Governance | Legitimacy | Spec-only (Phase 6) | src/domains/governance/ |
| 15 | ξ | Identity (Soul Vector) | Legitimacy | Spec-only (Phase 8) | src/domains/identity/ |
Why no ο σ ρ ω etc.? Those letters are not concepts. The earlier doc-loop used σ/ξ/ο/π/ρ as swarm role names. Because ξ and π are also concepts, that naming collided. R73 retires Greek doc-loop role names (see §4).
4. Four-Tier Agent Hierarchy
Work flows through four tiers. Each tier has a contract; no tier may skip the tier below it.
Tier 0 — Human (owner) ── intent, authorization, merge
│
Tier 1 — Sigma Orchestrator ── round planning, phase gating, writeback audit
│
Tier 2 — PM ── promote backlog → todo, dispatch, wave gates
│
Tier 3 — Executor agents ── 5-step chain, worktree, implementation
│
Tier 4 — Models ── Claude (primary); Kimi / Codex deferred
Tier 0 — Human (owner)
Role. The single source of intent. Only the human can:
- Authorize a new round
- Merge a PR to
main - Rebase or amend published commits
- Change the canonical vision
Contract. The human sets intent; all lower tiers carry it out. No agent may self-promote a backlog task or change scope without explicit human authorization.
Tier 1 — Sigma Orchestrator
Role. The round-level orchestrator. Sigma does not write code. Sigma:
- Reads the round plan and emits a Phase A manifest (work slices, dependencies, owner per slice)
- Dispatches to PM for wave execution
- Collects results and runs Phase B completion (verify writeback, audit, seal the round)
Contract. docs/agents/sigma-orchestrator.md. Sigma is the only tier allowed to seal a round or close a session.
Tier 2 — PM
Role. The task-level manager. PM:
- Runs the startup chain (
unified_init,unified_vitals,unified_set_project,task_next_actions) - Promotes backlog → todo (the only tier with this authority)
- Dispatches executors by wave (governance → runtime → domain → integrations → tests/ci/docs)
- Enforces wave gates (a wave may not start until the previous wave’s writeback is complete)
Contract. docs/agents/pm-contract.md. PM never writes code directly; PM spawns executors.
Tier 3 — Executor agents
Role. Hands-on workers. Every executor runs the 5-step chain: audit → contract → packet → implement → verify. Every executor operates in an isolated worktree under .worktrees/claude/<task-slug> on feature/<task-slug>. Every executor writes back via task_update + thought_record.
Contract. docs/agents/executor-contract.md. An executor may not skip the packet stage, may not edit the main checkout directly, may not merge its own work.
Tier 4 — Models
Role. The underlying LLMs that power agents at Tiers 1–3. Phase 0 assumes Claude only. Multi-model routing (Kimi, Codex, GPT-class) is deferred to Phase 1.5 when δ Model Router lands. See docs/architecture/decisions/ADR-005-multi-model-defer.md.
5. Four-Surface Topology
Colibri lives on four surfaces at once. Each has a specific purpose; none is the “truth” alone.
| # | Surface | Purpose | Direction of truth |
|---|---|---|---|
| 1 | Repository (E:\AMS, GitHub LastEld/AMS) |
The canonical source of all specs, ADRs, skills, and (eventually) code. | Authoritative. All other surfaces are projections. |
| 2 | Worktrees (.worktrees/claude/<task>) |
Per-task isolated copies, one branch each, where executors actually edit. | Feed-in. Merges back to main through PRs. |
| 3 | Obsidian vault (C:\Users\Kamal\Documents\Obsidian Vault\Colibri\) |
The human reading surface. Graph view, backlinks, daily notes, round cards, planning scratch. | Projection of docs/ + human-only planning in _vault/. Never edits source files directly. |
| 4 | GitHub Pages (https://LastEld.github.io/AMS/) |
The public reading surface. Jekyll + just-the-docs remote theme. |
Projection of docs/ built by GitHub Pages CI. |
Sync rules
- Repo → Obsidian: docs are mirrored through
colibri-docs-syncskill. Obsidian-only content lives inObsidian Vault/Colibri/_vault/and is never committed to the repo. - Repo → Pages: Jekyll builds every push to
main.docs/_config.ymlanddocs/_includes/govern layout. Asset files live indocs/assets/. - Worktrees → Repo: PR workflow only. Branches named
feature/<task-slug>. Merge by human. - Obsidian ← → Repo: one-way,
docs/→ vault. The vault is not a source of truth for any file that also exists underdocs/. Seedocs/multi-surface-topology.mdfor details and the full sync matrix.
6. The Canonical Pipeline
Colibri has one pipeline. It exists at three zoom levels: session → round → task.
6.1 Session level (months)
A session is a coherent arc of 5–15 rounds with a single theme. Sessions are sealed with a docs/session-seal-sN.md document. Sessions 1–5 complete; session 6 active (R53–R72 complete, R73 unification in progress).
6.2 Round level (days)
A round is one unit of orchestrated work. Every round has:
- Phase A — plan: Sigma writes the manifest (slices, owners, dependencies)
- Phase W — waves: PM dispatches executors in waves. Wave order:
- governance (specs, ADRs, constitutional rules)
- runtime (α β γ — the execution axis)
- domain (δ ε ζ η — intelligence + first legitimacy)
- integrations (ν — GitHub, Obsidian, Claude API)
- tests / CI / docs (verification surface)
- Phase B — seal: Sigma audits writeback, runs verification, closes the round with a commit and (optionally) a PR merged by the human.
A round owns exactly one branch namespace: feature/rNN-*.
6.3 Task level (hours)
A task is the unit executors operate on. Every task moves through the β Task Pipeline 7-state FSM:
INIT → GATHER → ANALYZE → PLAN → APPLY → VERIFY → DONE
↘ CANCELLED
Every task executor runs the 5-step chain: audit → contract → packet → implement → verify. Every task has a writeback contract: task_update(status=done, progress=100) + thought_record(...). Proof-grade tasks additionally run audit_session_start → work → audit_verify_chain → thought_record → merkle_finalize → merkle_root.
6.4 Three axes × pipeline
Each axis has its own signal inside the pipeline:
| Axis | Signal at task level |
|---|---|
| Execution | β state transitions, contract-first chain, wave gating |
| Intelligence | ζ thought records per decision, δ model selection per call |
| Legitimacy | η Merkle leaves per task, κ rule checks per apply, μ audit verify per seal |
The round cannot close until all three axes have left a signal. No signal = no round.
See docs/pipeline-definition.md for full details.
7. Why This Document Exists (R73)
Before R73 the project had six overlapping “master” docs:
| File | Problem |
|---|---|
docs/colibri-master-context.md |
Internally contradictory: Session 6 and Session 7 both “active”; claimed 484 tools. |
docs/reference/greek-vocabulary.md |
Treated ξ π as agent roles, contradicting 15-concept table. Referenced deleted src/ paths. |
CLAUDE.md |
Claimed src/server.js is the entry point (deleted R53). |
AGENTS.md |
Listed 5-agent doc-loop swarm using ξ π (collision with concepts). |
docs/index.md |
Claimed 234 files, 63 tasks — numbers were stale. |
MEMORY.md |
Memory index said R54; reality was R72. |
Symptoms the human reported:
- “много хаоса” — lots of chaos
- “по документации не чуствуется что это одна система” — the docs don’t feel like one system
- “там 484 тулза зачем то???” — why 484 tools?
Root causes identified:
- Concept/agent letter collision — ξ and π were both concepts and doc-loop roles.
- Memory drift — 18 rounds of progress not reflected in MEMORY.md.
- Orphaned donor heritage — 484 tools is an AMS donor count, not a Colibri target.
- Four surfaces without a sync contract — repo, Obsidian, Pages, worktrees each drifting.
- No single canonical vision doc — every doc pointed to a different master.
R73 fixes all five. This document is the single canonical vision. Every other doc either (a) projects from this one, (b) narrows into a sub-topic of this one, or (c) gets deprecated.
8. Reading Order (for anyone new)
- Humans and PMs: this doc →
docs/pipeline-definition.md→docs/multi-surface-topology.md→docs/roadmap/R73-R80-plan.md - Agents executing a task:
CLAUDE.md→AGENTS.md→docs/agents/executor-contract.md→docs/guides/implementation/task-prompts/<task>.md - Designers: this doc →
docs/design-system.md - Anyone verifying claims:
docs/architecture/decisions/(ADRs)
9. What’s Not in This Document
This document is deliberately short. It does not contain:
- Full Phase 0 task list — see
docs/guides/implementation/task-breakdown.md - MCP tool schemas — see
docs/reference/mcp-tools-phase-0.md - Concept internals — see
docs/world-schema.mdfor the map,docs/3-world/for runtime-layer bodies,docs/reference/extractions/for algorithm pseudocode (e.g.alpha-system-core-extraction.md). - Skill definitions — see
.agents/skills/ - Architectural rationale — see
docs/architecture/decisions/(ADRs)
If you need the what, look in the link. If you need the why, look in an ADR. If you need the one sentence answer, look here.
10. Living Document Rule
This document changes only through a round seal. Never edit it mid-round; add an ADR instead. If an ADR is accepted, update this document in the next round’s Phase A. A commit that modifies this file and is not the product of a sealed round is a bug.
Canonical master document — R73 unification corpus.