Introducing Keystone: The First Agent Harness Framework | by Ian Johnson | Jun, 2026 | MediumSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Introducing Keystone: The First Agent Harness Framework

Ian Johnson

8 min read·<br>Just now

Listen

Share

Setting up an agent harness from scratch is enough work that most teams never start. You sit down on a Monday morning, look at an empty .claude/ directory — or .codex/, or .cursor/ — and decide to do it next week. Next week becomes next month. The agent keeps making the same mistakes it made the first day, and nobody has time to write the file that would stop them.<br>That’s the problem Keystone solves. As of today, Keystone is at 1.0. It’s free, MIT-licensed, and ready to install on a real project. I’m responsive to feedback — if something is wrong or missing, tell me and it has a real chance of landing in the next release.<br>What Keystone is<br>Keystone is the agent harness framework for any project. Think of it the way you think of a web framework. Rails, Django, Laravel give you the components, conventions, and slots to build a web app: routes, controllers, views, middleware, a directory layout that tells you where each piece lives. Keystone does the same for an agent harness. Its components are guides the agent loads on every turn, a corpus of on-demand context, sensors that catch mistakes before they reach a commit, actions the agent can run, playbooks that chain those actions into workflows, and adapters that bind the whole thing to whichever coding agent you use.<br>That last piece is the headline. Keystone is agent-agnostic. Claude Code, Codex, Cursor — the adapter layer renders the same harness into the file shape each tool expects. One source of truth, one set of conventions, and the team’s rules ride along regardless of which agent a developer happens to open today.<br>The build itself is small. A Go binary lays the files down; from there it’s markdown and conventions all the way. No daemon to keep alive, no SaaS to log into, no API key to rotate. If you uninstall Keystone tomorrow, the harness it scaffolded keeps working — and you keep ownership of every line.<br>That part matters more than it sounds. Most harness tooling I’ve looked at wants to be the thing you depend on. Keystone wants to be the thing that gets you to a working harness and then gets out of the way.<br>Design principles<br>The product is opinionated, and the opinions are worth naming out loud. These are the principles I keep coming back to when deciding what goes in and what stays out.<br>The harness is just markdown. Rules live in plain .md files. No DSL, no YAML schema, no compiler step. If you can write a paragraph, you can write a rule. If you can git diff a file, you can review what changed.<br>Any agent, one harness. The adapter layer translates a single set of files into Claude Code, Codex, Cursor, or whatever comes next. Switching agents — or running two on the same repo — does not mean rewriting the rules.<br>Easy to change. Need to update a rule? Open the file, edit the markdown, save. No build step, no migration, no internal index to rebuild. The change takes effect the next time the agent loads the file. The cost of fixing a wrong rule should be the cost of editing a paragraph, and in Keystone it is.<br>The team owns the harness. Files live in your repo, on your branch, in your review process. PRs that touch the harness go through the same review as PRs that touch the code. Nobody else can change the rules under you, and the rules version with the commits they describe.<br>A place for information at every layer. The framework has slots at the project, team, and org level. Org policies are shared across every repo in the company; team policies sit between, for teams big enough to need their own conventions. Strict policies lock things projects can’t override. Non-strict policies act as defaults the project can adjust. The cascade only kicks in when there are layers worth cascading — solo developers ignore the org and team layers entirely. All layers are agnostic and can be nested arbitrarily to model any governance or compliance model.<br>Optional everything. The default install gives you a working set, but every piece is removable. Don’t want the security review? Delete the agent. Don’t like the six-phase workflow? Use four phases. The harness should fit the team, not the other way around.<br>Cheap checks before expensive ones. Lint, type-check, and tests run first. They’re fast and unambiguous. Only after the cheap checks pass do the inferential reviewers (functional, security, risk) get a turn. A good harness fails fast on the easy things and saves the expensive thinking for what’s left.<br>Review feedback feeds the rules. The hardest part of running an agent is noticing when it has drifted from the team’s norms. Keystone ships with a learning loop that turns review feedback into rules, so the same correction doesn’t get retyped in every PR.<br>Boy-scout maintenance is part of...