Architecture Decision Records
Dated, immutable records of the structural decisions that shaped Orkeon. A superseded ADR keeps its original text as an archive; the superseding one links back.
Why does the numbering start at 002? There is no ADR-001 — the first decision recorded as an ADR was numbered 002 and the gap was kept rather than renumbering, so existing cross-references stay stable.
| ADR | Decision | Status |
|---|---|---|
| ADR-002 | Orkeon.Tools.Abstractions as a shared kernel (the Infrastructure → Tools.Abstractions exception) |
Accepted |
| ADR-003 | Secondary shared kernels: Application → Analysis.Abstractions, Infrastructure → Analysis |
Accepted |
| ADR-004 | The scripting naming twins, documented without renaming | Superseded by ADR-007 |
| ADR-005 | The heterogeneous Tools.* family (Tools.Web/Tools.EventHub → Application) |
Accepted |
| ADR-006 | The src/rag/ subsystem: Orkeon.Rag.Abstractions shared kernel, legacy RAG namespaces removed without shims |
Accepted |
| ADR-007 | Decision D3: Orkeon.Cli.Scripting renamed to Orkeon.Cli.Commands.Scripting before any NuGet publish |
Accepted |
| ADR-008 | A physical path is never a virtual path: runners mount under a name, infrastructure mounts are invisible to agents | Accepted — its RunnerMounts is now RunnerVirtualRoots (ADR-009); the decision stands, the type moved |
| ADR-009 | A constant two projects must agree on lives in a zero-dependency satellite, not in a hand-written copy guarded by a drift test | Accepted |
| ADR-010 | Microsoft Agent Framework interop is a separate package (Orkeon.Interop.AgentFramework), in both directions: a crew as an AIAgent, an AIAgent as brain or tool of an Orkeon agent; the initial context finally reaches the prompts |
Accepted |
| ADR-011 | The runners export OpenTelemetry by the standard contract (OTEL_EXPORTER_OTLP_ENDPOINT); Orkeon.Hosting.Aspire adds them to an AppHost; the Aspire dashboard is the cross-platform observability surface and no web Studio will be built |
Accepted |
| ADR — RaggableTree | 5-level-plus-edges stratified semantic graph via Tree-sitter (unnumbered — lives with its architecture guide; amended 2026-08-18) | Accepted |