Capability Authoring Reference¶
The complete grammar and authoring rules. This mirrors
<Runtime Home>/specs/capability-spec.md, which ships inside the binary and is
refreshed with every version — when the two disagree, the file in your
Runtime Home wins, because it describes the binary you actually have.
Your runtime carries its own contract
This site gets you installed, gets your first capabilities running, and
explains how the pieces fit. Any Runtime command prepares the Home
automatically; engrt bootstrap is the optional explicit report. Start at
<Runtime Home>/RUNTIME-AGENT.md (the contract) and manifest.json
(this binary's providers and operations). Specs and command cheatsheets
for your installed version live in <Runtime Home>/specs/ and
commands/. Read those for precise operational detail — they describe
the binary you actually have. Come back here for concepts, upgrades,
and anything not yet installed.
Operations must come from the published provider surfaces (files, github,
and v0.9.9's bounded gcp project read)
(engrt files --help, engrt github --help, or manifest.json). An
invented operation fails validation rather than running:
The authoring loop is a contract: authoring-context → reuse or edit source
with your own file tools → validate → plan → review. Validation is not policy approval;
a successful plan is not source admission or permission to execute. Publishing
and execution are separate, explicit actions.
Writing your first capability?
Read Create a Capability instead — it walks the whole sequence in order, from finding operations to sharing the result. Come back here for the details.
v0.10.0: versions and step dependencies¶
These additions ship in v0.10.0 and are absent from v0.9.9. The grammar below remains valid for existing capabilities.
The v0.10.0 executable is engrt; read its matching Home contracts before
using new syntax.
| Optional field | Contract |
|---|---|
engrt_version at the top of the runtime block |
Optional installed-binary SemVer constraint, such as ">=0.10.0"; omission keeps legacy behavior |
capability_version at the top of the runtime block |
A nonempty SemVer 2.0.0 string, such as "1.2.0-rc.1+team.7"; omission stays absent |
id on a step |
Unique, case-sensitive ASCII label matching [A-Za-z_][A-Za-z0-9_-]{0,63}; never empty or synthesized |
needs on a step |
1–255 distinct earlier step IDs; both the declaring step and each target require an explicit ID |
Keep version: v1: it identifies the grammar. Capability SemVer is metadata;
it selects no source revision, grants no permission and promises no publication
immutability. Do not put credentials in IDs; recognized secret-shaped IDs refuse.
Malformed versions, duplicate IDs and missing/self/future dependency references
refuse before authentication, execution or capability evidence is written.
Optional top-level engrt_version declares which installed binary can run
this capability, for example engrt_version: ">=0.10.0 <1.0.0". It first
requires Runtime 0.10.0. Omission keeps legacy behavior and adds no implicit
minimum. The string accepts at most eight whitespace-separated SemVer 2.0.0
comparators (=, >, >=, <, <=, or a bare exact version), at most 512
bytes. There is no space between operator and version; all bounds must match.
No v prefix, OR, wildcard, caret, tilde, comma or interpolation is supported.
Build metadata does not affect ordering. Prereleases use SemVer precedence:
0.10.0-rc.1 does not satisfy >=0.10.0; explicitly declare a prerelease bound
when appropriate. Contradictory bounds match no version.
Validate, plan, preview and execute check the binary-owned release version before policy/config/auth probes, effects or capability evidence. A mismatch refuses with an installation hint; it never downloads or selects a binary. Inspect/search expose the declaration and incompatibility without authentication. The requirement cannot override grammar, provider availability or policy and does not change compiled invocation identity; the source digest binds its exact bytes. Older binaries safely reject this new field. Old capabilities without it continue to work on v0.10.0; they need no bulk rewrite.
Execution stays sequential in document order and stops globally at the first
failure, including before independent later steps. Dependencies introduce no
parallelism, conditions, retries, outputs, continuation or rollback. Plans show
IDs/dependencies; step evidence carries capability_step_id and
capability_step_needs. Dependency lists use target document order, so changing
the order of the same set does not change compiled identity. Workflows without
id/needs retain their existing compiled identity under the same Home privacy
key; changing only capability_version does not change that identity.
v0.10.0 installs specs/capability-contract.json beside
specs/capability-spec.md and lists it in manifest.json. The generated contract
records the binary version, grammar window/floor, feature release floors and
bounds. Archives also expose both capability files under specs/. Grammar,
feature support and provider/operation availability are separate; validation
does not promise execution permission or success.
Released v0.9.9 strictly rejects these new fields. Keep default shared sources compatible with older consumers; use a separate opt-in source for new syntax. Publishing 0.10.0 does not automatically upgrade consumers following source main. v0.10.0 also provides local search and inspect, with bounded scans and explicit incomplete results. They do not authorize execution.
Outputs and verification (v0.11.0)¶
Requires v0.11.0
This grammar ships in v0.11.0. Released v0.10.0 fails closed on these
capabilities: it refuses them with a field decode error such as
field outputs not found, before any step runs.
A capability opts in by declaring an engrt_version that excludes every
release before 0.11.0, such as engrt_version: ">=0.11.0". Without it, none of
the keys below are accepted, and ${...} keeps its legacy meaning. This is the
minimum grammar for typed results, live verification and stateless rerun. It is
not a workflow language.
| Key | Contract |
|---|---|
outputs |
Allowed only on provider steps that return typed REST or GraphQL results. Map of name → {pointer, type, optional}:• pointer is an RFC 6901 JSON Pointer, at most 8 levels deep• type is string, integer (exact) or boolean• at most 16 outputs per step; strings at most 4 KiB A missing required output, a wrong type or a credential-shaped value fails the step as output_contract_violation |
${steps.<id>.outputs.<name>}, ${steps.<id>.observation} |
Insert an earlier step's value, which must be listed in needs, as data into one argument. The value is never rescanned. Values that are absent, start with -, contain control characters, contain :// or walk a path (..) refuse the step before dispatch |
when |
1–4 predicates that must all hold, or the step is not_required: it runs nothing and still satisfies needs |
expect |
1–4 predicates over the step's own result, recorded as a separate verification (passed, failed or unavailable) |
Each predicate has one ref and exactly one of equals, not_equals,
exists: true or missing: true. Values are compared as strings in the
declared type's canonical form, such as "42", "true", PRESENT or
ABSENT. A value may also be exactly one ${input}. There is no OR, nesting or
loop. A missing value never satisfies equals or not_equals, so absent data
cannot open a mutation gate; test absence with missing.
Observation. A curated read reports PRESENT on success and ABSENT on an
authoritative 404; the step succeeds with no outputs. In v0.11.0, these
reads are GitHub repo view, file get, label get and release get.
Authentication, permission, rate-limit and server failures never become
ABSENT. Generic api and graphql have no observation.
One logical operation per expect step. Each chain is:
- an observation step, referenced by the gates;
- optional gated mutations, listed in the
expectstep'sneeds; - the verification read.
Any other shape is refused as unsupported_operation_shape. Two mutations of
one chain may not both run (conflict).
Whether a step reads or mutates is decided from its resolved invocation, never from where it sits in the workflow:
- Verification steps must be read-only. An
expectstep must be provably read-only, such as RESTGET, a GraphQL query or a curated read. A mutation cannot verify its own response. That includes a method or endpoint that comes from a step reference. It is refused before anything runs.validatereports it when the step resolves without inputs;planandexecutealways check. - The observation step must be read-only too. A mutation in the role the gates refer to is refused before anything runs.
- Reads are dependencies, not mutations. A dependency that only reads never
makes an operation
APPLIEDor aconflict, and several operations may share it. Its failure fails every operation that depends on it. GraphQL reads are recognised from the parsed operation, so the word "mutation" in a string or comment does not matter. - Comparison values are checked before any step runs. They are reported back
in
verification, so a credential-shaped literal is refused at validation. A credential-shaped or wrongly typed${input}comparison value is refused asinvalid_input(exit 2) before any step runs.
File content drift needs no encoding operator. GitHub reports a file's git
blob SHA, so compare it with the blob SHA of your literal content (from
git hash-object). Then repair the file by compare-and-set, passing the
observed SHA forward:
- id: update_file
needs: [observe_file]
when:
- {ref: steps.observe_file.observation, equals: PRESENT}
- {ref: steps.observe_file.outputs.sha, not_equals: "<desired blob sha>"}
provider: github
args: [file, put, "${repo}", NOTE.md, message=repair, "content=...", "sha=${steps.observe_file.outputs.sha}"]
engrt_version: ">=0.11.0"
workflow:
- id: observe
provider: github
args: [label, get, "${repo}", "${label}"]
outputs:
color: {pointer: /color, type: string}
- id: create
needs: [observe]
when: [{ref: steps.observe.observation, equals: ABSENT}]
provider: github
args: [api, POST, "/repos/${repo}/labels", "name=${label}", "color=${color}"]
- id: update
needs: [observe]
when:
- {ref: steps.observe.observation, equals: PRESENT}
- {ref: steps.observe.outputs.color, not_equals: "${color}"}
provider: github
args: [api, PATCH, "/repos/${repo}/labels/${label}", "color=${color}"]
- id: verify
needs: [create, update]
provider: github
args: [label, get, "${repo}", "${label}"]
outputs: {color: {pointer: /color, type: string}}
expect: [{ref: steps.verify.outputs.color, equals: "${color}"}]
Run it again from step 1 against the same target and it observes live state
again. The first run reports APPLIED; an identical rerun reports SATISFIED
with no mutation; after out-of-band drift it reports RECONCILED. This is a
stateless rerun: Runtime keeps no checkpoint or resource-state database.
Grammar¶
```runtime
version: v1
inputs:
<name>:
description: <plain-English description>
required: true|false
workflow:
- provider: <registered provider>
args: [<operation word>, ..., <argument>, ...]
- binary: <allowed binary>
args: [<positional arg>, ...]
```
| Key | Level | Required | Meaning |
|---|---|---|---|
version |
top | yes | Spec version this block was authored against |
inputs |
top | no | Named parameters, referenced as ${name} in any step's args |
workflow |
top | yes | Ordered list of steps, executed in order |
provider |
step | one of | A registered Provider (github, files) |
binary |
step | one of | A binary in allowed_binaries |
args |
step | yes | Positional arguments, exactly as typed on the CLI |
description |
input | no | What this input is for |
required |
input | no | Whether execution refuses to run without it |
Each step sets exactly one of provider or binary — never both, never
neither.
These are the only keys¶
The parser rejects anything it does not recognize, naming the offending key and its line number.
transport: rest ✗ not a key — the provider owns that decision
steps: ✗ it is `workflow:`
command: ✗ from the retired command registry
capability: ✗ there is no capability step
This strictness is the point. Before it, transport: rest on a step or
steps: instead of workflow: validated clean while doing nothing — a
file that looked correct and silently skipped its work.
args are the CLI, sequenced¶
A step's args are exactly the words you would type after engrt <provider>,
split into a list.
| On the command line | In a capability |
|---|---|
engrt files read ./a.txt |
provider: filesargs: [read, ./a.txt] |
engrt files write ./a.txt hello |
provider: filesargs: [write, ./a.txt, hello] |
engrt github repo view cli/cli |
provider: githubargs: [repo, view, cli/cli] |
engrt github repo list acme per_page=100 |
provider: githubargs: [repo, list, acme, per_page=100] |
engrt command run gh repo list --limit 10 |
binary: ghargs: [repo, list, --limit, "10"] |
This is the same surface, just sequenced inside a file instead of typed one command at a time.
Curated CLI targets — v0.9.9¶
Curated GitHub CLI steps require an explicit repository. PR creation additionally
requires an already-pushed --head; it does not infer commits from your clone.
The configured credential host is fixed and execution starts in a private cwd.
For example, declare a required repository input and use:
Unknown flags, ambiguous repositories, browser/editor/recovery and PR --fill
variants refuse. Raw binary: gh remains limited to repo list; a curated CLI
operation is not blanket raw-command support. Plan before separately authorizing
execution. A successful plan neither authenticates nor proves native success.
The maintained workflows github-workflow-dispatch-and-list,
github-actions-run-inspect, github-issue-create-and-list, github-repositories
and github-pr-open-and-inspect now require repository; the last also requires
head. Update callers when selecting that corpus revision. Do not supply guessed
IDs or repeat a write workflow to discover a result. There is no output chaining.
See GitHub's exact target contract
and the installed <Runtime Home>/specs/provider-conformance.md support table.
Maintained GCP reads — v0.9.9¶
All gcloud workflows in the v0.9.9 corpus require project, with an explicit
--project=${project} and native --format=json on each step. Missing or empty
project refuses before any step. Use short project/location/repository IDs, not
fully qualified resource paths; an input description is not a validation regex.
Update existing callers and consumers of native text output when selecting this
corpus revision. Runtime's --output json envelope does not itself request JSON
from gcloud.
The new gcp/gcp-project-read-proof.md performs one projects describe with
matching positional/global project. Supply a project ID, not number, so an
external acceptance check can compare steps[0].data.projectId exactly. Check
exit/status and JSON media type too; capability v1 has no assertion or chaining
field. A matching project response does not prove the effective principal.
Select native credentials outside the workflow, enable GCP authentication and
map command_providers.gcloud: gcp. CLI credentials and ADC are distinct. Keep
the exact proof-source digest across the local, CI WIF and GKE acceptance lanes;
synthetic corpus tests alone do not establish live provider access. Verify the
admitted source and target in your deployment environment. The Docker build/push
example has a separate helper/credential lifecycle and is not this read proof.
See native-auth limitations.
Strict admission and literal inputs — v0.9.9¶
Runtime v0.9.9 accepts exactly version: v1, one complete runtime
fence and one YAML document. Other fenced examples are prose, not authority.
Extra documents/blocks, unclosed runtime fences, duplicate or unknown keys,
anchors/aliases, custom tags and implicit scalar coercion refuse. Quote numeric
arguments such as "-5"; input required is a YAML boolean, not yes or a
quoted string. A workflow is nonempty and each step selects one provider or binary.
${name} references a declared input, with names matching
[A-Za-z_][A-Za-z0-9_.-]* (maximum 128 ASCII bytes). Expansion visits original
argument text once; inserted values are never expanded again or split into
shell words. $$ emits $: use $${NAME} and $${{ github.ref }} for literal
templates destined for another system. Bare $HOME and $(...) stay text;
Runtime does not evaluate them. Unknown/malformed references or unknown supplied
inputs refuse. Missing required inputs are reported in sorted order; an absent
optional input becomes empty, preserving the argv element.
| Budget | Maximum |
|---|---|
| Whole Markdown source, including prose | 1,048,576 bytes |
| YAML depth / nodes | 32 levels below the document / 16,384 nodes |
| Steps / declared or supplied inputs | 256 / 256 |
| Arguments per step / workflow | 256 / 8,192 |
| YAML scalar, input value or expanded argument | 65,536 UTF-8 bytes |
| Total supplied values / expanded workflow argv | 1,048,576 bytes each |
Arguments and supplied values must be NUL-free UTF-8. Reads are byte-bounded;
node-tree limits are checked before typed decoding and alias expansion. The
whole workflow compiles before auth or effects, including input byte budgets.
The version-exact installed specs/capability-spec.md remains authoritative.
These are intentional compatibility corrections, not a new grammar version.
Policy match diagnostics name the rule family and one-based index rather than echoing the invocation or rule value. This avoids reintroducing omitted file content through the plan's decision text; matching and allow/deny are unchanged.
Discovering operations¶
Do not guess at operations. Every provider publishes its full surface, and that published list is the authority:
The same list is on disk at <Runtime Home>/manifest.json, generated from the
registry that executes, so an assistant with no network still has the correct
surface. <Runtime Home>/RUNTIME-AGENT.md is the vendor-neutral contract for
this binary. v0.9.8 has files and github; v0.9.9 also has
gcp project describe over REST. Other tool sheets document reviewed Command
Engine paths, not automatic admission of every native operation.
The help output lists every operation, its argument form, and the transport the provider chose for it. The transport column is information, not a choice.
engrt capability list # what this install can already resolve
engrt capability validate ./my-capability.md
A successful validate is the document/compatibility gate before
engrt github file put. It is not source admission and not permission to
execute.
Reliable one-ask authoring¶
For every human or AI authoring session:
- Run
engrt --output json capability authoring-contextand use its installed contract paths/digests and exact selected source. Ifauthoring_readyis false, report the reason; never fall back to the first source or Runtime Home cache. - Run
engrt capability listand reuse or extend a definition when one already serves the outcome. - Ask for any missing target facts or required inputs. Never invent them.
- Write the Markdown under
selected_source.dirwith your own editor or agent file tools. Authoring is source editing, not a File Engine operation, and does not require afile_policy.write_rootsgrant. - Run
engrt capability validate <path>until its grammar and operation references are clean. - Run
engrt capability plan <path> --input key=valueuntil every step is allowed. Plan resolves substitutions, context and policy, but does not authenticate, execute, use the network, mutate or audit. - Show the path, source, digest, diff and plan. Commit/publish only on an explicit request; execute only as a separate explicit action.
Identity allow-list evaluation is deferred during plan because identity is intentionally resolved only during execution. That does not weaken execution: the full auth and identity checks still apply then.
Pushing a new file¶
Author into the exact directory capability authoring-context reports, never
silently into Runtime Home. Since 0.9.2 that is normally the one directory named
by ENGRT_CAPABILITIES_DIR, with nothing configured first; write the file with
your own editor or agent.
Publishing is a later explicit action, and remains governed — the push is:
engrt github file put owner/repo capabilities/my-cap.md \
message="Add my-cap" content="$(cat ./my-cap.md)"
The provider UTF-8/base64-encodes content. Do not hand-build
github api PUT …/contents/…. Omit sha to create-only; pass sha=<blob>
to compare-and-set.
The rules¶
1. Never hardcode auth¶
Every step already goes through the Auth Engine via the provider or binary it names. A capability never embeds a token, credential, or auth flow of its own.
2. Never assume a Runtime Context beyond what's active¶
If a workflow genuinely needs a specific org, project or namespace, declare it as an input:
inputs:
organization:
description: GitHub organization to audit
required: true
workflow:
- provider: github
args: [repo, list, "${organization}"]
Nothing falls back to a Runtime file. A value the workflow cannot invent —
an organization, a project, a namespace — is a declared input, and Runtime
supplies none of them on your behalf. A value that really is where you are
rather than what this run is about comes from the native tool: leave it out
of the capability and let kubectl or gcloud decide.
3. Ask when a required input is missing¶
Don't invent a placeholder and execute anyway. capability execute refuses to
run with a missing required input; respect that at authoring time too.
4. Only reference what the runtime can execute¶
A step's provider must be registered and its args must name a real
operation of that provider. A binary must be in allowed_binaries, and its
exact native mode must satisfy context/auth/environment and the compiled floor.
5. Never depend on a transport¶
Write provider: github / args: [repo, list], never "the REST one". If you
need a specific wire protocol, the provider is missing an operation — add the
operation.
6. Don't finish until inputs are resolved¶
A capability referencing ${organization} isn't done until the author knows
where that value comes from.
Input substitution¶
${name} substitution is literal text replacement, performed before
execution.
inputs:
path:
description: Where to write
required: true
workflow:
- provider: files
args: [write, "${path}", "hello"]
An unsupplied optional input stays literal
An input you declare but do not supply remains in the arguments as the
literal string ${name}. That is why every shipped example marks its
inputs required: true. Prefer required: true unless you have a concrete
reason not to.
Passing a tool's own flags¶
Because a CLI-backed operation forwards arguments verbatim, a capability may pass that tool's own flags — including output flags:
This is not naming a transport. You are passing arguments the operation accepts; the provider still owns how it delivers them.
In v0.9.9, an admitted GCP read can request typed results
with native --format=json or --format json. Command steps and direct commands
use the same JSON-selector contract.
There is no new capability output: field. Unrecognized/transformed forms stay
text; malformed, empty or truncated declared JSON fails after dispatch, retains
the failed step and does not run later steps. Do not replay it merely to repair
its output. These flags do not change context, authentication or policy admission.
For the runtime's own output format, use the global flag at execution time rather than inside the file:
Composition: there is no capability: step¶
A capability cannot invoke another capability. There is no capability: step,
and engrt is not an allowed binary — so a binary: engrt step fails
validation too.
Large workflows inline the smaller ones they re-derive, and declare a Lineage section in the prose naming what was inlined:
## Lineage
Re-derives:
- `github/repo-health` — steps 3–5
- `files/scaffold-service-docs` — steps 9–12
The prose has no effect on execution. It exists so a reader can tell what a long workflow was assembled from, and so a change to a source capability has a findable set of dependents.
Worked example¶
Turning an ad-hoc audit into a capability:
# Repository standards audit
Answers "what do we own, and does this repo meet standard?"
## Lineage
Re-derives `github/repositories` for step 1.
```runtime
version: v1
inputs:
organization:
description: GitHub organization to audit
required: true
repository:
description: Repository to inspect, as <owner>/<repo>
required: true
workflow:
- provider: github
args: [repo, list, "${organization}", per_page=100]
- provider: github
args: [repo, summary, "${repository}"]
- provider: github
args: [api, GET, "/repos/${repository}/community/profile"]
```
engrt capability validate ./audit.md
engrt capability execute ./audit.md \
--input organization=my-org \
--input repository=my-org/orders-api
Note what the capability does not say: which transport serves each step. Step 1 happens to go over REST, step 2 over GraphQL, step 3 over REST — the provider decides, and can change its mind in a later Runtime version without breaking this file.
Known limitations¶
Worth knowing before you design around them:
| Limitation | Consequence |
|---|---|
No mkdir operation |
files write fails when parent directories are missing — create the path some other way first |
files delete denied by default policy |
Use git rm for recoverable removal, or change policy deliberately |
| No encoding primitive | Base64 payloads must be written literally in the file |
| Execution stops at the first failure | Capabilities are not transactional — earlier steps have already run |
| No loops, no conditionals, no branching | A capability is an ordered list. Complexity belongs in what you compose, not in control flow |
| No capability-to-capability calls | Inline and declare Lineage |
These are properties of a deterministic execution format, not a backlog. A workflow that needs branching is usually two capabilities and a decision.
Validation¶
Reports every problem found, not just the first. See Validate & Execute.
When a capability declares capability_version, audit lineage records that exact
SemVer as capability_version on capability start/completion, every step
intent/completion and ordinary audit records, including preview and failed runs.
It comes from the same loaded snapshot as capability_digest; it is an author
label, not proof of immutable publication. Missing declarations remain omitted
for legacy capabilities. Source and compiled invocation digests keep their
existing meanings; declaring a version does not select historical content.
Naming distinction for v0.10.0: a capability's engrt_version is an allowed
version range; an audit event's engrt_version is the actual executing release.
Generated capability-contract.json and Home manifest.json retain their
existing runtime_version binary-metadata key; generated feature floors use
minimum_runtime_version. These are separate schemas, not declaration aliases.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.