okf — the Supernova-OKF profile
A profile over Open Knowledge Format v0.2, plus the tooling to enforce it: a Claude Code 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.
| What OKF leaves open | What the profile defines |
|---|---|
type is a free string | closed vocabulary per bundle, declared and validated |
| nothing about references across bundles | <bundle-id>:<concept-id> syntax and resolution |
| nothing about duplication | self-declared owns/defers, no central registry |
status without a stated axis | document lifecycle vs. world state, separated |
| no dependency-based freshness | belongs_to + verified |
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
/plugin marketplace add supernova-labs/okf
/plugin install 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 .
| Layer | Checks | Fails |
|---|---|---|
| Reference | bundle:concept syntax, bundle declared, resolves when reachable | warns |
| Freshness | hub pending review, derived copy older than origin, stale_after expired | warns |
| Ownership | belongs_to crossing bundles, dangling defers, owns collision | warns |
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