# Spec 000: Godloop v2 system overview Status: draft revision 1 for review Date: 2026-08-08 Target: `dev.godloop.ai`; production v1 remains untouched ## Product sentence Plan in Masterplan, talk in General Chat or a shared Project, connect a Space, work live with agents, and save useful work as a reusable Loop. Godloop should feel like one contextual development room, not a collection of runners, dashboards, schedulers, and chat modes. ## The whole system ```text people ── Masterplan + General Chat + shared Project ── Godloop v2 │ durable commands + events │ user-owned Space connector │ Herdr + Git worktrees + Crabbox │ live chats + typed results │ review now, Loop later ``` Godloop owns product truth and collaboration. Herdr owns live local agent sessions. Git owns changes. Crabbox owns isolated compute. The Space connector translates between them without becoming another product database. ## Specification map [Spec 001: shared state and live Work](spec-001-core-and-live-work.md) owns projects, conversation scopes, durable state, events, reconciliation, SSE, and the collaborative browser. [Spec 002: isolated execution](spec-002-sandboxed-execution.md) owns one coding execution's worktree, Crabbox environment, Herdr endpoint, result handoff, review, and cleanup. [Spec 003: FirstMate from General Chat](spec-003-agent-orchestration.md) owns the custom FirstMate profile, its small crew API, agent-to-agent communication, supervision, limits, and human intervention. [Spec 004: Masterplan and shared context](spec-004-masterplan-and-context.md) owns personal and project plans, timeline UX, revision-safe collaboration, and the bounded planning context agents receive. [Spec 005: Loops and integration hooks](spec-005-loops-and-integrations.md) owns reusable command recipes, ordered Godloops, Telegram, webhooks, the outbox, and their small project GUI. [Spec 006: coexistence and cutover](spec-006-coexistence-and-cutover.md) owns v1 preservation, migration inventory, rehearsals, deployment separation, cutover, and rollback. If a rule appears in more than one spec, one copy must be replaced by a link to its owner. ## Product surfaces `General Chat` is private. It handles ordinary questions and is where a user can select the FirstMate kind. Real work becomes project-scoped before a Space or repository is touched. `Project` is shared. It owns members, contributed Spaces, Work chats, agent executions, results, review, and future Loops. `Work` is the live projection of project activity. Each human or agent conversation is a chat; active agents also expose status and terminal observation. `Masterplan` is the shared map of outcomes and sequence. It provides context to people and agents but never becomes another task runner. `Loop` is a saved command formula over the same execution path. It is not part of the first build and will not receive a second runner. ## Small vocabulary - `Project`: collaboration and authorization boundary. - `Space`: a user-owned connector to one execution environment. - `Conversation`: private or project-shared ordered messages. - `Command`: validated intent from a human, agent, or future Loop. - `Execution`: one durable unit of work. - `Result`: typed outcome, artifacts, evidence, and effects. - `Event`: committed fact used for replay and live updates. - `Profile`: instructions and capabilities for an agent kind such as FirstMate. - `Plan Node`: a personal or project-linked outcome, milestone, or task. - `Loop`: a reusable command recipe; a Godloop is an ordered set of Loops. These nouns are shared by interactive work and future automation. Transports, UI components, Herdr calls, and integrations remain adapters. ## Architecture rules 1. One Go monolith, one Vue client, and one SQLite database until measured load proves otherwise. 2. One application command path for every mutation. 3. Canonical state and its event commit in one transaction. 4. One replayable SSE path plus an in-process wakeup hub; no polling as primary synchronization and no external broker. 5. Project membership is checked in the resource query. A Project is never reduced to one owner's user ID. 6. A Space owner explicitly contributes execution capacity. Collaboration does not silently share a machine or credentials. 7. Herdr is the live terminal/agent runtime, not product truth. 8. A worktree isolates changes; Crabbox isolates compute. Neither substitutes for the other. 9. Agents receive scoped Godloop crew tools, not raw Herdr or Crabbox control. 10. A typed Result exists before review or apply. Terminal text and process exit are evidence, not success. 11. FirstMate is a profile over the shared agent loop, not another service or orchestration engine. 12. Production v1 is a compatibility reference only. V2 never reads or writes its database. ## Deliberately absent - ADK, the direct runner, hosted mutation, and draft/personalization pipelines; - microservices, Redis, NATS, Kafka, Kubernetes, or a second database; - separate interactive and automation engines; - repository-controlled sandbox escape hatches; - marketplace, billing redesign, v1 migration, or multi-provider abstraction; - speculative agent kinds, recursive swarms, and configurable workflow builders; - freeform canvas coordinates, arbitrary integration plugins, and nested Godloops; - a UI refresh button as a state propagation strategy. Less Is More means a feature must reuse the nouns and command path above or wait. ## First end-to-end path 1. A user selects an active project outcome in Masterplan. 2. The user opens General Chat, selects FirstMate, and chooses that Project and its explicitly contributed Space. 3. FirstMate receives the bounded project-plan context, creates one Command, and dispatches at most two child agents. 4. Herdr shows each child in the user's workspace; Work shows the same children to every project member without refresh. 5. A writing child runs under Spec 002, while a read-only child may use an immutable snapshot. 6. Agents may message or call another permitted agent through the same scoped crew API. 7. Typed results wake FirstMate, remain inspectable in Work, require review before apply, and may update linked plan progress through an attributed command. 8. Save a useful result as a Loop and receive its later blocked/completed event through an explicitly configured Telegram or webhook subscription. 9. Restart the browser, server, connector, or Herdr session; durable state reconciles without duplication. That path is the product spine. Features that do not improve or reuse it are not part of the initial rewrite. ## Build order 1. `foundation`: empty Go/Vue app, SQLite migrations, auth boundary, private General Chat, Project membership, snapshot, and SSE. 2. `live Work`: one Space connector mirrors Herdr agents into shared chats. 3. `Masterplan`: add project context and the responsive planning surface over the same event path. 4. `isolated execution`: pass Spec 002's feasibility gate before depending on Crabbox for coding work. 5. `FirstMate`: fake adapter first, then one real read-only child, one writing child, and finally bounded agent-to-agent work. 6. `Loops and hooks`: only after the interactive path is useful and stable, save a command formula and project event subscriptions over the same contracts. 7. `transition`: rehearse import and rollback before any v1 cutover. Each step is one vertical slice with migrations, focused tests, reconnect and idempotency coverage, and one browser acceptance path. Do not scaffold later steps early. ## Review gate Before implementation begins, all seven specs should agree on: - General Chat versus Project privacy; - one active contributed Space per Project initially; - Herdr/Crabbox feasibility and failure behavior; - FirstMate's four crew tools and hard limits; - Masterplan scope, responsive UI, and agent context boundary; - the minimal Loop/Godloop model and integration subscriptions; - v1 preservation, migration rehearsal, cutover, and rollback gates; - the first end-to-end acceptance path above. After that review, create a file-level implementation plan for only the `foundation` slice. Do not produce a whole-platform task graph up front.