Build Coop Ide Gpui

---
license: Apache-2.0
name: build-coop-ide-gpui
description: 'Plan or audit the cross-layer Harbor cooperative editor: Loro replicas for humans and agents, governed edit claims, salvage authority, and transport across shared, LAN, and remote harbors. Use when a change spans editor collaboration, identity, recovery, or transport contracts. For a single GPUI pane use gpui-rust-console; for motion use rust-gpui-motion; for a shader use gpui-shaders. NOT for non-collaborative screens, web editors, or generic Rust development.'
allowed-tools: Read,Write,Edit,Bash,Grep,Glob
metadata:
  provenance:
    kind: first-party
    owners: [port-daddy]
  pairs-with:
    - skill: rust-gpui-motion
      reason: Owns every pane/board/hop transition and the no-transform constraint the coop-IDE shell composes for open/claim/conflict animations.
    - skill: gpui-shaders
      reason: Supplies the bespoke GPU surfaces (living-harbor water, dithered chrome, sonar sweep) the Harbor's visual-polish layer pulls in.
    - skill: vello-parley-rendering
      reason: Vector viz and Parley text layout for salvage/replica visualizations above the widget layer.
    - skill: metal-text-pipeline
      reason: Bare-metal glyph/text rendering when a coop-IDE surface drops below GPUI's text widget.
    - skill: gpui-rust-console
      reason: The Harbor's gpui shell (mux/Workspace pane tree, render-agnostic Pane/Surface contract) IS pd-console; this is the authoritative skill for that base app.
  io-contract:
    kind: deliverable
    consumes:
      - kind: feature-or-surface-requirement
        format: markdown
        description: A request to build or extend a cooperative-IDE feature or surface (e.g. "add a collaborative diff surface", "wire salvage for the editor pane") as reported by a human or another agent.
      - kind: coop-ide-architecture-plan
        format: json
        description: A structured plan describing the actors, claims/conflict handling, salvage, daemon-as-collab-server, transport topology, and sibling-skill composition for a coop-IDE surface, matching schemas/coop-ide-plan.schema.json.
    produces:
      - kind: phased-build-plan
        format: markdown
        description: A build plan sequenced by this skill's four layers and phased roadmap (P0 skeleton -> P5 remote+viz), citing which sibling skill each phase pulls (rust-gpui-motion, gpui-shaders, vello-parley-rendering, metal-text-pipeline, gpui-rust-console).
      - kind: architecture-audit-report
        format: json
        description: A deterministic pass/fail audit of a coop-ide-architecture-plan against this skill's phased Quality Gates and four anti-patterns, as produced by scripts/coop_ide_audit.mjs.
---

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

**Activation boundary:** use this when editor collaboration or recovery needs a decision across UI, CRDT, claims, and transport. A bounded pane, transition, or shader change can activate its owning sibling directly. This entry is the cross-layer architecture and authority contract, not a required wrapper for every visual edit.

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 critical 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… |
|---|---|
| **gpui-rust-console** | the shell itself — `core/pd-console`'s mux/Workspace pane tree, the render-agnostic `Pane`/`Surface` contract, or the reqwest↔smol refresh pipeline the Harbor is built on top of. |
| **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). <!-- cite-exempt: forward design+build target of this capstone skill (harbor-editor track); not a file in this bundle -->

## 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

