okf — the Supernova-OKF profile

A profile over Open Knowledge Format v0.2, plus the tooling to enforce it: a Claude Code and Codex plugin, a cross-bundle linter, and a GitHub Action.

OKF guarantees a machine can read the file. It does not guarantee the files speak the same language. This profile closes what OKF deliberately leaves open.

Why a profile

OKF is minimally opinionated on purpose — type is the only required key, and its values are free-form strings. That is the right call for a format meant to be adopted widely, and it is exactly why a corpus drifts.

In a real 12-bundle knowledge base we measured 93 distinct type values across ~700 documents, roughly half of them appearing exactly once — with full OKF conformance throughout. Nothing was broken. Everything validated. And the vocabulary had stopped being a vocabulary.

The ideas worth stealing

Type, status and world state are different axes. OKF's status (draft/stable/ deprecated) describes the document: is this ready to be read? A deal being "won" or a contract being "signed" describes the world. The test: if I rewrite this document tomorrow, with better prose and nothing changing in the world, does the value change? Yes → status. No → a domain field.

Bookkeeping is automated; judgment is asked for. Schema, vocabulary and indexes are deterministic — machines enforce them. "Is this still true?" is judgment — machines only ask, and record the answer in verified. Blocking a merge on judgment produces cosmetic edits and a trust field full of lies.

Never claim human review. The human: actor prefix is how consumers derive trust. An agent stamping it on its own output corrupts the signal for everyone downstream — so during migration, provenance goes to the migrating agent and verified starts empty.

Before collapsing a "state-as-type", check whether the files coexist. Article Draft looks like Article + status: draft — and often is. But if the supposed draft still exists after the final was published, it is not a state: it is a distinct artifact that survived the process, and it deserves its own type pointing at the final one. We nearly collapsed fourteen article skeletons before noticing thirteen of them sat next to their published article. Collapsing would have produced thirteen articles eternally "in draft" whose finished version was another file — destroying the very aggregation the rule protects.

Ownership is declared locally, not centrally. Each bundle states what it owns and what it defers to others. A central domain registry becomes a bottleneck the moment business units model the same word differently.

Install the plugin

Claude Code

/plugin marketplace add supernova-labs/okf
/plugin install okf@okf

Codex

codex plugin marketplace add supernova-labs/okf
codex plugin add okf@okf

The skill routes by intent: create a new bundle, conform an existing one, propose a type vocabulary, migrate v0.1 → v0.2, author a concept, validate, or run a freshness pass.

Validation

Base OKF conformance is construct okf lint. The cross-bundle layers are outside its scope by design — it is deliberately bundle-local and stateless — so they live here.

construct okf lint .
uv run plugins/okf/skills/okf/scripts/okf-xref.py .

Use in CI

- uses: actions/checkout@v5
  with: { fetch-depth: 0 }
- uses: supernova-labs/okf/.github/actions/xref@v0.1.0

Advisory by design — the action never fails the job. CI that goes red for something that does not block teaches people to ignore red CI.

A full workflow, including the blocking conformance gate, is in assets/okf.yml.

Status

Version 0.1.1. Validated by conforming twelve real knowledge bundles end to end — 592 concepts, 93 free-form type values reduced to twelve closed vocabularies. Every rule here earned its place by failing first in a real repository.

License

MIT

{
  "name": "okf",
  "owner": {
    "name": "supernova-labs"
  },
  "metadata": {
    "description": "Supernova-OKF profile — a validated profile over Open Knowledge Format v0.2",
    "homepage": "https://github.com/supernova-labs/okf"
  },
  "plugins": [
    {
      "name": "okf",
      "source": "./plugins/okf",
      "description": "Author, validate, migrate and govern knowledge bundles under the Supernova-OKF profile: OKF v0.2 plus closed type vocabularies, cross-bundle references, ownership and freshness",
      "version": "0.1.1",
      "author": {
        "name": "supernova-labs"
      }
    }
  ]
}