From Chaos to Clarity: Building OKF — an Open Knowledge Framework for AI Agents

TL;DR — Replaced a messy knowledge base with OKF — a structured system using YAML frontmatter, consistent directory layout, and trigger-based updates. The result: context bootstrapping became a 5-step flow with full documentation coverage.

The Problem: AI-KB Was Not a System

This workspace manages 7 projects — each with its own tech stack (Next.js, Astro, Vite, Express), its own database (Supabase, Neon, Redis), its own authentication strategy, and its own deployment pipeline. That's a lot of context for a human — let alone an AI agent that starts from zero on every conversation.

The old system was called AI-KB. It was a directory of Markdown files parked at ~/AI-KB/, and it worked in the loose sense that the files existed. But it had no structure:

• No frontmatter — files were plain Markdown with no metadata. You couldn't tell when a file was last updated, what type of document it was, or what project it belonged to without reading the whole thing.
• No standard schema — every project described itself differently. One profile had a table for tech stack, another used bullet points, a third was a wall of prose. Machine parsing was impossible.
• No directory convention — files were scattered. Agent profiles sat next to changelogs next to random notes. Finding anything meant spelunking.
• No automation — there were no triggers, no sync commands, no way to programmatically update the KB. Keeping it current was entirely manual, and so it naturally fell out of date.
• No cross-project view — you couldn't compare tech stacks, architectures, or statuses across projects without manually opening 7 files and squinting.

Every time an AI agent started a task, it had to read AI-KB files, guess at their format, piece together the context, and hope nothing was stale. This wasn't a knowledge base. It was a pile of notes that happened to share a directory.

What OKF Is

OKF — Open Knowledge Framework — is the replacement. It lives at ~/OKF/ and it's designed from the ground up for programmatic consumption by AI agents.

The core ideas are simple:

1. Every file has a YAML frontmatter block with type, id, and last_updated. That's it — three fields that make every document self-describing and machine-readable.
2. A fixed directory layout — projects/, system/, skills/, templates/. Every project within projects/ gets the same set of files: agent.md, profile.md, status.md, structure.md, dependencies.md, commands.md, and optionally decisions.md and assets.md.
3. Consistent schemas across all projects — every profile.md looks the same regardless of the project. Same sections, same table structure, same data. Cross-project comparison isn't just possible — it's trivial.
4. Trigger-based automation — three commands (update .md, cleanup, wrap-day) let agents sync the KB with live project state. No manual upkeep.
5. A bootstrap flow — agents follow a 5-step sequence (read INDEX → read AGENTS.md → follow KB links → read conventions → start task) and have full context every time.

How It Works — A Look Under the Hood

Think of OKF as a filing cabinet with labeled drawers. Every drawer has the same dividers, so you always know where to find things.

Here's the actual directory tree:

OKF/
├── index.md              ← the map: every project, its stack, its status
├── projects/
│   └── <project-name>/
│       ├── agent.md      ← who: personality, tools, triggers
│       ├── profile.md    ← what: stack, deps, architecture
│       ├── status.md     ← where: routes, components, changelog
│       ├── structure.md  ← layout: directory tree w/ responsibilities
│       ├── commands.md   ← how: dev, build, test, lint
│       └── dependencies.md
├── system/               ← shared rules
│   ├── conventions.md    ← communication, setup, git rules
│   └── inventory.md      ← triggers: update .md, cleanup, blog-post
├── skills/               ← pluggable skill files
└── templates/            ← template for adding new projects

Every file starts with three lines of metadata:

---
type: project-status     # what kind of document this is
id: my-project-status    # unique id for linking
last_updated: 2026-07-04 # so agents know if it's fresh
---

That's it. An AI agent reads the index.md, picks a project, opens its folder, and finds every piece of context in the same place every time. No guessing, no hunting.

When something changes — a new route, a dependency bump — an agent runs update .md and the status file gets synced automatically.

AI-KB vs OKF: A Comparison

The Migration

The migration from AI-KB to OKF happened in three phases over July 3–4, 2026.

Phase 1: Discovery and Design

First, we scanned the workspace to inventory every project — 7 in total, 6 codebases plus the writer service itself. For each one, we documented its tech stack, architecture, dependencies, and commands using a consistent project template.

We also designed the OKF schema: what goes in profile.md vs agent.md vs status.md, what frontmatter fields are required, and how the directory tree should look. The template file at templates/project-template.md became the contract — every project follows it.

Phase 2: Population

We created all the structural files first — profile.md, structure.md, dependencies.md, and commands.md for every project. These were generated from live source files (package.json, directory trees, config files), so they were accurate from day one.

Then we built the system layer: conventions.md (communication rules, Node.js setup for Termux), workspace.md (cross-project comparison table), inventory.md (trigger definitions), and glossary.md (shared terminology).

Phase 3: Migration and Deprecation

The rich content from AI-KB — agent personalities, behavioral triggers, architectural patterns — was migrated into agent.md and status.md files for each project. AI-KB had valuable content buried in inconsistent formats; we extracted it, normalized it, and fit it into the OKF schema.

Once everything was verified, ~/AI-KB/ was removed. All content was accounted for in OKF, and the old path became a symlink to nowhere.

Total time from first scan to full deprecation: roughly 24 hours.

What We Gained

The benefits showed up immediately.

Zero-guess context. An AI agent following the bootstrap flow goes from cold start to fully informed in under 5 reads. No more hunting for the right file, no more guessing if something is up to date.

Cross-project insight. The workspace.md comparison table lets us see at a glance which projects use which stacks — React 19 + Vite 8 here, Astro 7 + Alpine.js there, Next.js 16 + Drizzle over there. That kind of comparison was impossible before.

Automated maintenance. The three triggers — update .md, cleanup, and wrap-day — mean the KB doesn't drift. When a project adds a route or changes its data flow, a single command syncs the status.md. When a day of development wraps up, wrap-day captures the changelog and commits it.

Machine-readable metadata. The YAML frontmatter enables tooling. You could write a script that scans every status.md across all projects, extracts the last_updated field, and alerts when anything is stale. You couldn't do that with AI-KB.

A skill system that works. With skills/INDEX.md, agents can discover available capabilities — code audit, frontend dev, Supabase optimization, design reasoning — and load the relevant skill for the task. This turns the KB from a passive reference into an active tool.

Consistency across every project. Every project has the same files, same sections, same format. If you've read one project's KB, you know the shape of every other one. Cognitive overhead drops to near zero.

What's Next

OKF isn't finished. The next step is building automated validation — a CI step that checks frontmatter freshness, verifies that every file in the directory tree has a matching entry in index.md, and flags projects where status.md hasn't been updated in N days. There's also work to do on the skills system, making skill invocation more automatic based on task analysis.

But the foundation is solid. AI-KB taught us that even bad documentation is better than none. OKF taught us that structured documentation is better by an order of magnitude — especially when the consumers are AI agents that need to understand your entire workspace in seconds.

If you're managing multiple projects with AI assistance, don't settle for a pile of Markdown files. Build yourself a framework. The ROI kicks in on day one.