Skip to content

Architecture decision records

Each record captures one decision: the context that forced it, the options considered, and the consequences we accepted. Records are immutable once accepted; a changed decision gets a new record that amends or supersedes the old one. Proposals that precede decisions live in ../rfcs/.

ADR Title Status
0001 Python library with a sans-IO core Accepted
0002 One write path: commands through Workspace.commit Accepted
0003 Artifact types are Pydantic subclasses with library-defined patch kinds Accepted
0004 Optimistic concurrency and append-only revisions Accepted
0005 One durable event log per workspace Accepted, amended by 0021
0006 Agent integration as a pydantic-ai capability Accepted, amended by 0017
0007 Live output is owned by the caller, not the log Accepted
0008 Agent perception: change notes, fresh rendering, steering Accepted
0009 Write policies and non-blocking proposals Accepted
0010 Pausing with pydantic-ai deferred tools Accepted
0011 Workspace-scoped artifacts and tenant-scoped handles Accepted
0012 Surfaces: WebSocket thread protocol, REST commands, MCP Superseded by 0048
0013 A library with adapters and a reference implementation Accepted
0014 Trunk-based development with RFCs, ADRs and evergreen docs Accepted
0015 Quality gates Accepted
0016 MIT license Accepted
0017 Application toolsets register on the agent; the capability emits capability events Accepted
0018 Core's host contract: needs, commit and record Accepted
0019 One storage protocol behind workspace handles Accepted
0020 Running agents in threads Accepted
0021 SQL storage with one dialect-neutral implementation Accepted
0022 Surfaces over one command handler Superseded by 0048
0023 The documentation site Accepted, amended by 0026 and 0050
0024 The reference implementation as a workspace member Accepted
0025 Distributed as artifactr-ai, imported as artifactr Accepted
0026 Publishing the documentation site from main Accepted, amended by 0050
0027 OpenTelemetry-native observability, with Langfuse primary Accepted
0028 Typed feedback as events, mirrored to Langfuse Accepted
0029 evalr, a shared eval kit Accepted
0030 Contributor Compose and dev containers here, infrastructure in stackr Accepted
0031 LiteLLM, proxy first, for routing and guardrails Accepted
0032 Libraries, and stackr as the infrastructure template Accepted
0033 Trace links on runs and revisions Accepted
0034 Ports and adapters for integrations Accepted
0035 A turn is its own trace Accepted
0036 Metric cardinality through SDK views Accepted
0037 Feedback targets and evaluators Accepted
0038 Feedback as scores, through ports Superseded by 0049
0039 The Langfuse adapter Accepted; its score adapters superseded by 0049
0040 Joining stackr's network when it runs Accepted
0041 Dashboards generated, tested and released Accepted
0042 Typed run failures Accepted
0043 The LiteLLM adapter Accepted
0044 The evalr adapter Accepted; its amendment superseded by 0049
0045 A message id is used once in a workspace Accepted
0046 Telemetry that composes across libraries, untraced polling and mirror cursors Accepted
0047 Cancel-safe storage Accepted
0048 Surfaces over the runner Accepted
0049 Scores on evalr Accepted
0050 One docs build Accepted
0051 Notices: messages that start no turn Accepted

To add a record, copy template.md to the next number and add a row above.