| 1 | # IOP — Intent-Oriented Programming |
| 2 | |
| 3 | **Intent-Oriented Programming (IOP)** is first of all a **discipline of communication** around development: not “slash commands reinvented,” but a way to agree on goals, processes, and changes so they stay **visible** to everyone in the contour (people, agent, artifacts). |
| 4 | |
| 5 | **Communication is the whole key.** With communication come aligned intent, transparency, and meaningful code; without it — local order in files and global chaos, which agents made painfully visible. IT is about **information flow**; writing software is only part of that flow. |
| 6 | |
| 7 | This text is an **IOP manifest**: why, what it is, what it is not, how to enter, pillars, session shape. An **ecosystem** (IDE, KB, concrete products) is an **application example**, not a synonym for the discipline — see [§ Example: Cascade ecosystem](#example-cascade-ecosystem). |
| 8 | |
| 9 | **How to enter:** you do not have to read the whole manifest first — [§ Two entry thresholds](#two-entry-thresholds). |
| 10 | |
| 11 | !!! info "Normative detail" |
| 12 | Non-goals and ADR links — [ADR 0121](adr/0121-intent-oriented-programming-paradigm.md) (Accepted). |
| 13 | Russian: [манифест IOP (RU)](../iop-manifest-v1.md). |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## Why IOP |
| 18 | |
| 19 | IT is **information** technology: the work is a **coherent flow of meaning** — who talks to whom, about what, toward which goals, with which processes, and what observers can see. Without communication and transparency, shipping code is pointless: local order in files, global chaos in the team. |
| 20 | |
| 21 | IOP centers **explicit intent** (goal, target state, agreed process) and an **observable execution delta**. Code in the repo stays the source of truth for the program; IOP is a **discipline of communication** in which code is the verifiable outcome of agreement, not a replacement for talking. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## What IOP is not |
| 26 | |
| 27 | - **Not** “zoomers invented `/build`” — slashes, palette, hotkeys are **surfaces** for one meaning. |
| 28 | - **Not** a replacement for OOP/FP: classes and functions remain; what changes is how the team **agrees on work** before and after edits. |
| 29 | - **Not** documentation for a specific product or KB: the manifest does not replace a knowledge-base guide, router, or IDE onboarding. |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Two entry thresholds |
| 34 | |
| 35 | From outside, IOP is often shown **already assembled** — as if philosophy and full infrastructure were required on day one. In practice many people started differently, and that remains normal. |
| 36 | |
| 37 | | Path | What it is | |
| 38 | |------|------------| |
| 39 | | **Curiosity** | A folder, one honest dialogue with the agent, one hypothesis — without a ready-made “system around it” | |
| 40 | | **Integrated** | An existing contour: product, canon, familiar surfaces — convenient for those already inside | |
| 41 | |
| 42 | Both converge on one discipline: **explicit intent**, **observable delta**, human and agent in one flow of meaning (artifacts, not side chat). The difference is **what you show first**, not “real” vs “lite” IOP. |
| 43 | |
| 44 | **A note on history (one reference, not a rule for everyone).** It began with conversation — “how do you even think?” — before canon or markers existed. The contour was not handed down: it was **built together** — human and agent, questions, disagreement, clarification. Then a shared file the agent could append between sessions. Later, separately, came the knowledge base, IDE, channels such as Intercom — a **consequence** of practice, not an entry ticket. The human stays captain; without the agent in the same loop, much of what we now call IOP would not have been shaped in time. |
| 45 | |
| 46 | Showing skeptics only the summit paints a false picture. Narrating the start as if everything already existed does too. |
| 47 | |
| 48 | --- |
| 49 | |
| 50 | ## Three pillars of IOP |
| 51 | |
| 52 | ### 1. Flow of meaning and explicit intent |
| 53 | |
| 54 | At the center is an **aligned information flow** (people, agent, artifacts, status). An **intent** is not a button — it is a **named agreement** on a goal or target state in that flow. One meaning can appear in chat, commands, ADRs — without scattered “worlds.” |
| 55 | |
| 56 | ### 2. Two-loop verification |
| 57 | |
| 58 | | Loop | Who | What | |
| 59 | |------|-----|------| |
| 60 | | **Synthesis** | Agent + tools | Edits, build, refactors, automation | |
| 61 | | **Verification** | Human | Diff, tests, diagnostics, deliberate acceptance | |
| 62 | |
| 63 | Infrastructure keeps intent inside project “physics”; the human is captain at verification. |
| 64 | |
| 65 | ### 3. Epistemic layer |
| 66 | |
| 67 | Beyond code and types — **canon and context routing** so intent is not held only in memory and the last chat message. How canon is structured in a given environment is **implementation** (use case), not the manifest. |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## Agent before implementation |
| 72 | |
| 73 | In IOP the agent helps **before** commit and heavy automation: walk corners, push back, narrow scope — without waiting on a colleague. That does not replace human review or auto-write ADRs: the operator stays captain. |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | ## Honestly about human message volume |
| 78 | |
| 79 | IOP does **not** promise “we will handle any inbound stream” — **people do not handle that either** when everything lands in one endless feed. The bet is to **structure** communication, not amplify noise: |
| 80 | |
| 81 | - **lines of work** instead of one chaotic chat; |
| 82 | - **clarification batches** and threads, not every message = an immediate autonomous sprint; |
| 83 | - **one meaning** across surfaces — less “wrote in chat / did in palette / agent missed it”; |
| 84 | - **verification** — the human arbitrates **delta**, not every token. |
| 85 | |
| 86 | If communication is not structured, neither agents nor IDEs will save the day. IOP is about structuring it **first**. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Session shape |
| 91 | |
| 92 | ```mermaid |
| 93 | flowchart LR |
| 94 | subgraph intent ["Intent"] |
| 95 | I["Agreement surface"] |
| 96 | end |
| 97 | subgraph synth ["Synthesis"] |
| 98 | A["Agent + tools"] |
| 99 | end |
| 100 | subgraph verify ["Verification"] |
| 101 | H["Human: delta, tests, accept"] |
| 102 | end |
| 103 | subgraph knowledge ["Epistemics"] |
| 104 | K["Canon / context"] |
| 105 | end |
| 106 | I --> A |
| 107 | K -.-> A |
| 108 | A --> H |
| 109 | H -->|"accept / refine"| I |
| 110 | ``` |
| 111 | |
| 112 | --- |
| 113 | |
| 114 | ## Example: Cascade ecosystem |
| 115 | |
| 116 | A **use case**, not the definition of IOP. [Cascade IDE](https://github.com/AI-Guiders/cascade-ide) is an open **working implementation** of the discipline for .NET: agent-first IDE, in-proc MCP, KB canon ([kb-public](https://github.com/AI-Guiders/kb-public), agent-notes). Other stacks (Cursor + MCP, your own product) can carry the same pillars differently. |
| 117 | |
| 118 | **Agile in spirit (not Scrum):** short cycles, inspect and adapt, cooperation over blame — the same habit family as the [Agile Manifesto](https://agilemanifesto.org/), with a wider team (people + agent) and this discipline named **IOP** (manifest separate from framework — as Agile is from Scrum). A public narrative that the workspace already lives this way — [article on KDGIO](https://karataevdmitry.github.io/writing/agent-workspace-agile.html). |
| 119 | |
| 120 | ### How the pillars map to the stack |
| 121 | |
| 122 | | IOP pillar | In the Cascade ecosystem | |
| 123 | |------------|--------------------------| |
| 124 | | Flow and intent | Intercom, topic cards, ADR/KB, `command_id`, Intent Melody (`c:`), slashes ([0119](adr/0119-chat-slash-commands-intercom-surface.md)), palette, same commands via MCP | |
| 125 | | Verification | Diff in Forward, Roslyn diagnostics, tests, deliberate merge | |
| 126 | | Epistemics | `knowledge/`, router, [SHOWCASE](https://github.com/AI-Guiders/kb-public) — **KB guide**, not this manifest | |
| 127 | |
| 128 | ### Intercom |
| 129 | |
| 130 | **Intercom** ([ADR 0080](adr/0080-intercom-naming-and-multi-party-channel-model.md)) — not a “chat widget” but the **communication hub around a goal** in this use case. [0120](adr/0120-primary-work-surface-intercom-or-editor.md): `primary_work_surface = intercom` when connection is the forward anchor. Design — [intercom-design-hub](../design/intercom-design-hub-v1.md); agent as sparring — [philosophy §8](../design/cascadeide-philosophy-v1.md#8-агент-как-партнёр-для-проектирования-до-кода). |
| 131 | |
| 132 | ### Team environment (perspective) |
| 133 | |
| 134 | Not only an IDE window: PFD / Forward / MFD ([0017](adr/0017-multi-window-workspace-and-agent-surfaces.md)), shared room display ([0122](adr/0122-collaborative-iop-environment-and-shared-situational-display.md) Proposed). The screen gets **what you already agreed on** — not a transcript of everything said aloud. |
| 135 | |
| 136 | Product onboarding (not IOP): [handbook §1.1](../design/cide-design-handbook-v1.md#11-two-entry-thresholds-cide). |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## Read next |
| 141 | |
| 142 | | If you want… | Document | |
| 143 | |--------------|----------| |
| 144 | | **IOP (manifest)** | this file · [ADR 0121](adr/0121-intent-oriented-programming-paradigm.md) | |
| 145 | | **Agile in spirit (human–agent)** | [KDGIO: human–agent workspace](https://karataevdmitry.github.io/writing/agent-workspace-agile.html) | |
| 146 | | **Cascade ecosystem (use case)** | [§ above](#example-cascade-ecosystem) · [handbook](../design/cide-design-handbook-v1.md) · [ADR navigator](site/adr-nav/index.md) | |
| 147 | | **KB (separate from IOP)** | [kb-public / SHOWCASE](https://github.com/AI-Guiders/kb-public) | |
| 148 | | UI layout, Melody, agent-first policy | [UI layout](ui-ux/cascade-ide-ui-layout-v1.md) · [intent-melody](../intent-melody-language-v1.md) · [architecture-policy](architecture-policy.md) | |
| 149 | |
| 150 | --- |
| 151 | |
| 152 | *Cascade IDE — MIT · [GitHub](https://github.com/AI-Guiders/cascade-ide) · [AI-Guiders](https://ai-guiders.github.io/)* |
| 153 | |