Skip to content

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:

capability is invalid:
  - workflow[0]: "does not exist" is not an operation of provider "github"

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:

  1. an observation step, referenced by the gates;
  2. optional gated mutations, listed in the expect step's needs;
  3. 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 expect step must be provably read-only, such as REST GET, 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. validate reports it when the step resolves without inputs; plan and execute always 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 APPLIED or a conflict, 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 as invalid_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: files
args: [read, ./a.txt]
engrt files write ./a.txt hello provider: files
args: [write, ./a.txt, hello]
engrt github repo view cli/cli provider: github
args: [repo, view, cli/cli]
engrt github repo list acme per_page=100 provider: github
args: [repo, list, acme, per_page=100]
engrt command run gh repo list --limit 10 binary: gh
args: [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:

- provider: github
  args: [pr, list, --repo, "${repository}", --json, "number,title,state"]

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:

engrt github --help
engrt files --help

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:

  1. Run engrt --output json capability authoring-context and use its installed contract paths/digests and exact selected source. If authoring_ready is false, report the reason; never fall back to the first source or Runtime Home cache.
  2. Run engrt capability list and reuse or extend a definition when one already serves the outcome.
  3. Ask for any missing target facts or required inputs. Never invent them.
  4. Write the Markdown under selected_source.dir with your own editor or agent file tools. Authoring is source editing, not a File Engine operation, and does not require a file_policy.write_roots grant.
  5. Run engrt capability validate <path> until its grammar and operation references are clean.
  6. Run engrt capability plan <path> --input key=value until every step is allowed. Plan resolves substitutions, context and policy, but does not authenticate, execute, use the network, mutate or audit.
  7. 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"]
engrt capability execute my-cap --input path=./notes.txt

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:

- provider: github
  args: [pr, list, --json, "number,title,state"]

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:

engrt --output json capability execute my-cap --input ...

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

engrt capability validate <path|name>

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.