Rness
Your organization's standards, decisions, specs and plans, written into
every repository's AGENTS.md. Claude Code, Codex, Cursor and GitHub
Copilot already read that file: nothing else changes in how you work.
A team that codes with agents across several repositories ends up with a
CLAUDE.md copied by hand into each one, changed in one and not the
others. Rness keeps the rules in one repository, .rness, and writes what
applies into each repository. It never runs a model and is not an agent.
npm create rness
Website · Documentation ·
CLI reference and changelog ·
Discussions
What you get
- One context repository.
.rness/ holds the organization's
standards, ADRs, specifications and plans as Markdown, with a
rness.json that maps them to the repositories they apply to.
- A generated block in every repository.
rness sync writes the rules
that apply into each clone's AGENTS.md (and a CLAUDE.md that points
to it). rness sync --check fails CI when a block is out of date.
- Claude Code wired in. Hooks load the workspace context at session
start, refuse an edit of what
sync generates, and check every edit under
.rness/ before it is written; the /rness:status, /rness:adr,
/rness:spec and /rness:plan commands run the document lifecycle from
the conversation, and the plugin's mod keeps the workspace in view: a
band above the prompt, the status line, /rness:status in a pane;
rness mcp serves the same context to any MCP client.
- Where everything stands.
rness status shows every decision,
specification and plan and its status, in a terminal or as Markdown.
rness board push puts them on the boards rness.json declares (a
GitHub Project, GitLab issue boards, or a Jira space's board), first
Agent Pulse: one issue per document, the card an agent is working on
marked while it works.
- Upgrades without surprises. The CLI version is pinned in
.rness/package.json; every rness in the workspace delegates to it.
rness upgrade moves the pin and merges the scaffold's changes with git.
Quick start
npm create rness # asks where your organization lives (GitHub, GitLab or Atlassian), or a blank workspace
cd <your-org>
rness add <repo> # clone a repository of the organization into org/<repo>
rness sync # write the generated block into each clone
rness status # every decision, spec and plan, and its status
npm create rness joins the organization's .rness when it exists, or
starts one. A workspace is a directory per person:
<your-org>/
├── .rness/ standards, adr/, specs/, plans/, rness.json (the context repository)
└── org/<repo>/ one clone per repository, each with its generated AGENTS.md block
No organization yet? npm create rness <name> --blank makes a
workspace without one; bring repositories in with rness add <owner>/<repo>
or a git URL.
The full reference, every flag and the changelog of each release:
packages/cli/README.md. The guide for users:
rness.dev/docs.
Agents
Rness writes files, not prompts. Any agent that reads AGENTS.md gets the
organization's rules: Claude Code, Codex, Cursor and GitHub Copilot are the
ones verified to. Claude Code gets more, through its .claude/ files: the
hooks, the skills and the MCP server above.
Packages
All three share one version. Rness is at 0.x: commands and the rness.json
contract can still change between minor versions; the changelog says what
did.
Develop
Node 24 or later to develop (the published CLI runs on Node 22.17 or later, ADR 0010), pnpm through Corepack, TypeScript.
pnpm install
pnpm lint && pnpm format:check # eslint, prettier (CI runs both)
pnpm typecheck && pnpm test && pnpm build # every package
pnpm check:versions [--tag v0.22.2] # lockstep versions; with the tag before a release
pnpm lint:fix && pnpm format # apply the fixes
RNESS_NO_DELEGATE=1 node packages/cli/src/bin/rness.ts --help # run the CLI from source
Try a release before publishing it, through a local npm registry
(verdaccio, state in .verdaccio/):
pnpm verdaccio start # registry on http://127.0.0.1:4873 (VERDACCIO_PORT to change)
pnpm verdaccio deploy # build, then publish every package to it (never to npmjs)
export npm_config_userconfig="$PWD/.verdaccio/npmrc"
cd "$(mktemp -d /tmp/rness-XXXX)" && npm create rness <org> # the published shim, as a user runs it
unset npm_config_userconfig
pnpm verdaccio stop # or `clean` to also delete what it stored
deploy replaces a version already deployed, so it can run again after a
change; it also clears the npx cache (<npm cache>/_npx), which would
otherwise keep serving the first copy of that version to npm create.
Maintainers release by tagging vX.Y.Z on main: a tag on any other commit
fails before a dependency is installed. GitHub Actions builds, checks and
packs the packages in a job that cannot publish, publishes the archives to
npm from a job that runs nothing of the project (actions pinned by commit,
npm pinned, no dependency cache), then starts the Release workflow of
rness-dev/docs, which opens the pull
request that freezes the docs for that version. That last step needs the
repository secret DOCS_RELEASE_TOKEN (Settings, Secrets and variables,
Actions): a fine-grained personal access token with Actions read and write
on rness-dev/docs only, since a workflow's own token cannot start a
workflow in another repository. Without it, or when GitHub refuses it, the
run warns and the docs wait for their hourly run.
The same run then calls the Release workflow, which creates the tag's
GitHub release from the version's section of the changelog
(## 0.20.1 — <tagline> in packages/cli/README.md): write that section
before tagging. Without it the release fails, the packages already on npm,
and a re-run reads the same commit. Write the section on main, then run
Release by hand (Actions, Release, Run workflow, on main, with the tag):
it reads the changelog of the branch it runs on. The same run releases a tag
that never had one. A release already there is left as it is, and only the
highest version is marked Latest, whatever order the releases are made in.
node scripts/release-notes.mjs v0.20.1 prints the notes it would write.
Community
Rness is built with Rness: this repository is a member of the rness-dev
workspace, its AGENTS.md is generated, and its specifications and plans
run on Agent Pulse.
Licence
MIT.
