Skip to content

OKF-light alignment

Status: Adopted (light). Not a full OKF migration.

Reference: Google Cloud — Open Knowledge Format

Why

OKF v0.1 formalizes the “markdown wiki for humans + agents” pattern: a directory of Markdown files with a small YAML frontmatter contract. BookingZone already keeps cross-repo knowledge in git (bz-platform-context). OKF-light makes that bundle easier for agents to navigate without Confluence, SDKs, or a BigQuery enrichment pipeline.

What we adopt

Convention BookingZone practice
Bundle = directory of concepts This repo (bz-platform-context)
One concept ≈ one file Glossary terms live in glossary/; ADRs, process docs, specs as separate files
YAML frontmatter type, title, description, tags, timestamp (+ optional resource)
Progressive disclosure index.md (or folder README.md marked type: Index) at folder roots
Cross-links Normal Markdown links between concepts
Source of truth Git + PR review (ADR-0004). Wiki/Confluence = mirror only

Frontmatter schema (required minimum)

---
type: <see allowed types>
title: Human-readable title
description: One-line summary for agents
tags: [kebab-case, tags]
timestamp: YYYY-MM-DDTHH:MM:SSZ
# resource: optional URL (spec, console, issue)
---

Allowed type values (BookingZone)

type Use for
Index Folder index.md / nav hubs
Guide How-to / process (e.g. branching, OKF itself)
Concept Domain glossary / durable definitions
ADR Architecture decision records
Spec Master / trace specs (specs/SYS-*) — prefer when touching
Constitution System constitution
Runbook Operational ship / incident procedures

Producers may add extra frontmatter keys; consumers must tolerate unknown keys.

Agent habit

  1. Prefer folder index.md (or README.md with type: Index) before deep-reading every file.
  2. Use tags / type to filter relevance (e.g. tags: [payments]).
  3. Treat this repo as the durable knowledge bundle; use MCP for live schema/docs.

Out of scope (for now)

  • Google Knowledge Catalog ingestion
  • BigQuery enrichment agent / OKF visualizer
  • Rewriting every case-study / CSV under docs/
  • Replacing Frappe MCP or DocType schemas with OKF