All ADRs
The full index of all 33 ADRs, grouped by topic. Within each group, ADRs are listed by number. Highlighted ADRs (marked with ★) get extended treatment with narrative context — see the highlights section for the curated deep-dives.
If you’re new here, start with What is an ADR? or jump straight to the highlights.
Foundation: project setup and conventions
Section titled “Foundation: project setup and conventions”The bedrock decisions about how the codebase is built and tested. Every other ADR rests on these.
- ADR-0001 — Monorepo with pnpm workspaces
- ADR-0002 — TypeScript strict mode (all flags)
- ADR-0003 — Biome for lint + format
- ADR-0004 — Vitest as test runner
- ADR-0010 — Zod v4 for schema validation
- ADR-0015 — GitHub Actions CI as the quality gate
Architecture: the platform’s shape
Section titled “Architecture: the platform’s shape”The decisions that define what the platform IS — its layering, its primitives, its security boundaries.
- ★ ADR-0005 — Two-layer architecture (Platform Core + Business Packs) — see the highlight
- ★ ADR-0006 — Six-layer context system; layers 1–2 immutable — see the highlight
- ADR-0009 — Types-only Platform Core package
- ADR-0011 — Schemas live in a separate package
- ADR-0012 — Runtime immutability enforcement for assembled context bundles
- ADR-0013 — Enterprise readiness bar
Runtime: agent execution
Section titled “Runtime: agent execution”How agents actually run. Tool loops, delegation, the model-tier abstraction.
- ★ ADR-0021 — Agent runtime and tool loop — see the highlight
- ★ ADR-0022 — Delegation as tool — see the highlight
- ADR-0007 — Branded ID types
- ADR-0008 — Provider-agnostic
ModelTier - ADR-0023 — Tool registry — concrete ToolResolver
LLM and embedding adapters
Section titled “LLM and embedding adapters”The provider-agnostic abstractions over Anthropic, OpenAI, and future providers.
- ADR-0019 — Provider-agnostic LLM adapter interface
- ADR-0020 — Anthropic concrete LLM adapter
- ADR-0028 — LLM provider abstraction — error taxonomy
- ADR-0029 — Embedding provider abstraction —
EmbeddingAdapter
Storage and memory
Section titled “Storage and memory”Where data lives. The hardest design problems on the platform.
- ★ ADR-0030 — Long-term memory access pattern — agent-driven via tools — see the highlight
- ADR-0027 — Storage primitives per memory layer and data type
- ADR-0032 — Async coordination primitives — queues, event bus, outbox
Deployment and operations
Section titled “Deployment and operations”How the platform runs in production. Workers, jobs, secrets, logging, errors.
- ADR-0014 — Cloudflare Workers as the runtime platform
- ADR-0024 — Deployment model — Cloudflare Workers as first target, runtime-agnostic core
- ADR-0026 — Job management — auth, listing, deletion
- ADR-0016 — Structured logging
- ADR-0017 — Error taxonomy
- ADR-0018 — Secrets and config access
Agent definition format
Section titled “Agent definition format”How agents are written. YAML, prompts, bundling.
- ★ ADR-0031 — YAML agent definition format and loader — see the highlight
- ADR-0033 — Worker bundling for YAML agent definitions and Markdown prompts
Phase 1 scenarios
Section titled “Phase 1 scenarios”The decisions that shaped Phase 1’s first scenarios.
Why so many ADRs?
Section titled “Why so many ADRs?”33 ADRs in a Phase-1 codebase is more than most teams write. The density is intentional. Every decision documented here had at least one alternative we seriously considered; many had three or four. The ADR is the artifact that lets us re-examine the choice when the world changes — when Cloudflare ships a feature that obviates a workaround, when our usage patterns invalidate an early assumption, when a new contributor asks “why is this like this?”
If a Phase 2 ADR supersedes one of these, that’s not a failure of the original — it’s the system working. The old ADR stays in place; the new one explains what changed.