Why I built Rness: governing AI coding agents across repositories

Cédric Magne — Wed, 07 Oct 2026 19:37:50 +0000

I build with coding agents every day: Claude Code most of the time, Codex for a second opinion, Cursor or Devin in the editor. My GitHub organization has five repositories. An agent can know how a related repository works, if the configuration of the one it is in tells it. That is extra configuration in every repository, and keeping all of it in sync by hand is heavy.

Governing those agents from one place, across every repository, was the hard part. I started Rness to solve it. This is what it is, what it already does in my own organization, and where it is going.

Every agent has its own picture of your organization

Look at a team that codes with agents. One repository has a CLAUDE.md, an AGENTS.md and a .cursor/rules folder. The next has a CLAUDE.md copied from the first months ago and edited since. A third has .github/copilot-instructions.md and nothing else. The architecture decision the team took last month sits in a document no agent opens.

Each agent works from the file in front of it, so each one carries its own picture of the organization, and the pictures disagree. The more code the agents write, the more that disagreement lands in the code.

A governance layer above the agents

Models provide the intelligence and agents do the work. Rness is the layer above them that holds what the organization has decided: its standards, its architecture decisions and the reasons behind them, the specifications and plans in progress. Agents execute; Rness governs.

It rests on three ideas.

Everything lives in one place. The standards, decisions (ADRs), specifications and plans are Markdown files in one repository, .rness, cloned next to the others, with a rness.json that says which rules apply where. A rule is written once.

Rness writes where the agents already look. Claude Code reads CLAUDE.md; Codex, Cursor and GitHub Copilot read AGENTS.md. Rness writes into those files, so every developer keeps their agent, their editor and their workflow. Governance is centralized and development stays where it is.

Decisions carry their reasons and their status. An ADR goes from Proposed to Accepted, a plan from In progress to Completed once its proofs pass. An agent in any repository can find what was decided, why, and what is under way.

One rule, one file

Setting a rule for every agent of an organization is a count of files. Claude Code reads CLAUDE.md; Codex, Cursor and GitHub Copilot read AGENTS.md. A rule kept by hand goes into at least two files per repository, and more once .cursor/rules and .github/copilot-instructions.md are in the mix. Three repositories mean six files or more, forty mean eighty or more. When the rule changes, the count starts again, and nothing tells you which copy was missed.

With Rness the rule is written once, in a standard under .rness/. rness sync rewrites the generated block of every repository from it, and each CLAUDE.md already points to that block. Each repository gets one small commit, and rness sync --check in CI fails any repository whose block falls behind. When I decided that nothing I publish should carry an em dash, it took three lines in one file and one command, and every repository of my workspace had the rule.

One request, three repositories, one release

Here is what that looks like on a real change. I wanted to rename a command of the CLI, rness pulse, to rness board. The old name had come to mean three different things, and rness pulse sync sat next to rness sync with nothing to tell them apart.

I asked for it once, as a specification in .rness, and the agent turned it into a plan. The agent works from the workspace, where the CLI, the documentation and the website sit side by side under the same rules, so it saw everything the rename touched. In under half an hour it committed the new command and its tests in the CLI, then the renamed pages in the documentation. It also updated the website's llms.txt, the file other AI agents read to learn how to use the tool. About two hours after the specification, the new version was on npm.

Nothing in that list was a separate request. A rename in the CLI is also a change to the docs and to what the site tells other agents, and the agent knew it because it could see all three.

One decision, checked everywhere

The second case is a decision. My CLI required Node 24. One day a Claude Code session in one of my own projects, which runs Node 22, opened with a single line: rness needs Node 24 or newer (running v22.22.0). The hook that loads the workspace's context had refused to start, so Rness was switched off in that project, and that line was the only sign.

Lowering the floor to Node 22.17 took a few lines of code. The decision reached much further: the version guard, the engines of three packages, the CI matrix, the CLI's README, the documentation and the website. I recorded it as an ADR, with a plan that gave each change a proof. Minutes after I accepted the ADR, the CLI, the documentation and the website each had a commit citing it.

Then /rness:plan check ran every proof again before closing the plan, and a wider search found two lines the first pass had missed. Both were on the website: its llms.txt still said "Node 24 or later", and so did its structured data. They were fixed the same evening, and only then did the plan close. Two days later the CLI's dependency rule moved to the new floor, to prefer what Node 22.17 already ships, and rness sync wrote it into the CLI's AGENTS.md.

How the rules reach every agent

A workspace is one folder per person: the governance repository and a clone of each repository, side by side.

<your-org>/
├── AGENTS.md          the root block, for a session started here (CLAUDE.md beside it)
├── .rness/            the governance repository
│   ├── standards/     the rules
│   ├── adr/           the architecture decisions, and why
│   ├── specs/         what to build
│   ├── plans/         how, task by task, each with its proof
│   └── rness.json     the repositories, and which rules apply where
└── org/               one clone per repository
    ├── web/
    │   ├── AGENTS.md  the generated block, between its markers
    │   └── CLAUDE.md  points to AGENTS.md
    ├── api/
    └── contracts/

rness sync writes the rules that apply into a generated block of each repository's AGENTS.md, with a CLAUDE.md that points to it. Here is the top of the block in my landing page's repository:

<!-- BEGIN rness -->
<!-- rness · scope: web · contract: 1 · hash: 69ac389a2b6b · generated: run `rness sync`, never edit inside this block -->
...
<!-- rness: standards/architecture.md -->
# Architecture and repository strategy

Each standard names its file in .rness, so a reader knows where to change it. Claude Code also gets hooks: one loads the workspace's context when a session starts, another refuses an edit inside the generated block. MCP clients get the same context, read-only, from rness mcp. I have checked Claude Code, Codex, Cursor and GitHub Copilot, and any agent that reads AGENTS.md gets the rules the day it reads the file.

rness board push puts every decision, specification and plan on a GitHub Project, one issue each, and marks the card an agent is working on while it works. I open the board and see what the agents are doing, and why.

Where it is going

What ships today governs what agents know and what has been decided. The next layer governs what they may do: policies with a scope, from the organization down to a directory or a file pattern, so the right rule applies at the right level; a view of the whole organization that shows which repository drifted from them; GitLab and Bitbucket beside GitHub. All of it is specified and none of it is built. The landing page marks it "not shipped yet", and it keeps that mark until it ships.

Some things are by design. Rness reads Markdown and writes Markdown. It runs no model, and your code and context stay in your repositories and on your Git provider. While it is at 0.x, commands and the rness.json contract can change between minor versions, and each release says what did.

Built with Rness, in the open

Rness is built with Rness. Its repositories are members of a Rness workspace and their AGENTS.md blocks are generated. Its .rness holds more than 10 ADRs, 30 specifications and 40 plans, the rename and the Node decision among them. The launch runs there too: this article is a card with a status and a checklist on a GitHub Project.

The code is MIT-licensed on GitHub. Issues labelled good first issue are a way in, and the Discussions take ideas and questions. If your organization codes with agents across several repositories, the problems you hit are the ones I want to work on next.

Try it

npm create rness

It asks for your GitHub organization, or makes a workspace without one with --blank. rness sync writes the blocks and rness status shows every decision, specification and plan. The guide is at rness.dev/docs and the code at github.com/rness-dev/rness. Star the repository to follow where Rness goes.

What has your organization decided that your agents still don't know?

DEV Community: Cédric Magne