Skip to content
Like what we’re building? Star on GitHub

Architecture decision records ​

One decision per file, named NNN-kebab-title.md, where NNN is the next free number. The number is the record's identifier: it is cited from code comments, commit messages, pull requests and other ADRs, and from places this repository cannot reach — a chat thread, a ticket on another forge, someone's notes. That is why a number, once published, is never reassigned and never renumbered: doing so repairs the links inside this tree by silently breaking every citation outside it.

Numbers used twice ​

Eight numbers were nevertheless taken twice, by decisions written in parallel. They are listed here so an ambiguous ADR-NNN stays resolvable: a reader who follows one of these numbers reaches this table, and picks the subject they meant. TestADRNumberCollisionsAreDeclared keeps the table honest in both directions — a new collision that is not listed fails, and a listed number that no longer collides fails too.

Do not add a row to this table to make a build pass. A new record takes a free number; this table only records what was already published.

NumberRecordSubject
002002-desktop-assetserver-proxy.mdDesktop studio hosted via the Wails AssetServer handler
002002-editor-runview-separation.mdSeparating the Run console from the Workflow editor
075075-irref-fallback-for-oversized-cloud-queue-ir.mdIRRef fallback: offloading an oversized compiled IR at cloud dispatch
075075-nexie-roadmap-study-cycle-skill-level.mdNexie v3: the roadmap-study cycle as a skill-level behaviour
076076-pipeline-hard-blockers-and-waiting-deps.mdPipeline hard blockers, waiting_deps, unified launch admission
076076-scoped-config-share-editor.mdScoped config-share editor (self-service, per-field, per-repo)
090090-model-registry-and-operator-model-choice.mdA model registry, and letting the operator choose the model
090090-runtime-operational-settings-db-backed.mdRuntime-configurable operational settings, DB-backed
091091-fallback-skip-route-and-plan-peer-review.mdaction: skip terminal route, when: route gate, cross-model plan phase
091091-ubiquitous-assistant-chat-dock.mdThe assistant is a shell-level dock, not a route
093093-bot-vars-runtime-settings.mdBot-var overrides resolved from the DB before the pod env
093093-model-spec-registry-as-a-leaf-package.mdThe model-spec registry is a leaf package; its prices are a cost tier
094094-shared-subbot-bundles-bot-uri.mdShared subbot bundles: the bot:// dependency URI
094094-trigger-effect-outbox.mdDurable effect outbox for cloud board triggers
098098-connector-catalog.mdThe connector catalog: MCP for agents, deterministic nodes for workflows
098098-dsl-versioning-and-authoring-surface.mdDSL versioning, explicit imports, and the authoring surfaces

Citing one of these: name the file, not the number — docs/adr/098-connector-catalog.md rather than ADR-098.