build-coop-ide-gpui

name

build-coop-ide-gpui

description

Capstone/orchestration skill — build an M-Agent + N-Human cooperative IDE in Rust gpui (the Harbor): many agents and humans co-editing the same files as co-equal CRDT replicas, governed by claims/guard/salvage, across LAN/shared/remote harbors. The INDEX that dispatches into the sibling rust skills. Use when building the collaborative editor, the agent-fleet console, multiplayer editing with agents-as-peers, or any slice of the Harbor. Trigger on: cooperative IDE, collaborative editor, multiplayer editor, agents and humans co-editing, gpui IDE, Loro CRDT editor, harbor editor, claims/salvage, "build the cooperative IDE". NOT for: a single non-collaborative gpui screen (compose the siblings directly), web editors, or non-editor apps.

Build an M-Agent + N-Human Cooperative IDE in Rust gpui

This is the capstone: the whole-system skill for building the Harbor — an editor where M autonomous agents and N humans edit the same files at once, as co-equal replicas, on a native Rust gpui shell, governed by a daemon that already exists. It is an index/orchestration skill: it holds the architecture and dispatches each slice into the sibling rust skills. The thesis (from the battle plan) is the load-bearing wall: make the CRDT governable — Loro merges bytes, claims govern intent, the harbor card decides who may write the region at all.

DEPENDS ON (pull these as you work)

Sibling skill	Pull it when you're working on…
rust-gpui-motion	any transition/animation — pane expand, board/hop, the spawn→fullscreen→diff flow, presence pulses. The no-transform constraint lives here.
gpui-shaders	bespoke GPU surfaces — the living-harbor water, dithered chrome, sonar sweep, biofield.
sound-design-and-audio	the fleet audio cues (board/steer/hop/approve/fail) and how to ship them in Rust.
beautiful-gui-design	the visual system — hierarchy, semantic tokens, light/dark, contrast, the 8pt grid, a11y.
vello-parley-rendering / metal-text-pipeline	vector viz + bare-metal text/glyph rendering when you go below the widget layer.

Plus the canon docs: docs/strategy/harbor-editor-battle-plan.md (the spine) and docs/design/harbor-interaction-model.md (the Quay/board/steer interaction).

When to Use

• Building any part of the cooperative IDE / Harbor editor.
• Adding a new collaborative surface (editor, Quay, transcript, diff, commission).
• Wiring agents-as-peers, claims/conflict UX, salvage, or a harbor transport.

NOT for

• A single, non-collaborative gpui screen — compose the sibling skills directly.
• Web-based collaborative editors (different stack).
• Non-editor apps.

Decision Points

flowchart TD
  A[Working on the coop IDE] --> B{Which layer?}
  B -->|The FACE: panes, surfaces, interaction| L1[Layer 1 gpui shell → rust-gpui-motion, gpui-shaders, sound, beautiful-gui-design + ref 02]
  B -->|The TEXT: buffer, replicas, presence| L2[Layer 2 editor core on Loro → ref 03]
  B -->|GOVERNANCE: claims, guard, salvage| L3[Layer 3 coordination kernel = the daemon → ref 03]
  B -->|The WATER: LAN/shared/remote| L4[Layer 4 transport behind SyncTransport → ref 01/04]
  L1 --> P[Pick the phase in the roadmap → ref 04]
  L2 --> P
  L3 --> P
  L4 --> P

Core Rules

• Governable CRDT. Loro v1.13.x is the buffer; a claim is a presence range the guard can refuse to merge across. Bytes merge automatically; intent is governed above the CRDT.
• Agents are peers, not tools. Every actor (human or agent) is a Loro replica with a PeerID minted from its PD identity, rendered identically (cursor, claimed range, name), with provenance.
• Claims govern intent, not bytes. "Merges cleanly" ≠ "merges correctly" — surface logical conflict (POST /conflicts/predict) as a Conflicted/Gated band before a byte is written; never a silent auto-merge.
• Salvage is the wedge. A dead replica's op-log + claim persist and replay; a successor inherits and finishes. Build it, don't skip it — a buffer without salvage is a Potemkin editor.
• The daemon IS the collab server — no new sync backend. Loro Protocol over the existing tube; snapshots→/blob; op-log→immutable notes.
• Topology behind a trait. SyncTransport abstracts Shared (daemon HTTP+SSE) / LAN (iroh) / Remote (relay+E2E); the editor never knows which.
• Reuse, don't reinvent. Layers 1, 3, 4 assemble shipped PD assets; the only genuinely from-scratch cost is Layer 2's buffer.
• One motion owner per surface (see rust-gpui-motion). No UI merges without visual artifacts in the test plan (screenshot + motion clip) — full stop.

Failure Modes

Anti-Pattern: "Agents as tools, not peers"

