| 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:
- 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).
- Text (Layer 2) — back it with one
LoroDoc/LoroText; mint a PeerID from pd whoami; authorship gutter colored by replica (ref 03).
- Governance (Layer 3) — claim the edited region;
/conflicts/predict; paint overlap Tone::Conflicted; guard the commit; persist op-log for salvage.
- Polish — pull
gpui-shaders for the living-harbor water behind it; sound-design-and-audio for the board/approve cues.
- Land — visual artifacts (screenshot + a board→steer→diff clip) in the PR test plan, per the standing rule.
Quality Gates (phased)
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/
