Why I built okf-gem

People ask why I built a whole toolkit around a Markdown format. The reason is simple: standards. Standards are what make scale possible, for a team, for a codebase, and now for agents.

From directing agents to giving them boundaries

I have worked with coding agents long enough to watch my own workflow change shape. In the past I used frameworks like Superpowers to produce specs and artifacts that directed the agent, and that gave me documentation of the project's progress as a side effect. It worked. But the center of gravity was in the wrong place: I kept writing more instructions to get the behavior I wanted.

Today my concern is different. I want a good harness, just enough instructions, and well-documented supporting content that defines the limits. Written constraints are what give an agent real freedom: it can work hard inside what was established instead of guessing at what I meant. In that setup, the instructions get shorter and the knowledge becomes the part that carries the weight.

Structure is the problem OKF actually solves

Which leads to the catch: organizing knowledge efficiently, in a way that stays organized, is not trivial. Every team invents a folder convention, and every convention drifts into a junk drawer.

That is the problem the OKF specification solves. It answers the "how do I structure this?" question once, with folders, frontmatter, links, an index, and a log, and that answer creates freedom on the other side: I can document anything that matters, technical or not, without redesigning the structure every time. The format does the deciding; I do the writing.

Tooling and process were the other half

A structure without tooling and process still rots. I wanted a skill that uses tooling to consume bundles token-efficiently, and an interactive way to consult and browse all of it. That search led me to Marco Boffo's okf-skills, a Python toolkit for OKF. Finding it was great, and I needed more resources than it offered.

So I decided to build okf-gem: a complete package, replicable in any project, that establishes a standard and a process for how bundles are maintained (the skill and the Claude Code plugin) plus all the tooling for agents and humans (the CLI and the live graph).

Ruby objects, MCPs, and a graph you can mount

Since January I have been building AI tooling that organizes and consumes different data sources to give agents context. Working against a specified format made one thing obvious: representing bundles and concepts as Ruby objects is extremely versatile and powerful. The same objects can back an MCP server, feed an agent implementation, or run inside a plain script.

I also wanted the graph as a Rack app, not just a command. It serves my documentation locally today, and the same app mounts inside a Rails application, where I can put my own authentication in front of it.

Local, private, and portable

Given that need for process, standardization, and working well with agents, the whole toolkit runs 100% local, with total privacy. No account, no telemetry, no upload. A knowledge base is the most sensitive artifact a team owns, and it should not leave the machine to be useful.

The standard cuts one more way, and this is the part I like most: as OKF gets more popular, my tooling can interact with any bundle out there, because the format is portable. Tools built on a standard compound in value with every bundle anyone creates.

Solving my own problem first

I have been working to build my own venture, and that means dealing with a lot of things beyond code. Having a standardized way to organize knowledge, for me and for the people on my team, is not a nice-to-have; it is what keeps the rest manageable. And as I learned from 37signals' Getting Real more than a decade ago: when you solve a problem for yourself, you are probably solving it for a lot of other people too.

That is the bet. It is Apache-2.0; try it on a real repo and tell me where it falls short.