Worklode

Open source · Sunstone Institute

Intent is asserted.
Reality is observed.
The gap is a query.

Worklode is a platform work and architecture system. It records what your team says it will build, derives what your repos and clusters actually did, and turns every gap between the two into something you can query — architectural drift, an unimplemented spec, a deliverable that never reached production.

View on GitHub How it works

Single Go binary lode · PostgreSQL · RDF knowledge graph · MIT licensed

The thesis

Development work as ambition reconciliation

Most trackers store one version of the truth and ask humans to keep it honest. Worklode stores two — what was intended and what happened — and treats the difference as the product.

  1. 01

    Assert

    Design documents, specs and ADRs declare intent: which components exist, what depends on what, and what done means. They are authored into the graph and reviewed like code — not filed away as prose nobody reads again.

  2. 02

    Observe

    Derivers read ground truth: commits, pull requests, reviews, CI runs, artifacts, deployments and environments. Nobody hand-maintains this layer, so nobody can forget to.

  3. 03

    Reconcile

    Drift, documentation gaps, unimplemented specs and the ready frontier stop being standing meetings. They are all reads over the difference between the two layers.

The model

Three layers on one graph

One layer is asserted by people. Two are observed by machines. Deliverable is the vertical reconciliation point — where a declared definition-of-done meets what is actually running in production.

Three layers: Intent asserted, Execution and Runtime observed, joined vertically by Deliverable Intent asserted · authored & reviewed Design doc · Spec · ADR Component · Deliverable Execution · VCS observed · derived from your repos Task · Issue · Pull request Commit · Review · CI run Runtime · Deploy observed · derived from your clusters Artifact · Deployment Environment · Release
Execution facts flow up into the graph as a projection; design facts flow back down as references. The work graph lives on one branch — project is a property, not a silo.

The payoff

Drift is a diff, not a meeting

Every architectural relationship exists twice: as an asserted edge someone authored alongside a design document, and as an observed edge derived from code, pull requests and deploys. Compare them and drift falls out.

observed − asserted − acknowledged = drift

A deviation you meant to keep is not a violation. Mark it accepted with a node that names the tolerated edge, is sanctioned by an ADR, and can be set to expire — reviewed and provenanced like any other assertion, never a hidden allowlist.

Architectural drift

A component depends on something your design never said it could.

Documentation gaps

Code that exists in the observed layer with no design document behind it.

Unimplemented specs

Intent that was written down, accepted, and then never showed up in a repo.

Ready frontier

What is genuinely unblocked right now, computed from the graph — never cached stale.

The architecture

Two stores. No fact has two owners.

Transactional work needs locks and ACID guarantees. Architectural knowledge needs versioning, branches and time travel. Those are different jobs, so Worklode uses different stores and splits authority cleanly between them.

Execution backbone

PostgreSQL

Task state, worktree-bound leases, an append-only provenance event for every state change, and the blocks / child_of edges that gate pickup. Claiming a task is one ACID transaction.

Knowledge graph

RDF quad store

Named graphs, versioning, time travel and branches. Components, design documents, architectural relationships and drift. Standards-first vocabulary — Dublin Core, PROV, DOAP, SKOS — with new terms minted sparingly.

Work arrives on its own: a GitHub App feeds issues, pull requests, reviews, CI runs and releases; a Flux webhook reports deployments; a Kubernetes watcher reports crash loops and OOM kills. Reconciliation replays anything a webhook missed.

Built for agent-driven teams

Coordination should not cost tokens

Push coordination into deterministic, token-free machinery — compiled hooks, a CLI with --json, server-side selection. Spend model tokens only on judgment.

Atomic pickup

claim --next ranks and takes the next ready task in a single transaction, server-side. Two agents starting at once cannot land on the same task, and no model has to reason about which one to pick.

Worktree-bound leases

A lease belongs to a git worktree, not a chat session. It survives restarts and context clears, renews from a compiled pre-commit hook, and expires on its own when work is genuinely abandoned.

Session visibility

The backbone knows which coding-agent session holds which lease right now — across Claude Code, Codex, Cursor, Aider and others — so “what is running?” has an answer.

Ranking that fits people

A concern dimension and a per-project focus steer what comes next, with a strict mode when a project needs undivided attention. No story points.

agent picking up work
// claim the next ready task, create its worktree, bind the lease
/lode:next
// re-acquire the task already bound to this worktree
/lode:resume
// record a real blocker and release the lease
/lode:block --on WL-42
// finish, release, clean up
/lode:done

Get started

Up in a few commands

Docker Compose brings up Postgres, applies migrations and starts the server. Then install the CLI and claim something.

shell
# start the stack
export LODE_BOOTSTRAP_TOKEN=wl_$(openssl rand -hex 20)
docker compose up -d

# install the CLI
go install ./cmd/lode

# create a project, map a repo, add work, claim it
lode project add sunstone-web --name "Sunstone Web"
lode project add-repo sunstone-web sunstoneinstitute/sunstone-web
lode task add --title "Fix the footer link"
lode task claim --next

Read the docs on GitHub