rungs

Installs and maintains a repository’s agentic development system.

Your agent has instructions. Do they have gates? Is your backlog’s status field telling the truth about what actually merged? That thing you noticed last Tuesday — where did it go?

rungs scaffolds the parts of a working setup — agent instructions, skills, work tracking, findings, decision records, validation gates — as modules you pick, then keeps checking that they still say what they said.

Why this exists

Every rule in here was paid for once already.

The content is extracted from four repositories built over six months in different stacks — a .NET ingestion platform, a 105-package Angular monorepo, a set of reference apps, and a full-stack product with 3,236 commits across 401 branches. Each solved part of this by hand. Each also failed in ways the others did too.

So rungs does not ship a good idea about how to work. It ships what four repos learned, with the incident attached. Every module declares its provenance, and doctor quotes that incident back when a gate it installed has never fired:

check-findings-register has run 340 times and never fired. It exists because one repo produced 268 audit reports with no register to close them into. Is that still a risk here — or is this gate scoped too narrowly?

The research is in docs/research/ and stands on its own: four repo autopsies, the eight failure modes all of them hit, and a maturity ladder that prices each practice so you don’t install rung 5 at rung 1.

Install

npx @rungs/cli doctor

It reports what your repo already has, installed or not, and ends by naming one command to run next. Once you have run that: your first hour — which of the new files matter, what the installed skills are for, and what to do when a gate goes red.

Requires Node 22.18+ — it runs TypeScript directly, no build step.

Published as @rungs/cli, not rungs: the unscoped name is unpublishable, being one edit from both rung and runjs, which npm’s typosquat filter refuses. The tool, the command, and everything it writes are still rungs — only the package identifier differs. After a global install the command is plain rungs.

From source:

git clone https://github.com/ThroughTheWind/rungs && cd rungs && npm install
node src/cli.ts --help

What you get

rungs init . tracked writes:

AGENTS.md              # what every session reads — with a line budget that is enforced
CLAUDE.md              # a one-line bridge: @AGENTS.md. Not a second copy
.ai/
  rules/               # path-scoped rules you author, rendered per harness
  gates.toml           # every gate this repo runs
  rungs.toml           # what is installed, and a hash of everything we wrote
.claude/skills/        # spec-compliant Agent Skills — portable to 45+ clients
docs/backlog/          # work items, a board, a findings register
docs/decisions/        # ADRs, with an admission rule that keeps the directory small

Nothing is overwritten, ever. add on a repo that already has a backlog keeps yours and installs only what is missing. Files you edit afterwards are reported as diverged and left alone.

Commands

rungs --help prints the same two tables. For module parameters run rungs modules --params, which renders them from the manifests; what a parameter is and how to set one is docs/design/parameters.md.

Modules

Fifteen, each carrying a rung — how mature a practice is — so add can tell you when you are installing above your level.

concurrency refuses to install without --confirm-threshold, because below five simultaneous sessions every mechanism in it costs more than it returns. Selling rung 5 to a rung-1 repo is the most likely way this tool does harm.

Full specification: docs/design/module-catalog.md.

Which agents

Skills are spec-compliant Agent Skills, portable to Claude Code, Codex, Cursor, Copilot, Gemini CLI and 40+ others without translation.

Only path-scoped rules are genuinely fragmented across harnesses, so that is the only thing rungs renders — into .claude/rules/, .github/instructions/ and .cursor/rules/. Anything a target cannot express is reported, never silently dropped, in .ai/render-report.md.

Reasoning: ADR-0001.

Design commitments

Four promises that shape everything else:

• Your repo gains no new language runtime. rungs writes no gate scripts. Generic gates are declarations run by engines the CLI provides; anything else is a shell command you already own. A .NET repo with no package.json stays that way. (ADR-0002)
• A gate with no engine blocks — it never reports green. A registry passing because most of its gates do nothing is the worst failure this tool could have.
• eject is a promise, not a courtesy. It materialises the engines into your repo and rewrites the registry to plain commands. A tool whose checks vanish when you uninstall it is one nobody should adopt.
• Nothing is measured that needs judgement. The gate ledger records exit status and wall-clock. It never scores your workflow. (ADR-0005)

Status

Pre-release, v0.1.1 — published as @rungs/cli.

rungs is installed in its own repo and its gates run on every change — 20 pass, 0 fail (rungs check, 2026-08-15). Detection is verified against all four source repos. Not yet done: installing into a source repo for real rather than in dry run.

Expect module contents to move. The command surface is settled.

Contributing

Modules are the product, and a module is a directory that looks like what it emits — markdown and TOML, no code. If you can read the repo it produces, you can write one: modules/README.md.

Every module must declare [provenance] with a real incident behind it. A module nobody paid for does not ship.

Repository

Licence

MIT.