| 1 | # ADR 0121: Intent-Oriented Programming (IOP) — conceptual foundation of Cascade IDE |
| 2 | |
| 3 | **Status:** Accepted |
| 4 | **Date:** 2026-05-17 |
| 5 | |
| 6 | ## Related ADRs |
| 7 | |
| 8 | | ADR | Role | |
| 9 | |-----|------| |
| 10 | | [0100](0100-project-constitution.md) | Constitution: agent-first, cockpit, shared operational model | |
| 11 | | [0013](0013-command-surface-and-discoverability.md) | Palette, keyboard-first, command discoverability | |
| 12 | | [0051](0051-intent-based-attention-routing-toml.md) | Intent-based attention routing (TOML) | |
| 13 | | [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md) | Intent-first: topic cards, Melody/Chords, `command_id` | |
| 14 | | [0080](0080-intercom-naming-and-multi-party-channel-model.md) | Intercom — session and intent channel | |
| 15 | | [0109](0109-declarative-parametric-melody-catalog-toml-and-code-binders.md) | Intent Melody catalog (declarative intent layer) | |
| 16 | | [0119](0119-chat-slash-commands-intercom-surface.md) | Intercom slash → same `command_id` as palette/MCP | |
| 17 | | [0120](0120-primary-work-surface-intercom-or-editor.md) | Forward anchor: Intercom or editor — where the IOP loop lives | |
| 18 | | [0122](0122-collaborative-iop-environment-and-shared-situational-display.md) | Environment: N `(P)(F)(M)` stations + shared room situational display | |
| 19 | | [0019](0019-shared-git-core-ide-and-git-mcp.md) | Git parity: human and agent in one loop | |
| 20 | | [0084](0084-agent-edits-editor-source-of-truth-presence-channel.md) | Editor — text source of truth; chat — intent/status | |
| 21 | |
| 22 | ### Outside ADR |
| 23 | |
| 24 | | Document | Role | |
| 25 | |----------|------| |
| 26 | | [iop-manifest-v1.md](../iop-manifest-v1.md) | Short IOP manifest for the site and onboarding | |
| 27 | | [architecture-policy.md](../architecture-policy.md) | Architecture policy, north-star, KB | |
| 28 | | [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) | IDE/MCP commands — intent execution | |
| 29 | | [intent-melody-language-v1.md](../../intent-melody-language-v1.md) | `c:` grammar (Melody), not chat slashes | |
| 30 | | [north-star-cursor-mcp-cascade-workbench-v1.md](../../design/north-star-cursor-mcp-cascade-workbench-v1.md) | “Cursor + MCP + Cascade” boundaries | |
| 31 | |
| 32 | ## Summary |
| 33 | |
| 34 | - Adopt **Intent-Oriented Programming (IOP)** as the **named product paradigm** of Cascade IDE: first of all a **discipline of communication** in the development contour (**working implementation of a proposed paradigm in the product**), not a replacement for OOP/FP. |
| 35 | - Three IOP pillars in CIDE: **intent over manual syntax** (intent layer), **two-loop verification** (agent synthesizes — human approves diff), **epistemic context** (KB canon and context routing as normative layer for the agent). |
| 36 | - Public wording for the team and site — [iop-manifest-v1.md](../iop-manifest-v1.md); this ADR is the normative link to existing decisions and non-goals. |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Context |
| 41 | |
| 42 | The agent-first IDE stack already has “intent-first” in individual ADRs ([0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md), [0055](0055-skia-instrument-composition-pipeline.md) Intent→…→Render), an **Intent Melody** catalog, **Intercom**, **MCP** and **Roslyn** parity. What is missing is a **single paradigm name** that: |
| 43 | |
| 44 | 1. explains to newcomers (including on probation) *why* the product is shaped this way, not as “VS + chat”; |
| 45 | 2. connects scattered ADRs into one mental model; |
| 46 | 3. honestly separates **hypothesis + working in-product implementation** from “the only industry standard” or “the spec reference implementation”. |
| 47 | |
| 48 | Team discussion (including with Atlas) proposed **IOP** alongside OOP and FP. The meaning runs deeper than UI commands: IT is about **information flow** (goals, intentions, processes, communication, transparency); software development is part of the flow, not the whole subject. Agents reinforced an old truth: without explicit intent and a shared picture, code and the team diverge into chaos. |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## Problem |
| 53 | |
| 54 | 1. **Shallow reading of IOP:** “the basic unit is intent” sounds like “more slashes,” although the point is **agreement on goals** in the team’s information contour. |
| 55 | 2. **Cognitive ceiling:** a human cannot hold 100k+ lines of a monolith as “one text in the head”; the human role is architecture and verification, not a manual syntax compiler. |
| 56 | 3. **Split contours:** without a shared paradigm it is easy to duplicate command parsing (chat slash vs Melody vs MCP) — see motivation in [0119](0119-chat-slash-commands-intercom-surface.md). |
| 57 | 4. **Weak agent context:** without KB canon and routing (`route_context`, playbooks) intents “drift”; we need an explicit **epistemic constraint** model, not prompt alone. |
| 58 | 5. **Marketing vs engineering:** without an ADR the term IOP risks sounding like a “revolution” declaration without ties to code and ADR statuses. |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## Decision |
| 63 | |
| 64 | <a id="adr0121-p1"></a> |
| 65 | |
| 66 | ### 1. Definition of IOP (Cascade IDE scope) |
| 67 | |
| 68 | **Intent-Oriented Programming (IOP)** is a way of organizing work in the IDE where: |
| 69 | |
| 70 | - the **subject** is an aligned **information flow** (goals, processes, communication, transparency), not program text alone; |
| 71 | - an **intent** is a *named agreement* on intention or target state in that flow (not syntax and not “yet another slash”); |
| 72 | - **execution** (including code generation) is delegated to the agent and infrastructure (MCP, build, Roslyn, git) under **human observability**; |
| 73 | - **correctness** is checked via **delta** (diff, diagnostics, tests) and **normative knowledge** (KB), not only “something was generated”. |
| 74 | |
| 75 | IOP in CIDE is a **discipline of communication** in an agent-first IDE (information flow made explicit and verifiable). **C#, projects, and the editor remain the source of truth** for program text ([0084](0084-agent-edits-editor-source-of-truth-presence-channel.md), [0098](0098-semantic-first-document-as-projection.md)). |
| 76 | |
| 77 | <a id="adr0121-p2"></a> |
| 78 | |
| 79 | ### 2. Three IOP pillars in Cascade IDE |
| 80 | |
| 81 | | Pillar | Meaning | In CIDE (existing / in flight) | |
| 82 | |--------|---------|-------------------------------| |
| 83 | | **1. Flow and explicit intent** | Aligned information flow; intent = agreement on goal/state | Intercom, topic cards, KB/ADR; Intent Melody, `command_id`, palette, [0119](0119-chat-slash-commands-intercom-surface.md) slashes → same contour as MCP; [0109](0109-declarative-parametric-melody-catalog-toml-and-code-binders.md) | |
| 84 | | **2. Two-loop verification** | Agent synthesizes; human is architect and diff arbiter | Forward (editor) / Intercom ([0120](0120-primary-work-surface-intercom-or-editor.md)); Roslyn MCP, build/test MCP, git MCP; human-in-the-loop on merge | |
| 85 | | **3. Epistemic context** | Normative layer over code — KB canon, router, policies | kb-public, agent-notes, `knowledge/` tree (`domains/` is a **repo path**, not a “domain” term); [architecture-policy](../architecture-policy.md), [0100](0100-project-constitution.md) | |
| 86 | |
| 87 | The manifest metaphor of an “intent compiler” is **not one binary** but the bundle: **Intercom + command surface + MCP + agent + IDE verification**. |
| 88 | |
| 89 | <a id="adr0121-p3"></a> |
| 90 | |
| 91 | ### 3. Working implementation in the product |
| 92 | |
| 93 | Cascade IDE is an **open working implementation** of the proposed IOP paradigm (**an in-product instance**, not an external-spec reference): IDE, Roslyn MCP, agent-notes, kb-public, documented at the [project site](https://ai-guiders.github.io/cascade-ide/). |
| 94 | |
| 95 | Wording such as “the whole world will switch to IOP”, “the world’s only compiler”, or **reference implementation** in the ISO/W3C sense is **not** part of this ADR — only a **working paradigm hypothesis** for the product and the AI-Guiders community. |
| 96 | |
| 97 | <a id="adr0121-p4"></a> |
| 98 | |
| 99 | ### 4. Terminology (glossary v0) |
| 100 | |
| 101 | | Term | Meaning in IOP/CIDE | |
| 102 | |------|---------------------| |
| 103 | | **Intent** | Named agreement on goal/target state in the information flow; in CIDE carriers include Intercom, KB, `command_id`, Melody, slash (not “atom = slash”) | |
| 104 | | **Intent Melody** | Declarative/parametric language binding intents to UI and hotkeys | |
| 105 | | **Intercom** | Session channel: dialogue, topic cards, slashes — forward surface for intents ([0080](0080-intercom-naming-and-multi-party-channel-model.md)) | |
| 106 | | **Verification loop** | Synthesis → diff/diagnostics/tests → human accept or rollback | |
| 107 | | **Epistemic context** | KB, agent-notes, router/playbooks, policies — meaning constraints for the agent | |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## Non-goals |
| 112 | |
| 113 | - **Do not** reduce IOP to slash commands, palette, or Melody — surfaces, not the paradigm. |
| 114 | - **Do not** replace OOP, FP, or C# in the user repo with “intents instead of code”. |
| 115 | - **Do not** autonomous merge to main without human-in-the-loop (see [0100](0100-project-constitution.md), git policies). |
| 116 | - **Do not** IOP without verification infrastructure (Roslyn/build/test/git) — otherwise it is chat only. |
| 117 | - **Do not** claim an ISO/ECMA standard; IOP here is a **product and architecture** frame for CIDE. |
| 118 | - **Do not** duplicate the body of [0119](0119-chat-slash-commands-intercom-surface.md) / [0109](0109-declarative-parametric-melody-catalog-toml-and-code-binders.md) — linking layer only. |
| 119 | - **Do not** promise “we will digest any inbound user stream” — IOP reduces communication chaos; it does not remove human attention limits. |
| 120 | |
| 121 | --- |
| 122 | |
| 123 | ## Risks and boundaries (honest) |
| 124 | |
| 125 | | Risk | IOP/CIDE response | |
| 126 | |------|---------------------| |
| 127 | | **Intercom = endless feed** | Intercom is a **communication hub around a goal** ([0080](0080-intercom-naming-and-multi-party-channel-model.md), [0120](0120-primary-work-surface-intercom-or-editor.md)), not a generic messenger; topic cards, spine, threads ([0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md), [0031](0031-agent-chat-clarification-batches-and-threading.md)) | |
| 128 | | **“We cannot handle the user stream”** | People cannot either without structure; the product **does not amplify** inbound noise — it **names intent** and separates synthesis from verification | |
| 129 | | **Agent does everything at once** | Human-in-the-loop, diff, non-goals on autonomous merge; slash/MCP are contracts, not message chaos | |
| 130 | |
| 131 | --- |
| 132 | |
| 133 | ## Consequences |
| 134 | |
| 135 | - **Intercom** in perspective — **communication hub around a goal** (people + agents → intent → implementation), see [0120](0120-primary-work-surface-intercom-or-editor.md), [0080](0080-intercom-naming-and-multi-party-channel-model.md). |
| 136 | - **Team environment** — multiple cockpits + **shared situational display** (not a chat feed), see [0122](0122-collaborative-iop-environment-and-shared-situational-display.md). |
| 137 | - New command/chat/MCP features are described as **intent surface extension** + **parity** + **verification**, referencing IOP pillars. |
| 138 | - Documentation site: block on [home](../index.md), [IOP manifest](../iop-manifest-v1.md), Russian copy at `docs/iop-manifest-v1.md`. |
| 139 | - On **Accepted** — one line in [architecture-policy.md](../architecture-policy.md) (goal/positioning) and glossary in [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) if needed. |
| 140 | - Onboarding (probation, contributors): manifest + [concept overview](../concept-overview.md) first, then ADRs by topic. |
| 141 | |
| 142 | --- |
| 143 | |
| 144 | ## Implementation maturity (at Accepted) |
| 145 | |
| 146 | | Pillar | Maturity | Notes | |
| 147 | |--------|----------|-------| |
| 148 | | Intent | Implemented (v1) | Melody, palette, MCP; [0119](0119-chat-slash-commands-intercom-surface.md) phases A–B; [0120](0120-primary-work-surface-intercom-or-editor.md) | |
| 149 | | Verification | Implemented (contour) | Editor, Roslyn/build/git MCP; UX completeness — roadmap | |
| 150 | | Epistemic context | Implemented (external stack) | kb-public, agent-notes-mcp; CIDE integration — [0118](0118-agent-notes-core-2-toml-and-knowledge-path.md) | |
| 151 | |
| 152 | --- |
| 153 | |
| 154 | ## History |
| 155 | |
| 156 | | Date | Change | |
| 157 | |------|--------| |
| 158 | | 2026-05-17 | Proposed: IOP paradigm, three pillars, manifest, CIDE working implementation. | |
| 159 | | 2026-05-17 | Softened positioning: “reference implementation” → “working implementation in the product”. | |
| 160 | | 2026-05-17 | IOP: avoid “knowledge domains”; `knowledge/domains/` — repo path only. | |
| 161 | | 2026-05-17 | IOP depth: information flow, communication/transparency; intent ≠ slash. | |
| 162 | | 2026-05-17 | Anchor wording: IOP = **discipline of communication** (“communication is the whole key”). | |
| 163 | | 2026-05-17 | Intercom as goal-centric communication hub; honest risks on message volume. | |
| 164 | | 2026-05-17 | Link to [0122](0122-collaborative-iop-environment-and-shared-situational-display.md) — environment vs application. | |
| 165 | |