Symptom: agents are a side-panel that edits for the human; no shared cursor/claim/provenance. Detection: agent edits don't appear as a replica in the buffer; no PeerID identity. Fix: make every agent a first-class Loro replica keyed to its PD identity (ref 03).

Anti-Pattern: "Trusting CRDT auto-merge for correctness"

Symptom: two actors edit the same symbol; it merges cleanly and silently produces wrong code. Detection: no claim/conflict layer above Loro; no /conflicts/predict call. Fix: claim-before-edit; predict overlap; render Conflicted band + nudge before any write (ref 03).

Anti-Pattern: "Building the editor before the coordination"

Symptom: a beautiful buffer with no claims/salvage — demos well, fails the moment two actors touch one file. Detection: P1 buffer done, P3 claims/salvage indefinitely deferred. Fix: the wedge IS coordination; sequence per the roadmap (ref 04); refuse the Potemkin editor.

Anti-Pattern: "Transport-first"

Symptom: weeks sunk into iroh/NAT traversal before the buffer or claims exist. Detection: P4/P5 work happening before P1–P3. Fix: abstract topology behind SyncTransport from day one but prove the buffer+coordination over the daemon bus first (ref 04).

Worked Example: add a collaborative surface end-to-end

Adding the Editor surface (battle plan P0→P1), composing the siblings:

1. Shell (Layer 1) — add SurfaceKind::Editor { path, region } to mux.rs; implement the object-safe Pane (one pane, two faces). Pull beautiful-gui-design for hierarchy/tokens, rust-gpui-motion for the open transition (no transform — layout-fraction zoom).
2. Text (Layer 2) — back it with one LoroDoc/LoroText; mint a PeerID from pd whoami; authorship gutter colored by replica (ref 03).
3. Governance (Layer 3) — claim the edited region; /conflicts/predict; paint overlap Tone::Conflicted; guard the commit; persist op-log for salvage.
4. Polish — pull gpui-shaders for the living-harbor water behind it; sound-design-and-audio for the board/approve cues.
5. Land — visual artifacts (screenshot + a board→steer→diff clip) in the PR test plan, per the standing rule.

Quality Gates (phased)

• Every actor is a Loro replica with a PD identity + provenance (agents = peers).
• Claims//conflicts/predict gate edits; logical conflict is surfaced, never silently merged.
• Salvage implemented (dead-replica op-log replays; claim inherits) — not deferred away.
• Daemon is the collab server (no new sync backend); topology behind SyncTransport.
• Build order respected (buffer+coordination before transport polish).
• Each surface composes the right siblings (motion/shaders/audio/visual-system).
• No UI merge without visual artifacts in the test plan.

Fork Guidance

Fork by layer: shell (ref 02 + the three visual siblings) · editor core (ref 03 / Loro) · coordination (ref 03 / daemon) · transport (ref 01/04). Keep the architecture (the four layers + the dependency map) in the parent so one actor owns coherence.

Reference Map

• references/01-architecture-and-the-stack.md — the whole-system view: the four layers (gpui shell → Loro editor core → coordination kernel → transport), the dependency map onto the sibling skills, what's load-bearing vs polish.
• references/02-the-gpui-app-skeleton.md — structuring a large gpui app: the mux/Workspace pane tree, the Pane/Surface contract, SurfaceKind variants, the refresh→channel→view pipeline; how to add a surface end-to-end.
• references/03-collaboration-coordination-salvage.md — the heart: agents+humans as co-equal Loro replicas, presence-as-claims, the daemon as collab server, conflict UX, agents-as-peers via MCP, salvage; the M×N model + three harbor topologies.
• references/04-build-order-and-composing-the-skills.md — the phased roadmap (P0 skeleton → P1 buffer → P2 LAN → P3 agents+claims → P3.5 salvage → P4 shared → P5 remote+viz), each phase naming which sibling skill it pulls; the "you are here / read next" map.

Sibling skills (dependencies): rust-gpui-motion, gpui-shaders, sound-design-and-audio, beautiful-gui-design, vello-parley-rendering, metal-text-pipeline.

Skill Bundle Index

Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.

references/

• references/01-architecture-and-the-stack.md — Architecture & The Stack — The Whole-System View — This is the load-bearing wall of the capstone.
• references/02-the-gpui-app-skeleton.md — The gpui App Skeleton — > Capstone reference 02 of the "Build an M-Agent + N-Human Cooperative IDE in Rust gpui" skill. > This is the structural chapter: how
• references/03-collaboration-coordination-salvage.md — Collaboration, Coordination & Salvage — the heart of the M×N IDE — This is the capstone's load-bearing chapter.
• references/04-build-order-and-composing-the-skills.md — Build Order & Composing the Skills — This is the index card for the whole capstone.