Put the AI Context in the Repo

I used to treat AI context as something I carried in my head, or worse, as something I rebuilt in the chat box every morning. A paragraph about how we ship. A reminder about the constraints. A half-remembered skill file that lived in a private note. It worked until it did not. The model was ready. The repo was ready. The brief was a rumor.

This week our Community of Practice came back to a blunt question: what lives in the repo? Not as a slogan. As an operating choice. If agents are going to act on a codebase, the scarce artifact is not another model name. It is the context that makes their action safe and useful.

The scarce artifact moved

For a long time the scarce thing was code. Then it was compute. Then it was access to a strong model. Those are not free now, but they are no longer the bottleneck I feel day to day.

What I feel is missing context. The brief that says what “done” means. The skill that says how we review. The constraints that say what we will not trade away for speed. The local facts that never made it into the README because they lived in a meeting.

If that context stays in a private brain, every human and every agent starts from fog. If it lives in the repo, the next person inherits a brief instead of a scavenger hunt.

Repo as the shared brief

I do not mean dump every thought into markdown and call it governance. I mean put the durable AI-facing context next to the code it governs:

• How we go from ticket to production in this repo
• What skills or agent instructions we trust here
• What must be true before a change is mergeable
• What the system is for, in language a stranger can use

That is the same instinct as keeping runbooks near the services they rescue. Humans already know to look in the tree. Agents are finally good enough to look there too. The mistake is leaving the important sentences in a chat transcript that expires when the tab closes.

Our CoP conversation was useful because it stayed concrete. People were not arguing about whether AI matters. They were arguing about where the brief should live so the next session does not start from zero.

What I am practicing

I write this from Omarchy, which has been my daily driver for about eight months. Linux, not a Mac I dual-boot for comfort. Mail still lives in Gmail in the browser across a few accounts. Calendar still lives in Notion Calendar. The boring substrate is not the thesis. It is a reminder that I will change defaults when they stop matching the job.

The default I am changing now is where AI context sits.

1. Prefer a repo artifact over a clever prompt I cannot find tomorrow. If I had to say it twice, it probably belongs in the tree.
2. Keep skills next to the work. A skill that only lives in one person’s tool profile is a private advantage that becomes a public outage when they are out.
3. Write constraints as constraints. “Be careful” is not context. “Do not touch payments without X check” is context.
4. Let agents read what humans already needed. If a new engineer would need the paragraph, the agent probably does too.
5. Accept that some pain remains elsewhere. I have not solved mail and calendar clients. I do not need to solve them before I put the brief in the repo.

Chat is a scratchpad, not a filing system

I still use chat. I am not performing purity about interfaces.

Chat is where I discover the sentence. The repo is where I keep the sentence that survived contact with the work. The failure mode is treating the scratchpad as the archive. Then Monday arrives, a different agent session opens, and I perform the same briefing like I never learned anything last week.

There is also a social version of the same bug. A useful CoP insight stays in the room notes. A hiring conversation produces a crisp definition of “done” that never reaches the repository the new person will clone. We keep saying we want leverage from AI. Leverage needs an address.

Building in public without oversharing

I am fine saying the operating principle out loud: context belongs next to code. I am not going to paste internal product machinery, deal dollars, or client strategy into a personal post to sound concrete. The concrete part is the habit. If a paragraph changes how humans and agents should act on a repo, that paragraph has a home in the tree.

That habit also plays nicely with Team Topologies-shaped thinking I wrote about recently. Clear interfaces need durable artifacts. Infinite verbal collaboration is how context stays trapped in bandwidth. A short file in the repo is often the interface.

What this is not

It is not a demand that every company publish its internal brains. Building in public is useful at a high level. Product internals, deal math, and client strategy still do not belong on a blog.

It is also not “the README will save us.” READMEs rot when they try to be everything. The win is a small set of living context files that agents and humans actually open, kept honest by use.

And it is not a claim that context in the repo removes judgment. It concentrates judgment. Someone still has to refuse a confident wrong plan. The repo just makes the standard visible before the plan is drafted.

Put it where the work is

Models will keep moving. Editors will keep changing. The chat box will keep inviting me to re-explain the company every morning like a tourist.

I am done touring. If the context matters, it lives in the repo. That is the brief I want humans and agents to share.