OKF v0.1 is the canonical format for all family knowledge

OKF v0.1 for all concept files in knowledge bundles

OKF v0.1 is the canonical format for all family knowledge

Decision

Every concept file in oriz/knowledge/ and in each submodule’s knowledge/ directory follows OKF v0.1 — one concept per file, plain markdown body, YAML frontmatter with type / title / description / tags / timestamp, kebab-case filenames, max 3-level hierarchy.

Why

OKF is producer/consumer-independent: any LLM-backed agent can read it without bespoke tooling, and the user can read it with any markdown editor. It also has a Google Cloud-published static visualizer and an emerging consumer ecosystem, which is the strongest 100-year-bet currently available for durable agent-readable docs. Picking it once across the whole family avoids a per-repo re-litigation each time we open a new submodule.

Implications

• Family-wide conventions live in ../../_okf.md; every other concept file references it implicitly.
• Per-site knowledge/ bundles follow the same shape with site-specific concepts only; cross-link to family-wide concepts via relative paths.
• The 12 allowed type values (convention, rule, decision, service, runbook, design-brief, architecture, policy, schema, process, glossary, index, log) are the closed taxonomy — extend deliberately.
• New decisions get a file under knowledge/decisions/, NOT a section embedded in AGENTS.md.
• When the spec hits 1.0 we run a frontmatter audit; until then prefer additive frontmatter changes over structural ones.

Cross-refs

• Format conventions (_okf.md)
• Self-update rule
• Knowledge bundle index
• Add-new-decision runbook — the operational workflow that enforces this format
• OKF v0.1 spec — Google Cloud, published 2026-06-13

Edit on GitHub · Back to index