Context-V Is an OKF Profile
Any tool that reads Open Knowledge Format can read a context-v folder. The price is one frontmatter field and an index file.
- Path
- decisions/Context-V-Is-an-OKF-Profile.md
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5
- Tags
- Decision · OKF · Interoperability · Frontmatter · Context-Vigilance
Context-V Is an OKF Profile
Why care?
Context-v is a folder of markdown files with YAML frontmatter. So is the Open Knowledge Format (OKF), an open spec from Google Cloud for knowledge that “people write, agents generate, and organizations exchange.”1 OKF deliberately defines almost nothing: no taxonomy, no lifecycle, no body structure. Context-v is exactly those things. They stack.
Making context-v conformant means any OKF tool (visualizers, validators, other organizations’ agents) can read a context-v/ folder. It also means the kit can honestly say this is a standard format with opinions on top, not learn our format.
The decision
A context-v/ folder is an OKF v0.2 bundle. Context-v is a profile of OKF: it adds a folder taxonomy, a status lifecycle, four-part versions, and identity fields, and keeps everything OKF requires.
Decided 2026-10-05 by Michael Staton, after reading the v0.2 spec1, the frozen v0.1 text2, and an annotated guide3.
What OKF requires, and where context-v stands
OKF v0.2 conformance has three rules:1
- Every non-reserved
.mdfile has parseable YAML frontmatter. Already true. The kit’s hook enforces it before writes tocontext-v/. - Every frontmatter block has a non-empty
type. The one real gap. index.mdandlog.md, when present, follow OKF’s shape. We use neither yet, andcontext-v/README.md(no frontmatter) breaks rule 1.
What changes
typeon every doc. The value is the folder’s own name, plural, in Train-Case:type: Specs,type: Plans,type: Explorations,type: Issues,type: Decisions,type: Loops,type: Handoffs, …. Type always matches the folder, so it’s never a judgment call, and a check can verify it. Templates carry it,/cv:newand the shortcuts set it, and the hook requires it on new files. Existing docs get it in a deliberate pass, never as a side effect of other work.- Folder types stay open. Context-v’s folders were always a starting set; people and agents create new ones when the work calls for it. OKF doesn’t constrain that either, since it registers no types centrally.1 Two rules: folder names are plural, and a doc in any folder declares that folder’s name as its
type(research-notes/→type: Research-Notes).
- Folder types stay open. Context-v’s folders were always a starting set; people and agents create new ones when the work calls for it. OKF doesn’t constrain that either, since it registers no types centrally.1 Two rules: folder names are plural, and a doc in any folder declares that folder’s name as its
index.mdreplacescontext-v/README.md. It’s in OKF’s shape (headings plus a linked list with one-line descriptions, no frontmatter), and the root one declaresokf_version: "0.2". Folder-levelindex.mdfiles are optional;/cv:kickoffreads them, and/cv:reflectkeeps them current. They do for agents what the README did for people: a table of contents to read before opening anything.- Map, don’t rename. Context-v keeps its own fields. OKF fields are added only where they carry something new:
description: the one-line summary OKF tools show in indexes and search.verified: { by: "human:<id>", at: … }, written when/cv:preprecords a sign-off. A human verifier makes the doc human-reviewed in OKF’s trust tiers, so our sign-off gate becomes machine-readable.generated: { by, at }, derivable fromauthorsand the dates, and written when useful.
sourcesand our hex-code citations are the same idea. OKF keys per-claim footnotes tosources[].id, not positions, because “agents constantly rewrite these documents.”1 That’s the reason we use hex codes. A doc’s citation keys serve assources[].idvalues. This decision doc uses them.- A reference in the context-vigilance skill (
references/okf.md) holds the mapping below.
Status: keep ours, map for OKF readers
OKF v0.2 fixes status to draft | stable | deprecated, with absent meaning stable.1 Context-v uses the same key for a richer lifecycle. We keep ours, because it carries the workflow, and publish this mapping for OKF consumers:
context-v status |
OKF status |
|---|---|
Draft, In-Review |
draft |
Signed-Off, Implementing, Shipped, Partially-Shipped |
stable |
Stale, Superseded, Archived, Deferred |
deprecated |
An OKF tool reading a raw context-v doc sees an unrecognized status value. The spec forbids rejecting documents over unknown fields, but doesn’t say how to read an unknown value of a known field. If that becomes a real problem, an export step can rewrite status on the way out, without touching the source.
Alternatives passed over
- Ignore OKF. It costs nothing today. But the overlap is so large that staying incompatible would be a choice to be insular, and a gift to anyone who wants to fork the practice into OKF.
- Adopt OKF wholesale, dropping context-v’s fields. It loses the lifecycle, versions, IDs, and folder taxonomy: the parts that make the practice work. OKF explicitly leaves those to producers.
- Rename our
statusto avoid the clash. It would break every existing doc and every reader of them, for one external consumer’s benefit. The mapping costs less. - Generate a separate OKF export and leave context-v untouched. Two copies drift. Conformance in place, at the cost of one field, is cheaper and keeps one source of truth.
Still open
agent-skills/sits outside the bundle. Skill files follow the Agent Skills spec, and addingtypetoSKILL.mdmay trip strict skill validators; theirreferences/files have no frontmatter at all. OKF already expects schemas like.protofiles to live beside a bundle, not inside it.extra/is scratch with no frontmatter, but it’s gitignored, so a cloned bundle never contains it.Links.Settled 2026-10-06: wikilinks stay. OKF doesn’t require any link style; conformance is frontmatter andtypeonly. A repo declares its link syntax incontext-v/config.mdunderlinks:(default: wikilinks, resolved by filename). OKF’s reference visualizer only follows markdown links, which is a limitation of that demo tool; a 31-line patch makes it follow wikilinks too.log.md. Whether/cv:reflectalso appends alog.md(OKF’s per-folder change history) alongsidechangelog/.- Datetimes. OKF timestamps are full datetimes with a UTC offset; our
date_*fields stay date-only. OKF fields we add use OKF’s form.
As built (2026-10-05)
- Every template carries
type(the folder’s name) anddescription; adecisiontemplate and the/cv:decideshortcut are new. /cv:newand its shortcuts settypeand add the doc’s line to its folder’sindex.md.- The frontmatter check requires
typeon new files and rejects one that doesn’t match the folder. It skipsindex.md,log.md, andconfig.md. /cv:initwrites an OKF-shapedcontext-v/index.md(declaringokf_version: "0.2") instead of a README./cv:kickoffreads the indexes first;/cv:reflectkeeps them current./cv:preprecords a sign-off asverified: { by: "human:<id>", at: … }.references/okf.mdin the context-vigilance skill holds the mappings and a conformance one-liner.- This repo’s
context-v/hastypeanddescriptionon every doc, plus indexes. It passes the three conformance rules, and OKF’s reference visualizer renders all six docs, including this one’s human-reviewed trust tier and its sources.
What the visualizer showed: zero links between docs, because that demo tool follows only standard markdown links. That’s a tool limitation, not an OKF requirement (see Still open, now settled).
How we’ll know it worked
- ✅ The kit’s own
context-v/passes OKF’s three conformance rules. - ✅ It opens in the OKF reference visualizer without errors.
- ⬜ A newly scaffolded repo (
/cv:init, then/cv:explore) is conformant from the first doc. Waits on a first live install.
Related
- [[Context-V-as-a-Portable-Plugin-Any-Agent-Can-Install|The portable-plugin exploration]]: the kit’s design and its decisions log
- The frontmatter hook (
hooks/check-frontmatter.py): wheretypebecomes required