Self-describing runtime

No commands to memorise¶

Engineering Runtime ships the specifications required to drive it. An assistant reads them on the machine it is running on, works out what the Runtime supports, and writes the work up as a capability — one reviewable file that the Runtime then executes — without having been trained on this product.

Every tool an engineer touches has a command surface to remember. Runtime's own, plus GitHub's, plus your cloud's, plus Kubernetes'. Most of that memory is spent on syntax rather than on the outcome anyone actually wanted.

Runtime is built so that memory is not required — by the engineer, and not by the assistant either. This page is about how that works. Capabilities is about what you build with it, and reads more easily once you know you will not have to learn a command surface to get there.

The Runtime describes what it can execute¶

Installing the binary writes a contract into your Runtime Home, and refreshes it on every version change:

What ships	What it answers
`RUNTIME-AGENT.md`	the rules an assistant is held to, for this exact release
`specs/capability-spec.md`	the grammar a capability must follow
`specs/{provider}/…`	every operation that provider exposes, and a complete worked example
`commands/*.txt`	the shape of each tool's commands, 31 cheatsheets
`specs/schema-contract.json`	which config and policy versions this binary accepts

One command reports the rest — where to write, what policy permits, which providers and binaries are available:

runtime capability authoring-context

That is the whole discovery surface. There is no API to call, no catalogue to fetch, and nothing to be online for.

Two surfaces, two jobs¶

Self-discovery answers one question extremely well and deliberately does not try to answer the other.

	The installed contract	docs.engineeringruntime.com
Where	your Runtime Home	the public web
Answers	what can this exact binary do, and how do I write for it?	what is this, how do I set it up, why did that fail?
Needs	the binary installed	nothing
Version	exact — refreshed on every upgrade	current release
Best for	writing and validating a capability	learning, operating, and debugging

Writing a capability needs the installed contract, because a grammar or an operation list that is one release out is worse than none — it produces a file that looks right and fails on execution.

Everything wider is the documentation site, and it is written to be read by an assistant as much as by a person: concepts, installation, configuration, troubleshooting, and what a particular refusal means. An engineer who hits an error can paste it to whichever assistant they already use and get a real answer, because the pages explaining that error are public and readable — exactly the way an assistant already helps them with Git, Kubernetes, Terraform or any other tool in the stack.

That is the part worth being plain about: Engineering Runtime does not ask to be a special case. An assistant should be able to help with it the same way it helps with everything else an engineer runs — by reading the documentation. The installed contract is the addition, not the replacement: it is there because authoring against a specific release is the one job public documentation cannot do precisely enough.

Why this matters more for AI than for people¶

A person can look something up. An assistant cannot look up a release that did not exist when it was trained — and that is every release, eventually.

The usual failure is not that an assistant refuses. It is that it confidently writes something plausible against a version it half-remembers, and the result fails at the first step that touches reality.

Shipping the contract with the binary removes the guess. The assistant reads what this release supports, on this machine, and where the contract disagrees with what it already knew, the contract wins. A new release teaches itself.

Intent in, deterministic execution out¶

Engineer or assistant — states an outcome: "check every repository in the org against our standards"

Reads the Runtime's published contract — what this release supports, and how a capability is written

Writes or selects a capability — one reviewable file, not a script

Runtime executes it — policy first, every step audited, the same result whoever runs it

The engineer supplies intent. The assistant does the reading. The Runtime guarantees the execution.

The same principle covers the tools underneath¶

A capability names an operation, not a command line. github repo view, not a remembered gh invocation with the right flags in the right order. The provider decides the transport — REST, GraphQL or the tool's own CLI — and the capability never says which.

So the knowledge you would otherwise carry about four different tools collapses into one question: what outcome do I want?

No AI vendor required¶

Engineering Runtime does not depend on a particular assistant, and no customer-facing page names one as the way in.

The reasoning layer and the execution layer evolve independently, which is only possible if the contract between them is public. Any capable assistant that can read the documentation and invoke the binary can participate.

HumanCI/CDAny AI assistantAutomation

Public documented contract Engineering Runtime

The one place vendors genuinely differ is integration mechanics — some tools can block a non-Runtime shell command, most cannot. That is a statement of fact about enforcement, not a recommendation.

Why governed execution matters more, not less¶

Making execution easy is only half of what an organisation needs. The other half is that operations stay predictable, reviewable, and observable — and that need grows when the caller can be an agent.

Requirement	How the Runtime meets it
Deterministic	Capabilities execute against defined contracts regardless of caller
Policy-enforced	Operations are evaluated against policy before execution
Auditable	Executions produce structured records for success, failure, and denial
Existing authentication	Platform and provider mechanisms, not a new credential store
Versioned	Capabilities are files — reviewable, diffable, testable

The goal was never to constrain AI or replace existing tools. It is to put a consistent layer between intent and the systems that matter.

The obligation this creates¶

A Runtime that describes itself has to describe itself accurately. That is the cost of the design, and it is not a small one.

An outdated example, a provider operation that changed, a prerequisite nobody wrote down — each of those is a defect in the product, not in the docs, because an assistant reads them and acts. A published contract that is wrong is worse than no contract at all: it replaces a question with a confident mistake.

The public documentation should describe the behaviour of the released Runtime — not the behaviour of the branch it was written from.

So a Runtime change and the contract it ships travel together, in the same change. A feature is not finished until the specification an assistant will read describes it. If a capability works but nobody — person or agent — can tell from the documentation what it does, the product experience is incomplete no matter how good the code is.

The same honesty applies to the line between shipped and intended. A roadmap item written as though it already works is the same defect as a stale command, which is why Editions marks every row as available, partial or direction rather than blurring them.