OKF: turn your repo's tribal knowledge into a bundle your agent reads first

The Stack

Tested Against

Prerequisites

• An agent you can point at a folder of markdown

Steps

1. 1

   Hand-author a small bundle and check it conforms

   Write one concept file per thing worth knowing (a gnarly table, a metric, an incident runbook), give each a non-empty `type`, and cross-link them with normal markdown links. CI runs the v0.1 conformance check over the bundle: frontmatter parses and every concept carries a `type`.

   mkdir -p bundle/tables bundle/playbooks
   cat > bundle/tables/orders.md <<'MD'
   ---
   type: BigQuery Table
   title: Orders
   description: One row per completed customer order.
   tags: [sales, orders]
   timestamp: 2026-05-28T00:00:00Z
   ---
   
   # Schema
   One row per completed order. See the [sales dataset](/datasets/sales.md).
   MD
   cat > bundle/playbooks/freshness.md <<'MD'
   ---
   type: Playbook
   title: Incident response, data freshness alert
   description: Steps to triage a freshness alert on the orders pipeline.
   tags: [oncall, incident]
   ---
   
   # Trigger
   A freshness alert fires when the [orders table](/tables/orders.md) lags its SLA.
   
   # Steps
   1. Check the ingestion job dashboard.
   MD
   cat > bundle/index.md <<'MD'
   # Tables
   * [Orders](tables/orders.md) - One row per completed customer order.
   
   # Playbooks
   * [Freshness alert](playbooks/freshness.md) - Triage a data freshness alert.
   MD
   ruby -ryaml -e '
   require "date"
   RESERVED = ["index.md", "log.md"]
   concepts = 0; errors = []
   Dir.glob("bundle/**/*.md").sort.each do |path|
     next if RESERVED.include?(File.basename(path))
     lines = File.read(path).lines
     unless lines.first && lines.first.strip == "---"
       errors << (path + ": no frontmatter"); next
     end
     rest = lines[1..]
     idx = rest.index { |l| l.strip == "---" }
     unless idx; errors << (path + ": unterminated frontmatter"); next; end
     fm = (begin; YAML.safe_load(rest[0...idx].join, permitted_classes: [Date, Time]); rescue; nil; end)
     unless fm.is_a?(Hash) && !fm["type"].to_s.empty?
       errors << (path + ": missing or empty type"); next
     end
     concepts += 1
   end
   if errors.empty?
     puts "OKF bundle conformant: " + concepts.to_s + " concepts, every frontmatter parses with a non-empty type"
   else
     puts "NONCONFORMANT: " + errors.join("; "); exit 1
   end
   '

2. 2

   Wire your agent to read the bundle (the model step, not checked by CI)

   OKF is a format, not a runtime. Tell your agent to consult the bundle before it acts (an instruction in AGENTS.md to read /knowledge first, a retrieval step, or a tool). The agent using the knowledge is fenced.