Divergence Spec Cloud

One canonical spec per workstream, independent of branches, machines, or bots.

The product is intentionally narrow: an API-first, CLI-first, branchless, access-controlled registry for versioned markdown specs. The UI exists to verify, browse, compare, and manage access, not to compete with a general-purpose knowledge base.

API firstCLI firstImmutable versionsMinimal UISign in

V1 scope

Narrow by design

Create, read, update, search, version, and share specs. The product does not try to be MCP, Notion, real-time collaboration, repo sync, or an AI generation surface in v1.

Domain model

Stable entities first

  • Workspace and membership own access, billing, and workspace roles.
  • Projects are the human organization surface and token allowlist boundary.
  • Specs are stable objects; spec versions are immutable markdown snapshots.
  • PATs, service tokens, and share links are distinct auth objects with different trust models.
  • External refs and audit events make links and authorship visible without turning the product into a wiki.

Architecture

Locked decisions

  • Next.js App Router with Route Handlers, not a separate backend service.
  • Supabase for auth, Postgres, and storage, but hidden behind adapter boundaries.
  • Markdown in Postgres as the canonical source of truth.
  • Optimistic concurrency with baseVersionId on every write.
  • FSD-lite only inside apps/web/src and a thin package-oriented monorepo elsewhere.

Delivery plan

Foundation before feature depth

  1. 1Foundation: monorepo, auth boundary, schema, session shell.
  2. 2API: CRUD endpoints, version creation, refs, search.
  3. 3CLI: typed SDK, token config, create/get/update/search flows.
  4. 4Access UI: tokens, revocation, project allowlists, share links.
  5. 5Browsing UI: project pages, spec pages, version history.

Determinism

Built for heavy agent usage

The repo is scaffolded around a thin Turborepo, shared schemas inpackages/shared, an SDK boundary for the CLI, and Chaperone rules that keep naming, placement, and layering enforceable from the first commit.

That structure matters because this product itself is meant to be operated by coding agents. Weak boundaries here would undermine the value proposition of the system.