| 1 | <!-- English translation of adr/0027-small-team-focus-vs-public-maturity.md. Canonical Russian: ../../adr/0027-small-team-focus-vs-public-maturity.md --> |
| 2 | |
| 3 | # ADR 0027: Small Team (Human + Assistant) vs “Open” Maturity — Two Axes, Not One Queue |
| 4 | |
| 5 | **Status:** Accepted |
| 6 | **Date:** 2026-04-08 |
| 7 | **Updated:** 2026-04-08 — Accepted; discoverability and axis B triggers. Details — [§ History](#adr0027-history). |
| 8 | |
| 9 | ## Related ADRs |
| 10 | |
| 11 | | ADR | Role | |
| 12 | |-----|------| |
| 13 | | [0024](0024-ide-sdk-and-stable-contracts.md) | Contracts and boundary discipline without promising SemVer “tomorrow” | |
| 14 | | [0005](0005-defer-dynamic-plugins-mef.md) | Deferred plugin host | |
| 15 | | [0013](0013-command-surface-and-discoverability.md) | Discoverability — separate axis from core speed | |
| 16 | | [0010](0010-ui-modes-toml-configuration.md) | TOML as honest configuration layer | |
| 17 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | Canonical path and format for user `settings.toml` and secrets | |
| 18 | | [0029](0029-configuration-toml-canonical-ui-facade.md) | TOML-first; holistic settings UI deferred; point UI = canon facade | |
| 19 | |
| 20 | ### Outside ADR |
| 21 | |
| 22 | | Document | Role | |
| 23 | |----------|------| |
| 24 | | [README](README.md) | Policy: major direction changes — separate commit + ADR | |
| 25 | | [onboarding-first-run-v1](../../design/onboarding-first-run-v1.md) | Living first-run/onboarding sketch — **not** required for “opening the repo” per this ADR; reference when deliberately deepening UI | |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Context |
| 30 | |
| 31 | CascadeIDE targets a **mature desktop IDE** that can be **opened** to other developers and integrators. In parallel, actual delivery speed today relies on a **very small “team”**: author(s) plus assistant (LLM) in paired work. |
| 32 | |
| 33 | Without an explicit split, risk is: |
| 34 | |
| 35 | - **Spreading thin** — building “store-ready” (onboarding, external-tool installers, polished settings UI) and losing core velocity; or |
| 36 | - **Boundary debt** — shipping “for ourselves only” and rewriting contracts, config paths, and integrations at the first external consumer. |
| 37 | |
| 38 | We need **one recorded model**: how to combine long-term openness and short-term focus without contradiction. |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## Decision |
| 43 | |
| 44 | Separate two independent dimensions — **product shape** and **delivery queue**. |
| 45 | |
| 46 | ### 1. Axis A — “shape” (boundary maturity) |
| 47 | |
| 48 | **Invest early** in what is expensive to change later: |
| 49 | |
| 50 | - stable **extension contracts** and protocols (per [0024](0024-ide-sdk-and-stable-contracts.md): layers, capabilities, out-of-proc integrations); |
| 51 | - **one source of truth** for configuration (global `settings.toml`, repo `workspace.toml`, etc. — [0010](0010-ui-modes-toml-configuration.md)); |
| 52 | - **ADRs** and navigator ([architecture-policy.md](../../architecture-policy.md)) on direction changes — so external readers and future-you see *why*, not only *what* in code. |
| 53 | |
| 54 | This is **not** a commitment to full onboarding or marketing packaging today; it **is** a commitment **not to break trust in boundaries** without an explicit step. |
| 55 | |
| 56 | ### 2. Axis B — “queue” (what the human–assistant pair ships in the sprint) |
| 57 | |
| 58 | **Hard-prioritize** what delivers value to **current** process users (including paired assistant work): debugging, editor, diagnostics, LSP, predictable file paths. |
| 59 | |
| 60 | **Deferred backlog** (see **triggers** below) for typical “store” items when they **do not** unblock core: |
| 61 | |
| 62 | - standalone settings app, heavy external-server installer from IDE, extended first-run wizard; |
| 63 | - discoverability polish for strangers ([0013](0013-command-surface-and-discoverability.md) remains direction, **not** a core-speed blocker). |
| 64 | |
| 65 | **Minimally sufficient** discoverability for “opening the repository” on axis B: **documentation** (including TOML and config paths), **examples** in the repo, **ADRs** with rationale — no objection as v1 baseline; full UI wizard not required until a trigger fires. Richer first-run/onboarding when the queue allows: sketch [onboarding-first-run-v1](../../design/onboarding-first-run-v1.md) — **not** part of this ADR’s minimum, a place for future work. |
| 66 | |
| 67 | ### Triggers: when to pull deferred axis B work |
| 68 | |
| 69 | Raise “for strangers” tasks (wizards, installers, strong discoverability polish) from the deferred backlog **deliberately** when **at least one** holds: |
| 70 | |
| 71 | 1. **First external contributor** (outside current repo authors) with a real PR/issue — signal that “clone and build” is tested in a foreign context. |
| 72 | 2. **Release candidate** or explicit milestone “showing the build wider than ourselves”. |
| 73 | 3. **Explicit pain or request** from user/integrator (including recurring) — do not wait for “store” if it already hurts. |
| 74 | 4. **Infrastructure necessity** — axis B task unblocks core or tests (then it is not “audience only”, a mixed payment; see §3). |
| 75 | |
| 76 | Until a trigger fires, the queue stays on core and boundaries (axes A and “our” users). |
| 77 | |
| 78 | ### 3. Rule for reconciling axes |
| 79 | |
| 80 | - If work **strengthens boundaries** (contract, protocol, file format) — take it **earlier**, even with a small team. |
| 81 | - If work **only reduces friction for strangers** — take it **after** core is stable for “our” users, or when a **trigger** from §2 fires. |
| 82 | |
| 83 | ### 4. Explicit heuristic for chat / review |
| 84 | |
| 85 | For any large effort ask: *“Is this axis A (boundaries) or axis B (audience)?”* |
| 86 | If both — split into two commits/approaches by meaning (logical commit policy in repo Cursor rules). |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Consequences |
| 91 | |
| 92 | - **Planning:** issues/notes may label `boundary` vs `audience-friction` (names repo discretion); do not mix “must ship for open” without naming the axis. |
| 93 | - **SDK and [0024](0024-ide-sdk-and-stable-contracts.md):** “small team” does **not** waive contract discipline; contracts save human+assistant time on boundary alignment. |
| 94 | - **Open source and “IDE for others”:** readiness is not only wizard count but **predictable** configs, documented decisions, testable boundaries — compatible with a small team if the queue is honest. |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | ## Rejected alternatives |
| 99 | |
| 100 | - **“Hack for ourselves first, re-layer for people later”** — rejected: expensive boundary rewrites; axes A/B separate “fast inside” from “careful outside” without rejecting the latter. |
| 101 | - **“Maturity = mass-market UI now”** — rejected: mixes axes and kills core throughput with small bandwidth. |
| 102 | - **“While there are two of us, ADRs are unnecessary”** — rejected: ADRs are cheaper for a pair than oral memory and assistant session drift. |
| 103 | |
| 104 | --- |
| 105 | |
| 106 | ## Change history |
| 107 | |
| 108 | <a id="adr0027-history"></a> |
| 109 | |
| 110 | | Date | Change | |
| 111 | |------|--------| |
| 112 | | 2026-04-08 | Accepted; clarified minimum discoverability (docs + examples + ADR, onboarding sketch link); added **triggers** for pulling axis B from backlog. | |
| 113 | |