relvo-labsrelvo-labs/agent-runtime/AGENTS.md

agent-runtime

AGENTS.md0 starsChanged 47 days agoApache-2.0View on GitHub

Operating contract for automated and human contributors to relvo-labs/agent-runtime. .agents/skills/ is the only skill root in this repository. Do not create .claude/skills/, .cursor/rules/, skills/, docs/skills/ or any other parallel instruction root. tools/skills/validate.ts fails the build if a second active root appears. If another tool needs to see these skills, symlink into the tool's expected location from outside version control — never the reverse, and never inside .agents/skills/ (symlinks under the skill root are a validation error). Before mutating any area…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- changesets-releaseSkill
- local-ci-paritySkill
- npm-releaseSkill
- package-architectureSkill
- package-artifact-validationSkill
- pnpm-supply-chainSkill
- provider-adapter-developmentSkill
- public-api-evolutionSkill
- runtime-contract-evolutionSkill
- runtime-lifecycle-coordinationSkill
- workspace-lifecycleSkill

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Do not create .claude/skills/, .cursor/rules/, skills/, docs/skills/ or any other parallel instruction root.
line 9
Distinctive:
Before mutating any area of this repository, read the skill that owns it.
line 17
Distinctive:
Use that exact pnpm version.
line 40
Very specific:
Every third-party version lives in the catalog: block of pnpm-workspace.yaml.
line 42
Very specific:
All eight public packages have published, immutable 0.2.0 and 0.3.0 versions.
line 67

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Operating contract for automated and human contributors to relvo-labs/agent-runtime.

1. Canonical skill root

.agents/skills/ is the only skill root in this repository.

Do not create .claude/skills/, .cursor/rules/, skills/, docs/skills/ or any other parallel instruction root. tools/skills/validate.ts fails the build if a second active root appears. If another tool needs to see these skills, symlink into the tool's expected location from outside version control — never the reverse, and never inside .agents/skills/ (symlinks under the skill root are a validation error).

2. Read before write

Before mutating any area of this repository, read the skill that owns it.

If you are about to change…	Read first
protocol schemas, wire DTOs, JSON Schema, state machines	`runtime-contract-evolution`
a provider SPI implementation or capability descriptor	`provider-adapter-development`
workspace acquisition, leases, cleanup	`workspace-lifecycle`
runtime commands, side effects, cleanup, subscriptions	`runtime-lifecycle-coordination`
package boundaries, the dependency DAG, tsconfig graph	`package-architecture`
anything exported from a package entry point	`public-api-evolution`
`exports` maps, build output, tarball contents	`package-artifact-validation`
dependencies, the lockfile, install scripts	`pnpm-supply-chain`
version intent for a published package	`changesets-release`
CI workflows or the local gate	`local-ci-parity`
the release workflow or `tools/release`	`npm-release`

.agents/skills/INDEX.md is generated. Run pnpm skills:index after adding or editing a skill; pnpm skills:check verifies it is not stale.

3. Toolchain

Node: use nvm use (reads .nvmrc, currently 24.20.0).
Package manager: pnpm, pinned exactly by packageManager in the root package.json. Use that exact pnpm version; Corepack is not assumed to exist. Do not use npm or yarn to install this workspace's dependencies.
Every third-party version lives in the catalog: block of pnpm-workspace.yaml. Packages must reference catalog:, never a literal range.

4. The gate

One command reproduces CI locally:

pnpm gate

CI runs the identical step list (tools/repo/gate.ts is the single source of truth for both). No gate step may require provider credentials, network access to a model provider, or a publish token — including the release step, which checks the release workflow's structure without being able to publish anything.

5. Hard boundaries for this foundation

@relvo-labs/agent-runtime must never import a concrete provider adapter. It composes neutral SPIs only. pnpm dag:check enforces this mechanically.
Provider-native identifiers, handles and checkpoints must not appear in public DTOs.
existing workspaces are borrowed. Nothing in this repository may delete, reset or otherwise destructively mutate a borrowed workspace.
Zod schemas are authoritative. TypeScript types are inferred from them; JSON Schema is generated from them. Never hand-write a type or a .json schema that duplicates one.
All eight public packages have published, immutable 0.2.0 and 0.3.0 versions; neither version may ever be named in a dispatch again. A 2026-09-27 registry observation found latest at 0.3.0 for all eight. Provider 0.4.0 is not published. Publication happens only through .github/workflows/release.yml: manual workflow_dispatch on main, an explicitly typed name@version scope, a credential-free gate and fail-closed preflight first, then an npm-release environment approval. It refuses to run while any version intent is pending, and it never chooses a version. Read .agents/skills/npm-release/SKILL.md and docs/release.md before changing it; an agent may not initiate a publication.

6. Provenance and licensing

This project is Apache-2.0. Material adapted from third-party MIT sources is attributed in NOTICE and in the ## Provenance section of the skill that carries it, always with a pinned upstream revision. Sources with absent or ambiguous licensing are recorded as "reviewed, not copied" and their text must not be incorporated.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free