Section 00 / Architecture Decision Records 000
Architecture Decision Records
Append-only log of load-bearing decisions. One file per decision. Never deleted; superseded.
0001-in-front-not-in
Accepted
ADR-0001: kaged sits in front of adjacent operator tooling, not within
2026-05-21
0002-web-first
Accepted
ADR-0002: Web-first; terminal is a capability, not the product
2026-05-21
0003-doc-first-then-tdd
Accepted
ADR-0003: Doc-first, then test-driven
2026-05-21
0004-runtime-bun-typescript
Accepted
ADR-0004: Runtime is Bun + TypeScript
2026-05-21
0005-storage-sqlite-default
Accepted
ADR-0005: Storage default is SQLite; PostgreSQL is optional
2026-05-21
0006-dsl-format
Accepted
ADR-0006: Project DSL is YAML with JSON Schema + Zod validation
2026-05-21
0007-auth-oauth-sidecar
Accepted
ADR-0007: Authentication is an OAuth proxy sidecar in front of the daemon
2026-05-21
0008-plugin-model
Accepted
ADR-0008: Plugins are subprocesses over JSON-RPC on stdio
2026-05-21
0009-sandbox-technology
Accepted
ADR-0009: Sandbox technology is bubblewrap; network allowlist is kaged-managed
2026-05-21
0010-deployment-modes
Accepted
ADR-0010: kaged supports per-user and system-wide deployment, equally
2026-05-21
0011-project-portability
Accepted
ADR-0011: Projects are portable; operator-local concerns live in local config
2026-05-21
0012-agentic-substrate-mastra
Accepted
ADR-0012: Agentic substrate is Mastra v1.x
2026-05-22
0013-observability-langfuse
Accepted
ADR-0013: Observability substrate is Langfuse, self-hosted, optional
2026-05-22
0014-llm-providers-via-kaged-llm-shim
Accepted
ADR-0014: All LLM providers route through @kaged/llm; Mastra integrates via a LanguageModelV2 shim
2026-05-23
0015-federated-project-config
ADR-0015: Federated Project Configuration & Resource Resolution
0016-streaming-first-ui
Accepted
ADR-0016: Streaming-first UI — live data and operator abort are non-negotiable
2026-05-24
0017-guest-principals
Accepted
ADR-0017: Guests are first-class identities with daemon-managed credentials
2026-05-25
0018-guest-project-grants
Accepted
ADR-0018: Guest access to projects is granted via per-project permission sets, not project DSL
2026-05-25
0019-workflows-dsl-block
Accepted
ADR-0019: Workflows are operator-authored, parameterised DSL artifacts agents invoke
2026-05-25
0020-issues
Accepted
ADR-0020: Issues are daemon-stored work items routed through operator triage
2026-05-25
0021-guest-ui-surface
Accepted
ADR-0021: Guest UI lives at /g/* — segregated route tree, distinct app shell
2026-05-25
0022-recursive-agents-per-agent-config
Accepted
ADR-0022: Agents are recursive; tools and cage are per-agent
2026-05-26
0023-project-plugin-lifecycle-hooks
Accepted
ADR-0023: Project-plugin lifecycle hooks, per-agent declaration, isolation as a core principle
2026-05-27
0024-context-compaction
Accepted
ADR-0024: Context compaction is kaged-owned, layered, observable, and operator-tunable
2026-05-27
0025-typecheck-orchestration
Accepted
ADR-0025: Typecheck orchestrates per-package; root tsc is a marker
2026-05-27
0026-cost-management-model-overrides-usage-tracking
Proposed
ADR-0026: Cost management, model metadata overrides, and provider usage tracking
2026-05-30
0027-linting-formatting-biome
Accepted
ADR-0027: Linting and formatting via Biome
2026-05-28
0028-oauth-provider-auth
Proposed
ADR-0028: 3rd-party OAuth provider auth — token lifecycle and credential management
2026-05-30
0029-structured-operational-logging
Proposed
ADR-0029: Structured operational logging
2026-05-31
0030-log-streaming-sse
Accepted
ADR-0030: Log streaming via Server-Sent Events
2026-06-02
0031-message-transcript-rendering
Proposed
ADR-0031: An assistant turn is an ordered transcript of parts, not a flattened bubble
2026-06-03
0032-monaco-editor
Accepted
ADR-0032: Monaco Editor as the code editor for kaged UI
2026-06-03
0033-tool-dot-namespace-convention
Accepted
ADR-0033: Tool dot-namespace convention
2026-06-05
0034-issue-bound-todos-and-session-binding
Accepted
ADR-0034: Sessions bind to one issue; the issue owns the agent's todos and drives closure
2026-06-05
0035-unified-operator-shell
Accepted