Skip to content

Architecture Decision Records

We record significant, hard-to-reverse decisions as ADRs using a light MADR format. One file per decision, immutable once Accepted — supersede rather than edit.

Index

ADR Title Status
0001 Record architecture decisions Accepted
0002 Implementation stack: TypeScript + Node + pnpm monorepo Accepted
0003 Concurrency: atomic files + union merge + derived indexes Accepted
0004 License: Apache-2.0 Accepted
0005 Search: SQLite FTS5 now, pluggable embeddings later Accepted
0006 Sync architecture: resident daemon Accepted
0007 Curation & review gate: in-repo staging queue Accepted
0008 Curation locality: staging is per-user local, canon syncs Accepted
0009 Brain-level config & feature flags (incl. optional auto-ADR) Accepted
0010 Secret scanning: built-in regex default, gitleaks optional Accepted
0011 Brain wiring: global user registry is the default source Accepted
0012 MCP distribution via the plugin at user scope Accepted
0019 Access model: git permissions are the ACL; clone on demand Accepted
0020 Ask the brain: the host agent synthesizes; cited retrieval Accepted
0021 Embeddings: opt-in local-first semantic dedup; vectors in index Accepted
0022 Decisions captured by default: autoAdr on + /decide command Accepted

Process

  1. Copy the format of an existing ADR. Number sequentially.
  2. Status: Proposed → Accepted / Rejected. Later decisions can mark an ADR Superseded by ADR-XXXX.
  3. Link the ADR from the relevant GitHub issue (decision tickets carry type:decision).
  4. Keep it short: Context → Decision → Consequences → Alternatives.