Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for Colibri. Each ADR documents a significant architectural decision: what was decided, why, and what the alternatives were.
Format
Each ADR uses the following structure:
# ADR-NNN — Title
**Status:** PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED
**Date:** YYYY-MM-DD
**Supersedes:** ADR-NNN (if applicable)
**Superseded by:** ADR-NNN (if applicable)
## Context
## Decision
## Consequences
## Alternatives Considered
Status definitions
| Status | Meaning |
|---|---|
PROPOSED |
Decision is under discussion; not yet binding |
ACCEPTED |
Decision is binding for new work |
DEPRECATED |
Decision was once binding but is no longer recommended |
SUPERSEDED |
A newer ADR replaces this one (link to replacement) |
Index
| ADR | Title | Status | Domain |
|---|---|---|---|
| ADR-001 | SQLite: node:sqlite vs better-sqlite3 | PROPOSED | Infrastructure |
| ADR-002 | VRF Implementation: HMAC-based vs @noble/curves | PROPOSED | Legitimacy (π Governance) |
| ADR-003 | BFT Consensus: Build from scratch vs libp2p | PROPOSED | Legitimacy (θ Consensus) |
When to write an ADR
Write an ADR when:
- Choosing between two or more viable technical approaches
- Making a decision that will be hard to reverse
- Changing a core dependency or protocol
- Accepting a known trade-off
Do not write ADRs for:
- Implementation details within an already-decided design
- Minor refactors with no architectural consequence
- Documentation-only changes
Who can accept ADRs
Only the PM (project owner) may move a PROPOSED ADR to ACCEPTED. Sub-agents must leave new ADRs in PROPOSED status and surface them in their task writeback.