Implementation Guides

Entry point for all Colibri implementation guides.

Status (R75 Wave I): Phase 0 is 100% on non-deferred tasks (28/28 shipped). P0.5.1/P0.5.2 shipped as δ library-only stubs per ADR-005 §Decision. src/ was re-established during R75 Wave A and now carries the live TypeScript runtime. Phase 0 guides describe the shipped contract; Phase 1+ guides still describe targets. Stack (shipped): TypeScript 5.3+ (ESM, NodeNext) · @modelcontextprotocol/sdk · Zod 3.23 · better-sqlite3 · merkletreejs · gray-matter · Jest (ESM). Chevrotain is deferred to Phase 1 (κ Rule Engine).

R69 — Agent-Ready Bootstrap Pack

New in R69: complete agent-bootstrap ecosystem for parallel multi-agent execution.

Guide Purpose
docs/guides/agent-bootstrap.md Master bootstrap prompt — read FIRST
first-7-prs.md Critical-path PR sequence (7 PRs to working server)
task-prompts/index.md Per-task agent prompts (all 28 Phase 0 tasks)
docs/guides/self-build-loop.md How Colibri builds Colibri (dogfooding)
docs/guides/agent-handoff-protocol.md Multi-agent handoff spec (stages, packet, failures)

Primary Entry Points

Guide Purpose
PHASE-0-EXECUTION-GUIDE.md START CODING HERE — Phase 0 entry point: task map, worktree setup, acceptance criteria, skills to load
task-breakdown.md 63-task breakdown — all phases with granular acceptance criteria
task-dependency-graph.md Mermaid dependency graph across all phases
skill-to-task-map.md Maps all 22 .agents/skills/ to Phase 0–8 tasks
pre-mcp-bootstrap-sequence.md Phase 0 manual protocol (before MCP server exists)

Phase Guides (TypeScript/Node.js — file paths, signatures, acceptance criteria)

Phase Guide Domain
Phase 0 (in task-breakdown.md §Phase 0) Bootstrap: server, DB, GSD, routing, audit
Phase 1 phase-1-kappa-rule-engine.md κ Rule Engine — DSL, Chevrotain parser, eval loop
Phase 2 phase-2-lambda-reputation.md λ Reputation — scoring, decay, tokens, gates
Phase 3 phase-3-theta-consensus.md θ Consensus — BFT voting, finality, gossip, slashing
Phase 4+ phase-4-complete-legitimacy.md μ ι π ξ — Integrity, Fork, Governance, Identity
Phase 5 phase-5-extensibility.md Plugin system and extensibility patterns

Algorithm References (Stack-agnostic — pseudocode, language-TBD, safe to read before choosing a stack)

Guide Domain
kappa-rule-engine.md κ — EBNF grammar, rule evaluation pseudocode, DSL examples
lambda-reputation.md λ — Reputation domains, BigInt arithmetic, decay formulas
theta-consensus.md θ — BFT message types, vote counting, view-change algorithm

Reference and Migration

Guide Purpose
ckamal-extraction-guide.md How to read the 49 extraction files in docs/reference/extractions/
phoenix-port-map.md Mapping from Phoenix Python source → Colibri Node.js targets

Quick Path: What to Read Before Starting

For Phase 0 (Bootstrap):

  1. PHASE-0-EXECUTION-GUIDE.md — complete Phase 0 entry point (start here)
  2. pre-mcp-bootstrap-sequence.md — manual protocol for P0.1.x (before MCP exists)
  3. task-breakdown.md §Phase 0 — 28 subtasks with acceptance criteria
  4. task-dependency-graph.md — unblock the critical path
  5. skill-to-task-map.md — which skill to load for each task

For Phase 1 (κ Rule Engine):

  1. task-breakdown.md §Phase 1
  2. kappa-rule-engine.md
  3. phase-1-kappa-rule-engine.md

For Phase 2 (λ Reputation):

  1. task-breakdown.md §Phase 2
  2. lambda-reputation.md
  3. phase-2-lambda-reputation.md

For Phase 3 (θ Consensus):

  1. task-breakdown.md §Phase 3
  2. theta-consensus.md
  3. phase-3-theta-consensus.md
  4. ADR-003 — BFT library decision (TBD)

Table of contents

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.