What the Open Knowledge Format is, and why the ADLC needs one
Google Cloud published a v0.1 spec that says knowledge is a directory of markdown files. The unglamorous part is the point, and it is exactly what agentic development has been missing.
An engineer asked an agent to add a churn column to the weekly revenue export. The agent did it in about four minutes. It found the export job, found the subscriptions table, wrote a reasonable definition of churn, added the column, wrote a test, opened a pull request. The code was clean. The test passed. The reviewer approved it.
The number was wrong. Not slightly wrong, wrong in the way that makes a board meeting awkward, because the company had a specific definition of churn that excluded trial accounts and treated downgrades as partial churn, and that definition lived in a Confluence page written eighteen months earlier by someone who had since left, plus a thread in Slack, plus the head of one analyst who was on holiday.
Nobody had lied to the agent. Nobody had even withheld anything. The knowledge simply was not anywhere the agent could read, and the agent, being an agent, did the most reasonable thing available to it: it invented a definition that looked exactly like a real one.
This is the failure mode that the Open Knowledge Format is aimed at, and it is worth understanding what was actually published, because the spec is smaller and less exciting than the problem it addresses, which is usually a good sign.
What was actually published
On 12 June 2026, Google Cloud published version 0.1 of the Open Knowledge Format as an open, vendor-neutral specification. Here is essentially all of it.
Knowledge is a directory of markdown documents. Each document has YAML front matter at the top. Each file represents exactly one concept: a metric definition, a database table, a runbook, a policy, a service. The file path is the concept’s identity, so metrics/churn-rate.md is not a file that happens to describe churn rate, it is churn rate as far as the knowledge base is concerned. Concepts link to each other using ordinary markdown links, which turns the directory into a graph.
The front matter requires exactly one field: type.
That is the shape of it. No licence to accept, no API key, no server, no vendor account, no database, no proprietary format. Plain text files in folders. Anything that can read a text file can read the whole thing, which includes every editor, every agent, every CI job, every grep, and every human.
I want to sit on that last point about restraint for a moment, because it is easy to read a one-required-field spec as an unfinished spec.
A format with one required field is making a bet. The bet is that the hard part of organisational knowledge was never the schema. It was getting anybody to write anything down in a place that both a human and a machine could find. Every previous attempt to solve this problem started by designing an ontology, and every one of them died at the point where somebody had to fill in eleven mandatory fields to record a fact they already knew. Requiring one field means the cost of adding a concept is roughly the cost of writing the sentence you were going to write anyway.
Why this matters more now than it did in 2019
Wikis are not new. Confluence is not new. Notion, Backstage catalogues, data dictionaries, README files, architecture decision records: teams have been writing things down in structured-ish ways for decades, and the honest history of that is that most of it rotted, because the reader-to-writer ratio was terrible. You paid a real cost to write a page, and it got read four times.
Two things changed that arithmetic.
The first is that the primary reader is no longer a person. When an agent picks up a ticket, it reads whatever it can find, and it reads all of it, every time, without complaining and without skimming. A page that a human would have opened twice a year now gets consulted on every relevant change. The return on writing something down went up by an order of magnitude, quietly, without anybody announcing it.
The second is that the cost of being unwritten went up. A human developer who did not know the churn definition would have felt the gap. They would have hesitated, asked in a channel, tagged someone. That hesitation was a safety mechanism, and it was made of ignorance being uncomfortable. Agents do not experience that discomfort. An agent fills a gap in knowledge the same way it fills a gap in code: fluently, plausibly, and at speed. Missing knowledge used to produce a question. Now it produces a merged pull request.
When knowledge is unwritten
- A human hesitates and asks in Slack
- The answer lives in one person's head
- An agent invents a plausible substitute
- The invention ships, confidently
- The error surfaces in a board pack
When knowledge is a file
- The agent reads it before writing code
- The definition has one location
- A wrong definition is a diff, not a rumour
- Changes to it are reviewable
- The error surfaces in review
The ADLC angle
The Agentic Development Life Cycle rests on an uncomfortable requirement: context that used to travel inside a human now has to exist as text, because the thing doing the work cannot absorb context by osmosis, by having sat in the planning meeting, or by having been burned by this exact bug last spring.
Most teams meet that requirement badly. They meet it by stuffing a prompt. They paste three paragraphs of background into a ticket, or maintain a sprawling instructions file at the repository root that grows by accretion until it contradicts itself, or rely on a retrieval system that returns the four most similar chunks of an outdated wiki. All of these are ways of saying “we know context matters” without doing the boring thing, which is deciding what is true and writing it in one place with a name.
The Open Knowledge Format is a proposal for the boring thing. Its contribution is not technical sophistication. Its contribution is that it names a shape that is cheap enough that a team might actually maintain it, and structured enough that a machine can navigate it without guessing.
There is a nice symmetry here that I do not want to overstate. The article you are reading is a markdown file with YAML front matter in a directory, alongside sixty-odd others, each covering one idea, linked to each other. Nobody designed this library to conform to a specification. That is just what you end up building when you want text that both people and tools can work with. The spec largely describes a convergent solution rather than inventing one, which is the best argument for it.
What a knowledge directory actually looks like in a codebase
Concretely, on a real project, the thing tends to grow in this order.
The pattern to notice is that every entry starts life as an argument that happened more than once. That is the cheapest possible signal for what deserves a file. If two people have had to agree on something twice, the agreement should be a document, and the document should have a path.
What this does not solve
It is a format, not a truth oracle. A file at metrics/churn-rate.md is exactly as correct as whoever last edited it, and the format makes no promise about that. Writing the definition down converts an unknowable problem (what does this company mean by churn) into a knowable one (is this file current), which is genuine progress, but it is progress of a modest kind and it should be sold that way.
It also does not solve retrieval at scale, does not define how an agent should decide which files are relevant, does not say anything about access control, and does not tell you what to do when two files disagree. Version 0.1 leaves all of that open. Some of it will presumably get addressed. Some of it probably should not be, because the moment a format starts specifying access control it stops being something you can adopt in an afternoon.
Where this breaks down
The honest case against everything above.
It is v0.1, published weeks ago. I am writing about a specification that is very new, from one vendor’s open publication, with no track record. It may change substantially. It may be superseded by something with more momentum. Adopting the shape (one concept per file, path as identity, markdown links, front matter) costs you nothing much if the spec evolves, because that shape is just good filing. Adopting it as a commitment, building tooling that assumes today’s details, betting a platform on it: that is premature, and anybody telling you otherwise in August 2026 is selling.
Structure has a real maintenance cost. Every file is a thing somebody has to keep true. A hundred concept files is a hundred small liabilities. Teams consistently underestimate this because writing the first thirty is enjoyable and maintaining the next three hundred is not. If you cannot name who owns a section of the knowledge base, you are building a monument, not a tool.
A stale knowledge base is worse than none. This is the one that should worry you most, and it is the theme this whole series keeps returning to. When there is no written definition of churn, the agent’s answer arrives with an implicit warning label: it made this up. When there is a file that says churn excludes trials and that file is fourteen months out of date, the agent’s answer arrives with false authority, and the reviewer, seeing a citation to an internal document, checks it less carefully rather than more. Confident wrongness is exactly the failure mode agentic development already suffers from, and an unmaintained knowledge base is a machine for producing it.
Not all knowledge is decomposable into concepts. Plenty of what an experienced engineer knows is contextual, conditional and situated: this service is fragile on Mondays because of a batch job in another team, this customer will escalate, this abstraction is wrong but is not worth fixing yet. Try writing those as one-concept-per-file documents and you get either uselessly bland statements or a filing problem. The format is good for definitions, entities and procedures. It is much weaker for judgement.
One required field means very little interoperability, yet. A spec that requires only type is easy to adopt and hard to build on. Two organisations can both be perfectly OKF-conformant and share almost no common vocabulary, which means the portability on offer today is portability of files, not of meaning. That is still worth having. It is not the same thing as a standard.
The takeaway
The Open Knowledge Format is a small, early, vendor-neutral proposal that organisational knowledge should be a directory of markdown files, one concept per file, path as identity, linked to each other, with one required piece of metadata. Its value is not sophistication. Its value is that it is cheap enough to actually do, and legible enough that a machine can use it without a platform in the middle.
The ADLC needs something of this shape because agentic development converted unwritten knowledge from a slow-burning cultural problem into an immediate correctness problem. An agent will not ask you what churn means. It will tell you.
The next piece in this series looks at where this pattern came from: the LLM-wiki that Andrej Karpathy popularised, why the idea spread as folklore before it had a spec, and what formalising it actually adds.