Scaffold Lumbridge architecture and research plan

2026-08-31 14:37:49 -07:00
commit 8971ddcf58
19 changed files with 840 additions and 0 deletions
@@ -0,0 +1,84 @@
+# Product specification
+
+## One sentence
+
+Lumbridge is a high-performance, local-first terminal and workspace multiplexer
+that lets engineers run, steer, compare, and understand many coding agents
+without surrendering control of their accounts, keys, repositories, or shells.
+
+## Primary user
+
+An engineer who works across several repositories and routinely keeps multiple
+coding agents, shells, test watchers, servers, and review surfaces alive at once.
+The product should feel faster and calmer as concurrency rises.
+
+## Core jobs
+
+1. Open a repository and create a durable workspace with terminals and panes.
+2. Launch a supported harness through its subscription login or a BYOK profile.
+3. See whether each agent is working, waiting, blocked, complete, or disconnected.
+4. Steer work without losing terminal fidelity or bypassing approval prompts.
+5. Review file and Git changes by workspace or worktree.
+6. Understand usage, rate-limit windows, burn rate, and likely exhaustion time.
+7. Resume the entire workspace after the UI or machine restarts.
+
+## Initial harnesses
+
+- Claude Code
+- OpenAI Codex
+- DeepSeek Harness
+- Pi and compatible Pi distributions
+- Hermes Agent
+- OpenClaw
+- Goose
+- Gemini CLI
+- OpenCode
+
+An arbitrary command remains a supported harness through the generic PTY adapter.
+
+## Provider modes
+
+Subscription mode delegates authentication to the installed upstream harness.
+Lumbridge observes only documented status, usage, and protocol surfaces.
+
+BYOK mode supports OpenAI, Anthropic, Google Gemini, Groq, Cerebras, DeepSeek,
+and OpenAI-compatible endpoints. Keys live in the operating-system credential
+store. A provider adapter receives an opaque secret handle, never a value stored
+in project state.
+
+Provider and harness selection are independent. For example, a generic harness
+may use Cerebras by API key while Codex uses a ChatGPT subscription.
+
+## Usage footer
+
+The footer answers five questions in a glance:
+
+- Which harness, provider, model, and account profile is active?
+- How much of the current usage window has been consumed?
+- When does the window reset?
+- What is the recent and projected burn rate?
+- How trustworthy is the number?
+
+Every value is labeled internally and in detail views as provider-reported,
+harness-reported, locally measured, estimated, or unavailable. Lumbridge must
+not scrape browser cookies or reverse-engineer private account APIs to manufacture
+an exact remaining balance. When only local observations exist, the UI says so.
+
+## Non-goals for the first release
+
+- A new foundation-model training or inference service.
+- A hosted account or mandatory Lumbridge cloud.
+- Replacing every coding harness with one Lumbridge-owned agent loop.
+- Windows support.
+- Mobile control, collaborative cloud sessions, or remote execution.
+- Bundling third-party subscriptions or reselling model tokens.
+
+## Experience principles
+
+- Terminal truth first: no hidden process state and no fake terminal emulation.
+- Keyboard fast, mouse understandable.
+- Dense information with a quiet default presentation.
+- Approval and security boundaries stay visible.
+- Local and offline workflows remain useful.
+- Estimates are useful only when their uncertainty is honest.
+