Coherence
Idea Published

Coherence Hub

Every system is built around code.

A few systems can thoroughly explain why that code exists, what's important, how the system works, what states it have, and which claims must be verified.

Coherence Hub is an IntentHub for software systems. Similar to GitHub, it is organized by project, but the main artifact is the version-controlled graph of intent[link:intent-graph].

The purpose is to answer the question:

How to quickly understand what the system is supposed to do?

The problem

Most of the system intent is trapped into code symbols today.

Some of it exist purely in tickets, pull requests, ADRs, old bugtrackers nobody cared to migrate from, Slack threads, WIP diagrams from 2019, onboarding notes, production incidents, and Pete's memory.

And the challenge for the Engineers is somehow to make it all coherent. One system model that everybody is working on.

A new engineer

An agent can scan the repository and still miss the product constraint that explains the shape of the implementation.

A reviewer can inspect a diff and still not know which user outcome, invariant, or system rule the change is supposed to preserve.

GitHub stores how the code changed.

Coherence Hub should show what the change means.

Core model

The Hub has two primary graphs.

The intent graph describes desired outcomes:

The system state graph describes what the system knows and changes:

Together, these graphs form an implementation-independent model of the system.

Once this model exists, the implementation becomes replaceable.

A team can build the same system in Ruby, Rust, Elixir, TypeScript, Kotlin, Go, or something else, because the important part is no longer trapped inside one codebase.

The important part is the model of intent and state.

Code becomes one possible realization of that model.

What the Hub stores

A project in Coherence Hub should contain the smallest useful explanation of a system.

Not everything.

Not every thought.

Not every meeting note.

Only the durable structure needed to understand and evolve the system safely.

At minimum, a project should contain:

This creates a stable object that both humans and agents can inspect.

A developer should be able to ask:

What behavior is this module responsible for?

A product person should be able to ask:

Which user outcome does this change affect?

A reviewer should be able to ask:

What claim is being changed, and what evidence says it still holds?

An agent should be able to ask:

Which slice of the system model do I need before touching this code?

Project view

A project would live at:

hub.usecoherence.dev/{owner}/{project}

A project page should provide a web interface for exploring:

The same project should remain accessible through the CLI, TUI, and public API.

The web interface is not a replacement for local tools.

It is another client for the same underlying model.

Repository integration

Repository import is useful, but it is not the product.

The product is shared system understanding.

A repository is only one source of evidence.

The minimum repository shape can remain simple:

.coherence/
├── project.toml
└── specs.jsonl

From there, the Hub can discover more.

It can detect languages used by the project, run SCIP indexers, import the specification graph, connect specifications to code locations, and generate derived artifacts.

The user should not need to configure the entire analysis pipeline before seeing anything useful.

Add the repository.

Let Coherence inspect it.

Show the intent graph first.

Then show how the code connects to it.

Change review

A normal pull request shows a code diff.

A Coherence change review should show:

This turns a pull request from:

Here are the lines that changed.

into:

Here is the intended outcome, the system state affected by it, the code that implements it, and the evidence that verifies it.

Initially, Coherence Hub does not need to replace GitHub or GitLab pull requests.

It can attach analysis to an existing upstream pull request, publish checks, and provide a richer review page.

Later, Coherence changelists may become native review objects of their own and materialize into branches and commits in the connected repository.

Specification issues and pull requests

Specifications are version-controlled project data.

They should support the same collaboration model as code:

A specification update may exist without an immediate code change.

That is valid.

It means the team learned something about the system before implementing it.

A code change may also reveal that the specification is incomplete.

That is valid too.

It means the implementation discovered missing intent.

Both are changes to the same project model.

Project discovery

Public projects containing a valid .coherence directory can be indexed automatically.

This creates a discovery layer for Coherence-compatible systems:

GitHub lets us discover code.

Coherence Hub could let us discover explicit software intent.

That matters because code reuse is not enough.

A library without its intent is only partially reusable.

A system with its intent graph, state model, constraints, and evidence is much easier to understand, adapt, and rebuild.

Authentication and permissions

The Hub should support:

Private repositories should mirror the permissions of their connected provider.

A user who cannot access the upstream repository must not be able to inspect its specification graph, state model, code index, generated artifacts, or change history through Coherence Hub.

Intent is project knowledge.

Project knowledge needs the same permission boundaries as source code.

Architecture

The Hub is primarily a control plane over intent graphs, state graphs, repositories, and generated artifacts.

It needs to coordinate:

Elixir, Erlang, and Phoenix are a natural fit for this workload: many concurrent projects, supervised background processes, streaming updates, and long-running indexing pipelines.

The Coherence runtime itself does not need to be rewritten in Elixir.

The Hub coordinates existing tools and stores their results.

First useful version

The first useful version does not need to replace GitHub.

It only needs to let a project publish its intent graph, state model, acceptance criteria, links, and evidence in one browsable place.

A small first version should:

  1. import a public GitHub repository
  2. read .coherence/project.toml and specs.jsonl
  3. render specifications, acceptance criteria, links, slices, and DSL
  4. render a basic system state model
  5. connect claims to code locations when links exist
  6. compare two project revisions
  7. show intent, state, and code changes together
  8. expose the project through a public API

Native issues, native pull requests, private repositories, GitLab integration, project discovery, and richer verification workflows can follow later.

The smallest valuable product is not another Git forge.

It is a place where a system becomes understandable as a version-controlled graph of intent, state, implementation, and evidence.

GitHub stores the software.

Coherence Hub stores the reason the software exists.