Skip to main content
Managed templates are published, versioned bundles of .auto/ files maintained in auto’s template registry. The supported authoring surface has exactly two packages: @auto/agents for complete role entrypoints and @auto/fragments for reusable building blocks. You import a specific file instead of copying it into your repo, and projects that track @latest receive new versions automatically after every registry release.
Legacy per-role and team bundle names are retired. They are absent from discovery and rejected at @latest; only exact historical pins remain resolvable for provenance.

​
Importing a template

A managed-template import is any imports: entry starting with @:
.auto/agents/pr-review.yaml
The specifier grammar is @scope/name[@version|@latest]/subpath:
  • @scope/name — the template’s name. Scope and name may not contain / or @.
  • @version — optional. @latest (or omitting the version entirely) follows the registry’s newest version; an exact version such as @1.5.0 pins.
  • /subpath — required. A template is a set of files, so the import must name one: Managed template import must include a file subpath.
The subpath names the document that merges into your agent. An agent entrypoint such as @auto/agents@latest/pr-review.yaml supplies one complete role. A reusable fragment such as @auto/fragments@latest/tasks/coordinator.yaml layers one concern onto another agent. Your local agent file therefore stays thin: usually a name, one role import, variables:, and only genuinely tenant-specific overlays. Everything on the Imports and fragments page applies to managed imports too, including the rule that later imports win the merge. There is intentionally no whole-package import. @auto/agents and @auto/fragments are libraries, so every import must select one file. There are also no team packages: team presets live in Auto’s internal catalog schema and install the same single-role entrypoints. At apply time, the resolved version’s files are injected into the compile under reserved in-bundle keys (packages/@scope/name/<subpath> for @latest, packages/@scope/name@<version>/<subpath> for a pin) and resolved from there like any other file. This runs identically inside every apply surface — the GitHub Sync apply and every dry run — so they fail or succeed the same way.

​
The catalog

The managed authoring surface is deliberately small. The live catalog — with per-version file listings, required variables, and source links — is available from the auto.templates.list MCP tool (auto tools).
All former per-role, team, onboarding, task, Default, and smoke-fixture packages are retired: they are not returned by discovery or accepted at @latest. Already-published exact versions remain resolvable as immutable history. The permanent default agent is a built-in resource; customize it with .auto/agents/default.yaml, not a managed-template import.

​
@latest vs pinning

An import resolves by its track:
  • @latest (or a bare @scope/name) resolves to the registry’s newest version — the maximum dotted-numeric version among the template’s published versions. Latest-track consumers receive push-apply: when the registry advances, the subscription sweep re-applies your project on the new version automatically.
  • A pin (@auto/agents@1.0.0/pr-review.yaml) always resolves to exactly that version’s content. Pins opt out of push-apply and never receive advisories; upgrading is a deliberate edit to the specifier. A pin to a version the registry does not have fails loudly (Agent import not found) rather than resolving to something else.
The two tracks are fully independent, even within one project: a pinned import and a coexisting @latest import of the same template each resolve their own version’s files (injection keys are qualified by track), so an exact pin can never be contaminated by another import’s version. Exact versions are immutable once published — a pinned import’s content never changes underneath you.

​
Template variables

Templates parameterize per-tenant values with {{ $name }} tokens — a template file’s required variables are exactly the {{ $name }} references it carries. Consumers supply values through a variables: map on the importing agent, and GitHub Sync injects repoFullName and githubConnection automatically from the repo binding, so a forked template repo applies without edits. The full resolution and precedence rules are on Variables and templating. To see which variables a template requires before importing it, use auto.templates.list — it returns structured required-variable names and source links per version — or open the template’s public source. Every template file has a stable, unauthenticated URL:
latest URLs follow the registry head with short-lived caching; exact-version URLs are immutable with long-lived caching. Published YAML responses begin with a comment linking their own exact-version source, plus a second comment listing required variables when the file references any {{ $name }}.

​
The subscription sweep

Tracking @latest only helps if something actually re-applies your project when a new version publishes. That is the subscription sweep. Subscriptions. Every successful GitHub Sync apply records one subscription row per referenced template: the template name, the track, the concrete lastResolvedVersion that was injected, and an integrity hash of the resolved files. When a project has both a pinned and an @latest import of the same template, the @latest track deterministically wins the row — only latest-track rows are swept, and a pin must not silence a coexisting @latest consumer. The sweep. A long-lived background workflow cycles every 5 minutes, scanning up to 50 latest-track subscriptions per cycle with a rotating cursor so every row is reached fairly. For each subscription whose lastResolvedVersion lags the registry’s current @latest:
  • If the project has enabled GitHub Sync bindings, the sweep dispatches one template push per binding — a sync run that re-applies the production branch’s current HEAD with the new template version. The .auto/ files are unchanged; only the injected template content differs. The run shows up like any push apply: a “Sync apply” check on the repo, with the usual diagnostics.
  • If the project has no enabled sync binding (sync since disabled or removed), the sweep records a skip (no_sync_binding). Applies that run outside a sync binding resolve @latest fresh every time anyway, so such a project picks up the new version on its next apply.
The subscription row tracks the last push outcome as dispatched, failed, or skipped — dispatched means the sweep started a push, not that the apply succeeded; success is observable as lastResolvedVersion advancing on the next apply. Deterministic workflow IDs make a re-sweep of the same drift reuse the in-flight run instead of duplicating it. After each successful push apply, the subscription rows are reconciled: every resolved template is upserted, and rows for templates the project no longer imports are pruned — dropping an import also stops its pushes.

​
Bump advisories

When a push apply moves a template to a new version, the apply surfaces what changed as non-blocking info diagnostics on the sync check and comment, one per importing agent:
  • template_capability_expanded — the new version added files the prior version lacked: “Template “@auto/agents” updated 1.0.0 → 1.1.0 and added 2 new files to its bundle. Review the new capabilities and set up any connections they require.”
  • template_override_outdated — your project shadows a template file (the injector never overwrites a file already present at an injection key, so your copy keeps winning) and that file’s content changed in the new version: “…your versions are kept, so reconcile them to pick up the template’s update.”
Neither advisory ever blocks the apply; they exist so a version bump is never silent.

​
Staleness advisory

The template registry is compiled into the deployed backend, so for a short window after a new template version merges — until the backend carrying it deploys — @latest still resolves to the previous version. If an apply runs inside that window and the repo itself declares the newer version (which only happens in repos that publish templates from their own tree), the apply proceeds with the deployed version and the sync check carries a note naming both versions, so the partial rollout is visible rather than silent. Detection fails open — any inability to read the source produces no advisory and never blocks a merge. Ordinary consumer repos never see this advisory, and the sweep reconciles to the new version once it deploys.

​
Grant equivalence

A template’s compiled tools and mounts are its grant surface — what an agent built from it can touch. When a template publishes a variant entrypoint that continues an older version’s behavior (for example a -slack entrypoint preserving a prior Slack-required flow), registry tests pin the variant’s compiled tools and mounts to match the version it continues, modulo an explicitly inventoried exception list (such as read-only mount remainders and mount repositories that became {{ $repoFullName }} parameters, normalized against their hardcoded ancestors). Following such an entrypoint across versions does not silently widen what the agent is permitted to do. Independent of templates, capability gating is re-checked at runtime: for example, GitHub merge and secrets tools require the corresponding mount capabilities regardless of what any template declares. See Tools and Mounts.