Variables and Templating

​

The three grammars at a glance

​

Declared variables

name: pr-review
imports:
  - "@auto/agents@latest/pr-review.yaml"
  - ../fragments/environments/agent-runtime-base.yaml
variables:
  repoFullName: fractal-works/auto
  githubConnection: github-fractal-works

mounts:
  - kind: git
    repository: "{{ $repoFullName }}"
    mountPath: /workspace/auto
    ref: refs/pull/{{payload.github.pullRequest.number}}/head
triggers:
  - name: pr-review
    events:
      - github.pull_request.opened
      - github.pull_request.reopened
      - github.pull_request.synchronize
    connection: "{{ $githubConnection }}"
    where:
      $.github.repository.fullName: "{{ $repoFullName }}"

​

Declaration rules

• variables: is a map of name → value. Names must match [A-Za-z_][A-Za-z0-9_]*.
• Values must be strings, numbers, or booleans; numbers and booleans are coerced to their string form, so a YAML number is usable without quoting. Any other value type fails apply, naming the variable.
• A {{ $name }} reference tolerates inner whitespace: {{ $repo }} and {{$repo}} are equivalent.

​

Scope and precedence

• Variables are declared on the entry agent document — the file under .auto/agents/. The scope flows down the entire import tree transitively; a fragment compiled as an import inherits the entry document’s scope, and any variables: map the fragment declares itself is ignored during that compile.
• Substitution applies to imported content only: the string leaves of every imported document, before that document is parsed and merged. The declaring document’s own body is never substituted.
• Because substitution happens before the merge, the importer’s concrete fields still override substituted defaults through the normal merge semantics — declaring a variable and overriding a field are independent mechanisms.
• With an empty scope (no declared variables and no context variables), imported content passes through byte-identical — every {{ … }} token, $-led or not, is untouched.
• With a non-empty scope, every {{ $name }} token in imported content must resolve. An unresolved reference fails the apply with an error naming the variable, the importing specifier, and the available names:

Unresolved variable "{{ $repo }}" in imported ../fragments/base.yaml:
declare it in the importing agent's variables (available: {{ $repoFullName }}).

​

Context variables injected by GitHub Sync

​

Dry-run parity

• With exactly one enabled GitHub Sync binding on the project, both variables resolve from that binding, exactly as Sync would resolve them.
• With zero or multiple bindings, repoFullName cannot be defaulted; githubConnection falls back to the org’s GitHub connection only when the org has exactly one.
• When a referenced variable cannot be defaulted, the dry-run fails with a message naming the variable, why it could not be defaulted (no candidate, or multiple candidates — listed), and the fix: declare it in variables:, or reduce to a single binding/connection.

​

Runtime event templates

• triggers[].message — the text delivered into a session when the trigger routes an event to it.
• initialPrompt — the kickoff prompt of a trigger-spawned session.
• displayTitle — the session’s title (unless set to the literal infer).

displayTitle: "Review PR #{{github.pullRequest.number}}: {{github.pullRequest.title}}"
initialPrompt: |
  Review GitHub pull request #{{github.pullRequest.number}} in {{github.repository.fullName}}.

​

Rendering rules

• The renderer replaces each {{ path }} token with the value at that dot-path in the event payload. Strings, numbers, and booleans render as their string form; objects and arrays are JSON-stringified.
• A missing or null path renders as an empty string — it does not error. A typo’d path silently delivers blank text, so double-check paths against the event catalog.
• Tokens must not carry a payload. prefix. The apply rejects them at authoring time:

Template renders against the event payload; drop the "payload." prefix
(use "{{github.…}}", not "{{payload.github.…}}").
Offending tokens: {{payload.github.pullRequest.number}}

​

Top-level namespaces per event source

​

Mount ref templates

mounts:
  - kind: git
    repository: "{{ $repoFullName }}"
    mountPath: /workspace/auto
    ref: refs/pull/{{payload.github.pullRequest.number}}/head
    depth: 1

Agent git mount ref depends on event payload path
"payload.github.pullRequest.number" requires session input
(ref: refs/pull/{{payload.github.pullRequest.number}}/head).
This agent must be started by a matching event trigger that supplies that path …

​

File-backed strings

name: staff-engineer
imports:
  - ../fragments/environments/agent-runtime-base.yaml
systemPrompt:
  file: ./prompts/staff-engineer.md

• The path is resolved relative to the declaring file’s directory. Absolute paths and URLs are rejected (systemPrompt.file must be a relative path); a missing file fails apply naming the field and path.
• The file’s bytes are read as UTF-8 and become the field’s value before any merging happens — later phases of compilation see only strings.
• The compiled value is what the schema validates and what renders at runtime, so an initialPrompt file may carry runtime {{github.…}} tokens (and the payload. prefix guard applies to it too).
• Apply-time {{ $name }} variables are not substituted into the referenced file’s contents — only into imported YAML documents.