Architecture Decision Records (ADR) - CascadeIDE¶
This is where the architectural decisions taken are recorded: context, choices, consequences and rejected alternatives. architecture-policy.md - a short navigator and table of links here; step-by-step migration and MCP contracts - in architecture-migration.md, MCP-PROTOCOL.md.
Policy connection: Major changes in direction will be a separate commit with a navigator update and a new entry here.
Statuses and life cycle (without ADR list): status-lifecycle.md.
Index¶
Index status: Accepted / Proposed / Superseded only. Details (Implemented, "direction", strangler) - in the ADR header and status-lifecycle.md.
Thematic clusters¶
Brief navigation; full list - below. Large ADRs have a ## Summary block at the beginning of the file.
Debugging and IDE Health¶
| ID | ADR |
|---|---|
| 0001–0004 | hypotheses · agent/human parity · Debug mode · UI thread |
| 0011 | situational awareness |
| 0089, 0090–0091, 0095 | IDE Health naming · launch profiles · PFD debug deck · stratification Health |
Configuration and TOML¶
| ID | ADR |
|---|---|
| 0010, 0028–0029 | UI modes · settings.toml · TOML-first UI |
| 0030, 0040, 0050–0051, 0083, 0086 | commands/hotkeys · LSP presets · tools in TOML · intent routing · [ai] · topic UI |
Cockpit, CDS and Computing Circuit¶
| ID | ADR |
|---|---|
| 0021 | PFD/MFD - attention model |
| 0036, 0046–0047, 0066 | channel→CDS→surface · layout authority · instrument descriptor · cockpit vs presentation |
| 0063–0065, 0068, 0097 | instrument deck · deck primitives · taxonomy · payload vs projection · CCU |
| 0094, 0099 | ingestion bus · IDE DataBus |
Agent, MCP and indexing¶
| ID | ADR |
|---|---|
| 0008, 0016, 0038 | MCP contracts · ACP · agent facade |
| 0031, 0045, 0048, 0082, 0087 | chat · persistence · Cursor parity · loopback MCP · MAF |
| 0105–0106, 0118 | hybrid index · integration in CIDE · agent-notes 2.0 |
Graph, semantic map and navigation¶
| ID | ADR |
|---|---|
| 0039, 0053, 0062 | workspace navigation · control flow PFD · GitMap |
| 0067, 0113–0115 | graph-backed contract · HCI orientation · relation_kind · CDS graph layer |
Previews and documentation (Markdown)¶
| ID | ADR |
|---|---|
| 0023, 0026→0069 | language/diagrams · 0026 Superseded → 0069 |
Full index¶
| ID | Title | Status |
|---|---|---|
| 0001 | Storing debugging hypotheses in one JSON file | Accepted |
| 0002 | Single debug state layer for human and agent | Accepted |
| 0003 | Separate Debug UI mode (not Power cockpit) | Accepted |
| 0004 | Marshalling UI updates via IUiScheduler |
Accepted |
| 0005 | Set aside dynamic plugins (MEF and similar) | Accepted |
| 0006 | Layers, feature slices, role MainWindowViewModel |
Accepted |
| 0007 | Signals, connectivity, UI load | Accepted |
| 0008 | MCP Contracts and Testable Infrastructure | Accepted |
| 0009 | Strangler migration and exceptions for spike | Accepted |
| 0010 | UI mode data in TOML | Accepted |
| 0011 | Situational awareness in debugging (bar, hover; details in panel) | Accepted |
| 0012 | Floating and detachable chrome workspace (telemetry, stripes; not docks in v1) | Accepted |
| 0013 | Command surface and discoverability (palette, minimal toolbar) | Accepted |
| 0014 | Situational checklists (model, triggers, UI; parent - 0013) | Accepted |
| 0015 | TOML highlighting in the editor (tapped TextMate package taplo; not LSP in v1) | Accepted |
| 0016 | External agent for ACP (stdio, Cursor CLI); SDK vendor; UTF-8; orthogonal to MCP | Accepted |
| 0017 | Multiple application windows, screen areas, agent surfaces; MCP multi-root in scope | Accepted |
| 0018 | Canonical XML docs for IdeCommands and ProtocolDocGen (instead of mini-language only in summary) |
Accepted |
| 0019 | Common Git Core for Cascade IDE and git-mcp (logic parity, agent-notes-core use case) | Accepted |
| 0020 | Visibility of agent reasoning: layers (response, traces, optional log), fair restrictions of LLM providers | Proposed |
| 0021 | PFD/MFD - Cascade IDE Cockpit Attention Model | Accepted |
| 0022 | Visual Surface UI Development (AXAML/Blazor), WinForms Benchmark, MFD Hosting | Proposed |
| 0023 | Markdown + diagrams (Mermaid/PlantUML) - first-class experience through LSP and workflow | Proposed |
| 0024 | SDK for CascadeIDE - stable contracts for internal extension and future plugins | Proposed |
| 0025 | SDK: linking capabilities to attention zones (PFD/MFD/Forward/EICAS/HUD) | Proposed |
| 0026 | Markdown preview: surfaces and placement (workspace.toml); internal links (peek by “point N”/anchors); not to be confused with language ADR 0023 |
Superseded |
| 0027 | Narrow team (person + assistant) vs maturity “for discovery”: two axes (boundaries vs queue) | Accepted |
| 0028 | User settings: settings.toml, %LocalAppData%\CascadeIDE\, secrets in ai-keys.toml |
Accepted |
| 0029 | Configuration: TOML-first; holistic UI deferred settings; dot UI - canon façade | Accepted |
| 0030 | Layers command_id, hotkeys and UI: IdeCommands, palette, TOML, VM bridge; drawing of a unified catalog |
Accepted |
| 0031 | Agent chat: clarification packages, more complex yes/no answers, threads; not to be confused with PFD confirmations | Proposed |
| 0032 | HUD above the editor: custom content, grammar like presentation; EBNF to ADR, parser - according to DSL complexity |
Proposed |
| 0033 | i18n: ResX/.NET culture, Avalonia; UI strings are not in TOML as the main layer; pluralization - keys or library | Proposed |
| 0034 | Incapacitation, Emergency Mode; EICAS + PIC signals; liveness, contextual HUD, safety interlock; webcam/analysis MCP opt-in | Proposed |
| 0035 | Built-in browser in MFD (WebView2), external web LLM; trust boundary with MCP; hybrid via operator; bridge web↔MCP - beyond baseline | Proposed |
| 0036 | Channel → CDS → surface composer → surface; CDS as routing in the attention model (Agent-first) | Accepted |
| 0037 | PFD: surface invariants; Roslyn; canon [PfdStrict] / PfdStrictControl |
Proposed |
| 0038 | Agent facade: AiProviderManager, chat vs ACP vs standalone JSON loop; external MCPs; ideas for orchestration and tool-calling |
Accepted |
| 0039 | Workspace navigation; C# / .NET north-star (not polyglot v1); graph/semantic map; PFD/MFD; MCP: presets, kind_filter, subgraph |
Accepted |
| 0040 | LSP C#/Markdown: command line in settings.toml, presets, optional keys; env - open in ADR |
Accepted |
| 0041 | Protobuf vs JSON for agent/IDE messages: boundaries, criteria, hybrid; entry point (Proposed) | Proposed |
| 0042 | Pre-flight briefing: Planned Changes (intent + SA) and Review Before Apply (preview, semantic layer, rejection without garbage); state machine; orthogonal to “line-by-line trust” | Proposed |
| 0043 | MCP transport recovery parity (human ↔ agent), host boundary (Cursor) vs IDE; orthogonal ADR 0002 | Proposed |
| 0044 | Avalonia as a host (fuselage), custom chat rendering (Skia - hypothesis); model is primary, spike follows; see ADR 0031 | Accepted |
| 0045 | Persistence of chat history: append-only NDJSON events + metadata and projections; UI/render is not the source of truth | Accepted |
| 0046 | CDS: CockpitPresentationLayoutPolicy and P/F/M invariants; presentation as a source of truth for menus/MCP/modes/reactive layer |
Accepted |
| 0047 | Cockpit Instrument (Instrument): slot descriptor (CockpitInstrumentDescriptor), not Control; SE vs intent map as examples |
Accepted |
| 0048 | Chat via Cursor ACP in the IDE: mcpServers, auto IDE MCP; applications - body spaces, parsing mcp.json ↔ CIDE |
Accepted |
| 0049 | Step-by-step rollout of Skia-surfaces via CIDE with Avalonia-host; wave migration and dual-path | Accepted |
| 0050 | Declarative map "tool → zone/slot" in TOML | Accepted |
| 0051 | Intent-based attention routing (TOML) | Accepted |
| 0052 | CLI for agent contract (parity with MCP) and snapshot tests | Accepted |
| 0053 | Intent map and control flow on PFD (control flow, KISS, subgraph) | Accepted |
| 0054 | Performance benchmarks and baseline metrics for CIDE | Proposed |
| 0055 | General composition pipeline of Skia tools (Intent -> Declutter -> Layout -> Render) | Accepted |
| 0056 | Intent map: implementing a common Skia pipeline (composer, controlFlow layout, cursor semantics) | Accepted |
| 0057 | Chat surface: adoption of common Skia pipeline (threads, confirmations, dual-path rollout) | Accepted |
| 0058 | Pairing the agent and Roslyn MCP in settings.toml (limits, types of nodes, timeouts, presets) |
Proposed |
| 0059 | Roslyn Profiles MCP, Manager, Tactics (PFD) / EFB on MFD, Auto-Focus / Combat / Echelon | Proposed |
| 0060 | Chord layer (Ctrl+K), FMS-style, S/T, overlay; extension ADR 0013 | Accepted |
| 0061 | ADR context map ↔ paths in workspace.toml, indicator on PFD, intent/tooltip, agent advisory (GPWS for docks) |
Proposed |
| 0062 | GitMap: submodules and git boundaries separate from WSNC/intent map; general Skia pipeline; own contract/MCP; git-and-submodules-v1 | Proposed |
| 0063 | Instrument deck + ContentRepresentation; taxonomy of primitives (including Readout, Trend, Gauge, Presence); Presence/Activity vs Dark Cockpit; DedicatedPage - Page mode for WH, not deck |
Accepted |
| 0064 | Types of indicators deck: single graphical implementation; rendering library + semantic palette; without unnecessary architectural layer; DeckPrimitiveKind = view directory |
Accepted |
| 0065 | Tool categories and Graph types (graph_kind): domain orthogonal to slot/instrument_id; "Intent Map" = Code Intent Map; see table graph_kind |
Accepted |
| 0066 | Cockpit UI vs presentation IDE (chrome, overlays, theme): two pillars; do not mix fixtures/deck with shell; PrimitivesKit vs UiChrome |
Accepted |
| 0067 | Graph-backed surfaces: general contract for a family of graph screens (data, interaction, navigation, layout, selection, sync); intent map, GitMap, future graphs | Accepted |
| 0068 | Channel Row Payload vs View Projection vs Slot: table/strip ≠ cell type; v1 - one DTO; heterogeneity - discriminator and patterns | Accepted |
| 0069 | Markdown Preview: MFD tool as primary surface, native Markdig renderer first, WebView as optional adapter; authoring extension orthogonal to preview | Accepted |
| 0070 | Command Palette: direct overlay surface to host, routing to active TopLevel; ModalOverlay is not canon for palette baseline |
Accepted |
| 0071 | AI / IDE assistant: sovereignty, locality, invisibility; anti-pattern “cloud inline by default without control”; narrative - cascadeide-philosophy-v1 | Proposed |
| 0072 | Chat: topic cards, drill-in/back, adaptive default; intent-based Melody/Chords v1 for topic navigation; clarifies 0060 in chat-domain | Accepted |
| 0073 | PFD instrument deck: catalog of composition options (SA, code metrics, intent map, ADR indicator...); criteria "PFD vs on demand"; live draft before preset selection | Proposed |
| 0074 | Settings: more compact, anchor on MFD; lack of space in P+F+M - strategy table (scroll, min width, fallback window, ...) | Proposed |
| 0075 | UI: topic index UI/README.md; MFD page conventions (payload vs projection, keyboard-first); does not replace flat index |
Proposed |
| 0076 | UI/UX: center of principles - coherent text from snippets/ui/ (attention/cockpit, product philosophy); does not replace the original ADR |
Proposed |
| 0077 | TECH: principles center - coherent text from snippets/tech/ (boundaries/contracts, agent/debugging/observability); does not replace the original ADR |
Proposed |
| 0078 | Git preflight: noise control (EOL/BOM/whitespace), safe fixes, logical commit hints and post-push report | Accepted |
| 0079 | IDS (Ide Display System): IDE overlay pipeline (intent → composer → snapshot → surface), orthogonal to CDS; single input host and slots - according to plan; Roslyn CASCOPE013–016 | Accepted |
| 0080 | Intercom: product name of the communication channel instead of the narrow “chat”; agent + command + system replicas; external command circuit vs one’s own “mountain”; discoverability/i18n; strangler for code | Accepted |
| 0081 | Parametric Intent Melody: suffix :startLine:endLine for operations on editor text; validation; range refactorings; UX (indicator, chord vs palette) |
Accepted |
| 0082 | ACP + IDE MCP: one copy of the process - loopback HTTP/SSE instead of the second CascadeIDE --mcp-stdio; localhost security; stdio for external host save |
Proposed |
| 0083 | [ai] in settings.toml: mode = local | acp| mcp_only | cloud; nested sections; no backwards compatibility with old provider |
Accepted |
| 0084 | Agent's edits: the only text in the editor; chat - intent/status; presence layer (cursor, “writes”); diff in chat is not the main one; without mandatory CRDT | Proposed |
| 0085 | Editor HUD: inline layer in the editor (carriage, text, gutter) vs HUD banner (bar above the text); IDS overlays separately; banner config - 0032 | Proposed |
| 0086 | UI theme: brush canon in settings.toml; JSON for ide_get/set_ui_theme as transport; strangler Themes/*.json |
Proposed |
| 0087 | Microsoft Agent Framework (MAF): a guide to orchestration of the built-in agent loop; track. step - PoC | Accepted |
| 0088 | Host slot / region / deck cell - taxonomy of levels; do not mix | Proposed |
| 0089 | get_ide_state instead of get_workspace_state; IDE Health channel instead of Workspace Health; orthogonal ADR 0002 |
Accepted |
| 0090 | Launch profiles / multiple debugging startup configurations (like launch profiles in VS), storage, MCP, migration from startup-project.json |
Accepted |
| 0091 | Hypothesis: PFD instrument deck in debug mode - one Mfd page (DebugStack) may not be enough; PFD = Summary, Mfd = Details | Proposed |
| 0092 | Track Visual UI (markup designer): separate large program line; UX standard - 0022; priority Avalonia → Blazor → (optional) Razor | Accepted |
| 0093 | Extension 0090: optional built-in Kestrel URL view on MFD next to debug; the external browser remains default; WebView2 / cross-platform - in roadmap | Accepted |
| 0094 | Delivery bus in UI (analogous to AFDX): Channel<T>, batching, backpressure; orthogonal to the CDS “channel”; strangler from build log |
Proposed |
| 0095 | Three levels of Health: Workspace (folders, Git) · Solution (build, tests) · IDE (LSP, MCP, environment); taxonomy for channels/CDS/MCP; strangler from current IDE Health | Accepted |
| 0096 | Intercom: topic card = title + summary (card index); spine of the product line is orthogonal to the main thread (CIDE is an example); complements 0072 | Accepted |
| 0097 | Cockpit Computing Units (CCU), analogue of LRU Unit: raw material convolution → DTO/channel snapshot; orthogonal to 0094 (transport) and CDS; IDE Health in code - chain standard | Accepted |
| 0098 | Semantic-first: semantic map is primary; code/docs/git - projections; coordination with 0084 on the edit session; strangler | Proposed |
| 0099 | IDE DataBus: typed events in the IDE process; decoupling of sources and projections, without replacing 0094 (transport) and 0097 (CCU) | Accepted |
| 0100 | Constitution of the project: long-term principles, architectural invariants, governance and order of changes of the foundation of the project | Proposed |
| 0101 | Licensing and commercialization: license matrix, dependency rules, copyleft guardrails and implementation plan | Proposed |
| 0102 | Data Acquisition Layer (DAL): explicit external data acquisition boundary and contract DAL ↔ CCU ↔ UI | Proposed |
| 0103 | Editor HUD Substrate: SemanticProjectionPipeline / EditorHudEngine / IEditorSurfaceAdapter; DAL/CCU/DataBus; separate hi-freq bounded circuit; baselineAvaloniaEdit; comparison of hosts in design/, roadmap UI in ui-ux/ |
Accepted |
| 0105 | Hybrid codebase index: portable core + MCP for C#/Razor/AXAML (Roslyn true for C#); hybrid FTS+vec | Accepted |
| 0106 | Embedding hybrid index in CascadeIDE (DAL/CCU/DataBus/freshness) and Semantic Map border | Proposed |
| 0107 | Blank solution: dotnet new sln, menu/MCP, BlankSolutionCreator + IDotnetCommandRunner |
Accepted |
| 0108 | Web portal for external web AI: WebView, Host Object → IdeCommands/MCP; allowlist, consent; PoC (Atlas/Search AI) |
Accepted |
| 0109 | Intent Melody: target directory [[melody_root]] (shape + tail_signature); migration with [aliases]+[[parametric]]; args in code; plugins - processing by plugin |
Accepted |
| 0110 | Roslyn refactorings by range: Intent Melody/IDE ↔ Roslyn MCP bridge; no duplicate Features in the core; rmx/rix is not in the bundle before the bridge |
Proposed |
| 0111 | Editor: LineNumber / LineRange (1-based, Start ≤ End); ParsedLineRange; border to JSON - int in command args |
Accepted |
| 0112 | Palette (Ctrl+Q): line modes, strategies and workspace search backend contract (t:/m:/x:) with switching in settings |
Accepted |
| 0113 | HCI × Semantic Map: orientation; axes graph_kind / provenance / relation_kind; quick text referenced-by → Roslyn; SemanticMapInputSnapshot /CCU |
Proposed |
| 0114 | Relation type on edge (relation_kind): "inherits", "refers to", partial peer, text match; orthogonal to graph_kind and provenance; link to hit_kind |
Proposed |
| 0115 | CDS: general implementation layer of graph-backed instruments in the cockpit (not IDS); IGraphDataSource (v0); interface with 0036 and 0067 |
Accepted |
| 0116 | Intercom: session tree (branching, rewind, bookmark) and steer / follow-up when the agent is running; 0045, 0080, 0096 | Proposed |
| 0117 (SkiaKit) | SkiaKit: reusable Skia IDE primitives (sectioned cards, tile grid) | Accepted |
| 0117 | Remote operator surface: PWA-remote from a phone/other PC, Operator Gateway; not mobile IDE; 0017, 0108 | Proposed |
| 0118 | Agent Notes Core 2.0: TOML in-proc, config_path SSOT with MCP, knowledge_path in IdeCommands |
Accepted |
| 0119 | Chat as command line: Intercom (/card) + IDE (/build run, /test run, /debug launch); autocomplete, command_id |
Accepted · Implemented |
| 0120 | primary_work_surface: Intercom or Editor in Forward anchor (analogous to Agent/Editor in Cursor) |
Proposed |
| 0121 | IOP (Intent-Oriented Programming) paradigm — conceptual foundation; manifest | Accepted |
Assembly into one document (HTML, TXT, PDF)¶
Gluing together numbered ADRs and the same directives INCLUDE / INCLUDE_MANIFEST / INCLUDE_GLOB as in resume/ (without DOCX). Run from this directory: dotnet script build-adr.csx. Dependencies and output paths are in build/README.md.
Agreements¶
- Related ADRs: not a continuous paragraph in the header - section ## Related ADRs with the table
| ADR | Role |(template and rules in snippets). - File name:
NNNN-short-kebab-title.md, four digits with leading zeros. - Statuses: in the ADR header and in the “Status” column - see status-lifecycle.md. Briefly: first tag (Proposed / Accepted / Superseded / Deprecated); for a solution implemented in the code -
Accepted · Implemented(second tag via·). No subfolders by status - onedocs/adr/. - Thematic subfolders (not by status): optional index by topic - 0075 and
UI/README.md; TECH -TECH/README.mdand 0077. - The new ADR adds a row to the table above and, if necessary, a row to the table in architecture-policy.md.
Internal anchors and references (so that “see paragraph N” work as links)¶
The canon of the text is snippets/adr-anchors-policy.md (in the build-adr.csx assembly you can connect via {{ INCLUDE: snippets/adr-anchors-policy.md }} from adr-book.md).