On an AI-Native Team, Knowledge Lives in the Repo

Last post ended on a point worth pulling on: our whole review setup only works because the standards live somewhere durable, the labels, the personas, the definition of "good." That's one case of a bigger change in how we run the team. The institutional knowledge that used to live in senior people's heads now lives in the repo, where everyone and every agent can read it.

Every team has the same quiet problem. The real knowledge, why this module is built the way it is, what breaks if you touch that service, the rule we always enforce in review but never wrote down, lives in a handful of heads. Slow to transfer, walks out the door when someone leaves, invisible until you need it. We papered over it with onboarding docs that went stale and a culture of "ask the person who wrote it." That doesn't scale, and it really doesn't scale when agents do the work, because an agent can't ask the person who wrote it.

So we made the knowledge a thing instead of a vibe, and gave it a home: a separate repo we call the -meta repo, decoupled from the product code on purpose. It holds the two things we iterate on fastest, our decision log and our skills. The decoupling is the point. Our product code sits under SOC-2 controls, where every change goes through a slow gated PR review, for good reason. We don't want our own decision records and tooling dragged through that same process. In their own repo, decoupled, they can be edited the moment we learn something: a direct commit, no pull request, no review gate. The meta repo is the low-friction workshop. The product repo stays the controlled floor.

Our procedures are executable, not described. The recurring operations a team does, how we prep a release, run a review, cut a branch, used to be tribal knowledge with maybe a wiki page nobody trusted. In the meta repo they're written as runnable skills that anyone or any agent can invoke and get the same steps every time. The knowledge isn't a description of how to do the thing. It is the thing.

There's a name for this: harness engineering. When an agent makes a mistake, you don't just fix the output, you change the harness around it so it can't make that mistake again. The meta repo is our harness. The skills, the checks, the labels, the standards all live in it, and every time something goes wrong we'd rather spend the fix on the harness than on the one bad result, because the harness improvement pays off on every run after it.

A harness also has to give the agent eyes. A senior engineer debugging reaches for the logs and the browser console. An agent needs the same, or it's working blind and guessing. So we make the environment legible to it. The telemetry from the review post goes into a form the agent can query directly instead of a dashboard a human has to read. And we run the browser in debug mode whenever the agent works on the front end, so it can inspect the live DOM and read the console as it goes, see what it actually rendered instead of inferring it. Small operational choice, outsized effect: an agent that can see what's happening fixes its own mistakes, one that's blind escalates everything to a person. Most of "make the agent more capable" turns out to be "make the system more observable to the agent."

We share by pushing, not by gatekeeping. Improvements to the shared skills go straight to the main branch of the meta repo in small commits. The bet is that frictionless contribution beats careful curation for this kind of knowledge: better everyone improves it constantly than a clean version sits behind a gate nobody bothers to open.

There's also a human ritual that does the same job from the other side, the weekly Show & Tell. The team votes on which of the riskiest recent changes to walk through, and the author teaches it, framed as "here's how this works," not "here's why I did it right." It's the one piece of this that deliberately isn't automated, because the goal isn't a record of the change. It's getting how the system actually works into more than one head. The harness keeps the facts. The ritual spreads the comprehension. You need both.

Now the honest part.

Executable procedures rot differently than docs, and the rot is sneakier. A stale wiki page looks obviously old. A skill that quietly does the wrong thing looks like it's working. When the system changes and the procedure doesn't, you get confident wrong automation, which is worse than no automation. Keeping these current is real ongoing work, not set-and-forget.

"Frictionless contribution" cuts both ways. Push-to-main on shared tooling is fast and occasionally costs us: someone ships a change that breaks a skill for everyone for an hour. We decided that's an acceptable price for keeping contribution easy, but it's a genuine trade, and a more cautious team might choose differently.

The throughline of the whole series is that we kept moving things out of the slow human-gated path and into a durable system: alignment into written artifacts, review into continuous checks, knowledge into the meta repo. Which leaves one question hanging over all of it. If the system holds the knowledge, routes the work, and enforces the standards, what's left for a manager to do? That's the last post.