```mermaid
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.
- **Actors and replicas are distinct.** Bind a verified principal to a distinct device/session incarnation. Never derive a PeerID from a principal or display name alone: two devices must not reuse one operation counter. DocumentRef, not an absolute path, identifies a shared document. Names are labels, not verification.
- **Claims govern intent, not bytes.** "Merges cleanly" ≠ "merges correctly". Enforce direct claim violations. Semantic intersection allegations remain advisory unless an authorized policy explicitly creates a gate; similarity or an unconfirmed prediction cannot block human editing by itself.
- **Authoritative recovery is the target wedge, not current functionality.** P3.5 requires daemon-owned typed receipts from sequence zero, sealed abandonment, canonical Rust Loro validation, and one atomic P3 claim transfer/token/provenance transaction. Current P2 snapshots, `/blob`, notes, generic salvage, and `apply_remote_ops` cannot authorize it. Build the missing authorities; never simulate them.
- **The daemon IS the collab server** — no new sync backend. Loro Protocol rides the existing tube; the canonical editor-sync contract owns checkpoint/reconnect behavior, while P3.5 salvage uses separate daemon-owned typed operation receipts. Notes are provenance, never replay evidence.
- **Topology behind a trait.** `SyncTransport` abstracts Shared (daemon HTTP+SSE) / LAN (iroh) / Remote (relay+E2E); the editor never knows which.
- **Reuse without overstating.** Layers 1, 3, and 4 assemble many shipped PD assets, but authoritative P3.5 editor recovery is still unimplemented. Layer 2's editor core and the missing recovery authorities remain real product work.
- **One motion owner per surface** (see rust-gpui-motion). **No UI merges without visual artifacts** in the test plan (screenshot + motion clip) — full stop.

## Current Implementation Truth

The authenticated `POST /editor/recovery/{request,prepare,replay,finalize}` routes are registered security scaffolding, not a usable Harbor recovery pipeline. The P1 Rust operation-receipt producer, P1B, canonical Rust Loro recovery adapter, and P3 same-database released-claim transfer adapter remain unimplemented external gates. Daemon scope minting also lacks the required verified worktree root device/inode witness, and production does not yet provide the content-hash/parser-generation symbol lease or daemon file-mutation generation authority. Keep the public routes 503-gated until all authorities exist. Finalization must retain the descriptors and both leases through P3 transfer, persist the exact root/file device+inode, content hash, and generations, seal that hash in provenance as `scope.canonical_content_hash`, and consume the mutation lease in the same transaction. That lease excludes daemon-authorized writers, not arbitrary OS processes; later governed edits must reject any stale persisted witness. Canonical editor-owned provenance and its append-only outbox do not authorize replay. Any post-commit projection read, attempt-log write, or local publication-receipt failure must preserve canonical 200 success and return the stable outbox ID with a truthful pending reason; restart retries the same sink-deduplicated key until one local receipt exists. Without an atomically idempotent derived-note sink, no drain is scheduled and the outbox remains durably pending without churn; with one, bounded startup/periodic passes retry the exact key. Never fall back to `sessions.addNote`, and do not add migration compatibility for unshipped intermediate schemas.

## 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 human/agent embodiment a distinct replica with verified principal/device/session provenance (ref 03). Do not hash a principal into one shared PeerID.

### 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)** — reuse the existing `EditorPane` and `HarborBuffer`; allocate a distinct replica incarnation, bind shared admission to verified principal/device/session authority, and route by DocumentRef. Never shell out to `pd whoami` or treat its label as verification.
3. **Governance (Layer 3)** — claim the edited region; `/conflicts/predict`; paint overlap `Tone::Conflicted`; guard the commit; record each validated operation in the typed salvage ledger.
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 pivotal 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):** `gpui-rust-console`, `rust-gpui-motion`, `gpui-shaders`, `sound-design-and-audio`, `beautiful-gui-design`, `vello-parley-rendering`, `metal-text-pipeline`.

<!-- BEGIN BUNDLE INDEX (auto: index_references.py) -->

## Skill Bundle Index

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

**root**
- [`CHANGELOG.md`](CHANGELOG.md) — UbuildUcoopUideUgpui — Changelog — - Brought to the agentic-family standard: added `io-contract`/`provenance`/`pairs-with` frontmatter - Added a deterministic audit helper (ma

**`examples/`**
- [`examples/sample-input.json`](examples/sample-input.json) — sample input (data/schema)

**`references/`**
- [`references/01-architecture-and-the-stack.md`](references/01-architecture-and-the-stack.md) — Architecture & The Stack — The Whole-System View — This is the central wall of the capstone.
- [`references/02-the-gpui-app-skeleton.md`](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`](references/03-collaboration-coordination-salvage.md) — Collaboration, Coordination & Salvage — the heart of the M×N IDE — This is the capstone's decisive chapter.
- [`references/04-build-order-and-composing-the-skills.md`](references/04-build-order-and-composing-the-skills.md) — Build Order & Composing the Skills — This is the **index card for the whole capstone**.

**`schemas/`**
- [`schemas/coop-ide-plan.schema.json`](schemas/coop-ide-plan.schema.json) — coop ide plan.schema (data/schema)

**`scripts/`**
- [`scripts/coop_ide_audit.mjs`](scripts/coop_ide_audit.mjs)

<!-- END BUNDLE INDEX -->