---
name: lumbridge-development
description: Build, test, review, benchmark, or document Lumbridge, the native Rust local-first IDE, terminal multiplexer, and agent workspace.
---

# Lumbridge Development

Work from the Lumbridge repository root. Read `AGENTS.md`, then only the product
documents relevant to the task:

- architecture or persistence: `docs/ARCHITECTURE.md` and `docs/decisions/`;
- product behavior: `docs/PRODUCT_SPEC.md`;
- tests: `docs/TESTING.md`;
- native UI work: `docs/UI_OPTIONS.md` and `docs/UI_SPIKE_SCORECARD.md`;
- Buzz work: `docs/BUZZ_INTEGRATION.md`.

Preserve these product boundaries:

- The application shell, terminal, editor, runtime, and state model are native
  Rust. Do not introduce Electron, React, TypeScript, or a webview shell.
- Data is local-first. SQLite contains metadata and history, never API keys,
  subscription tokens, SSH private keys, Buzz private keys, or Tailscale keys.
- Remote PTYs live in a per-user runtime on the user's remote machine. OpenSSH
  and Tailscale are transports over access the user already configured; do not
  change tailnet ACLs, copy credentials, or open public listeners.
- macOS, Ubuntu, and Omarchy/Arch are release targets. A Linux-only success is
  not cross-platform proof.
- Usage and quota values always retain provenance and uncertainty.

## Development loop

Before editing, inspect Git status and preserve unrelated work. Use:

```bash
bacon
cargo xtest
./scripts/ci.sh
```

Root CI must remain independent from experimental UI dependencies. GPUI and
Floem live in separate workspaces under `spikes/` and consume the same
`ui-shell-model` fixture. Record only observed results in the scorecard; do not
select a framework until both pass the hard gates.

For Buzz integration, use its Apache-2.0 Rust SDK and signed protocol semantics
rather than inventing a webhook dialect. Test against a local relay and fixture
identity. Pane screenshots or transcripts require a visible preview, redaction,
explicit destination, and user confirmation before upload.

Add tests at the lowest deterministic layer first, then platform or rendered
tests where behavior crosses a real boundary. Before handoff, run the relevant
spike build plus `./scripts/ci.sh`, `git diff --check`, and report anything not
validated on all target systems.