.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.
Importing a template
A managed-template import is anyimports: entry starting with @:
.auto/agents/pr-review.yaml
@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.0pins./subpath— required. A template is a set of files, so the import must name one:Managed template import must include a file subpath.
@auto/agents@latest/pr-review.yaml supplies one complete role. A reusable fragment such as @auto/fragments@latest/shepherd/default-chat-channel.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 theauto.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.
@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.
September 6, 2026 release
The merged registry adds these exact versions:
In
@auto/agents@1.12.0, Admiral, Bouncer, Chief of Staff, Coroner, Designer, Exorcist, Herald, Incident Response, Renovator, Self Improvement, Senior Engineer, and Staff Engineer set model: { provider: openai, id: gpt-6-astra } and reasoningEffort: xhigh. Designer and Senior Engineer move from medium, while Herald and Incident Response move from high; the other listed roles retain xhigh. This is a template-default change, not a claim that every role or tenant override uses that model.
These are merged release contents, not confirmation that a backend deployment or project apply completed. Check the deployed catalog with auto.templates.list and verify the version resolved by your apply. Existing exact-version entrypoints remain unchanged. In particular, keep the 1.11.0 Incident Response pin when you still need its custom-webhook endpoint; the 1.12.0 PagerDuty workflow requires its provider connection and different event payloads.
September 7, 2026 release
The merged registry adds immutable@auto/agents@1.13.0 with four new role entrypoints:
The release includes the two Datadog entrypoints’ sibling scope fragments. Previously published exact-version content is unchanged. Before importing, confirm
1.13.0 and the selected file in the deployed auto.templates.list catalog, provide the role’s required variables and connections, and verify the version resolved by a separately authorized apply. A merged registry release does not prove backend deployment, tenant installation or live provider operation. Existing exact pins do not move to this release automatically.
September 8, 2026 release
The merged registry adds immutable@auto/agents@1.14.0. Its pr-review.yaml requires upsert_issue_comment for every verdict and exposes exactly pull_request_read and upsert_issue_comment, replacing the append-only add_issue_comment tool. The current-head review workflow, including re-review after a head change and the prohibition on file edits, submitted approvals and merging, is unchanged.
Previously published versions remain unchanged; @auto/agents@1.13.0/pr-review.yaml still selects add_issue_comment, and exact pins do not advance automatically. Before relying on 1.14.0, confirm that version and entrypoint in the deployed auto.templates.list catalog, verify the resolved installation after normal GitHub Sync, and inspect the tool snapshot of a newly created reviewer session. A merged registry release is not proof of backend deployment, tenant installation or successful verdict publication. Existing sessions retain their creation-time tools; this release neither upgrades those snapshots nor establishes recovery of an earlier failed review.
September 9, 2026 release
The merged registry adds immutable@auto/agents@1.15.0 and @auto/fragments@1.10.0, publishing the previously canonical-only workflows described below:
Bouncer’s close instructions retain the final artifact outcome and release the PR binding without declaring session completion. Incident Response’s resolution trigger also removes
effects.complete while retaining its entity release. The Datadog roles finish a quiet turn while preserving case and PR continuation; inactivity is not evidence that an investigation or fix is complete. PR Review retains its upsert-only verdict policy.
Previously published files remain unchanged, but each nested import has its own version track. For example, @auto/agents@1.14.0/staff-engineer.yaml still imports @auto/fragments@latest/base-engineer.yaml: pinning the role does not pin that fragment. Review the resolved import tree and tenant overrides rather than treating an exact role pin as a frozen dependency tree.
Check both exact versions and their files in the deployed auto.templates.list catalog before relying on them. This merged registry release does not establish catalog deployment, an applied tenant configuration, new-session snapshots, live scheduled delivery or resolution of an earlier security finding. Existing sessions retain their creation-time instructions and tools; the repository’s pinned Pentester facade is not rewritten by this release.
Repository Chief responsiveness experiment
Thefractal-works/auto Chief facade overrides its managed import with model: { provider: openai, id: gpt-5.6-luna } and reasoningEffort: low. This is a tenant-only experiment, not a change to published template defaults, staff model tiers or other installations.
Its final prompt section directs Chief to acknowledge a human request in the originating conversation before investigation or dispatch, then reuse the existing task owner for substantive work. Routine replies focus on the outcome and next step; coordination follows material milestones, blockers and decisions rather than repeated reminders or duplicate investigations.
The hourly heartbeat remains cron: "0 * * * *" with route.to: slot and onUnmatched: drop. Its instructions now reconcile retained obligations first and inspect only concrete overdue milestones, failures, blockers or missing continuity, rather than sweeping every installed tier. Expected CI, review, human-decision and recorded deployment waits are not treated as stalls. One compact roster retains ownership, authority, evidence and exact-SHA deployment waits; bindings remain continuation pointers.
The cadence change does not weaken exact-head CI, independent clean review, unresolved-finding checks, freshness rules or explicit human scope and merge decisions. A changed head requires a fresh verification cycle. These are authored instructions, not measured latency improvements or proof of model availability. Normal GitHub Sync and new-session activation remain separate from source readiness; the experiment does not itself update an existing session, apply resources or authorize a Chief restart.
Daily upstream dependency maintenance
The@auto/agents@1.13.0 entrypoint upstream-dependency-maintainer.yaml defines a daily check of one target dependency against a public GitHub upstream. Its instructions require a focused human-review PR, an evidence-backed no-op, or a blocked report.
The immutable
1.13.0 release is merged; backend deployment and separately authorized tenant installation remain distinct steps. Before importing, check auto.templates.list for the deployed version and entrypoint. Release contents alone do not prove installation or live operation.
The default heartbeat runs at 06:41 UTC daily, with
concurrency: 1 and route: { to: slot, onUnmatched: spawn }. Missed days reconcile the next observed current candidate rather than replaying release history. This is not a release-event subscription, polling cursor, or backfill system.
For the upstream lookup, the template requires one credentialless request to GitHub’s /repos/{owner}/{repository}/releases/latest endpoint with a 15-second timeout. It requires a release ID, tag and publication time, plus draft=false and prerelease=false. This selects GitHub’s latest stable candidate, not the highest version by comparison and not every published release. Target credentials must never be sent upstream; upstream text is untrusted data, not instructions.
Outcomes and recovery
Deduplication uses the target pin and open, merged and closed PR history, not session memory or a heartbeat delivery ID. PR bodies preserve this marker with the configured names and numeric GitHub release ID:
none. Its instructions also forbid provider-state changes, secret inspection, production applies, deployment, merging, queueing and auto-merge. Canonical contract tests are not live execution proof: an authorized installation must demonstrate a scheduled result, duplicate/retry without a second PR, stable-only selection and recovery after a failed read before claiming operational success.
Sentry issue triage
The@auto/agents@1.13.0 entrypoint sentry-triage.yaml investigates one Sentry issue and requires an evidence-backed recommendation, a small validated draft fix PR for human review, or an explicit no-safe-fix/failure report. The immutable release is merged, not proof of a backend deployment or tenant installation. Check auto.templates.list for the deployed version and entrypoint before a separately authorized installation; source tests do not prove live operation.
The configuration and finalization steps in this section describe that published entrypoint, unchanged in @auto/agents@1.14.0. The separately published @auto/agents@1.15.0 uses a single Public App connection and an inactivity policy that replaces self-stop. Keep the legacy and new contracts distinct; an existing pin, MCP-only grant or session does not automatically acquire the new tools or instructions.
Configuration and evidence
All eight variables are required for the published 1.13/1.14 entrypoint:
The template creates neither connection. Its Sentry tool allowlist is exactly
get_sentry_resource, search_events, and search_issues, used for read-only investigation. The target mount grants contents/PR writes and issue/check/Actions reads; workflow, secret and merge capabilities default to none. There is no Slack tool. Instructions forbid Sentry mutation, provider setup changes, secret inspection, production applies, deployment, merging and auto-merge.
Use normalized sentry fields, not raw webhook content. The adapter emits sentry.codeMapping.status: unmapped: the configured repository is a candidate, not a proven source mapping. The agent must confirm live organization, project and status, then corroborate source and release evidence before editing. Missing mapping, reproduction, access or evidence means no safe fix, not a speculative PR. Reports and PRs must redact customer data and secrets.
Shared issue intake and delivery
Inbound issue delivery uses shared installation receipts, not exclusive installation ownership or an unscoped outbound MCP grant. This is separate from runtime Sentry telemetry. The platform operator configures these variables for/api/v1/event-sources/sentry/events on the deployment’s public origin:
Missing or invalid App identity, or a missing secret, rejects intake. Raw-body signature, timestamp, and request-identity validation precede receipt creation; installation notifications also verify the configured App UUID and slug. A known installation must match its stored App identity.
An issue receipt freezes its authorized recipients, including an empty audience before consent. Each recipient needs an active installation and grant, an enabled subscription, verified project visibility, and the required capabilities, selected resources, and allocation for its tenant and destination project. Retrying an old receipt cannot add later subscribers or recreate deleted event rows. Shared events include
sentry.subscription.id; their entity binding identity includes the grant, subscription, and issue, keeping destination subscriptions separate. A failed immediate dispatch leaves pending events for the existing retry path, not a new audience.
Installation created and deleted notifications are control receipts, not agent trigger events or tenant authorization. They do not allocate projects or initialize credentials. A deletion invalidates only that installation and its subscriptions. Its retained deletion record also blocks later verification of the same installation UUID, even if deletion arrived before installation verification; a delayed created notification does not restore it.
Authorization is checked again before creating a session, before queuing a continuation to its actual destination, and before injecting initial prompts or queued continuations into a session. The injection check uses persisted event and session provenance, including initial-prompt ledger provenance, rather than trusting a producer-supplied event ID. Missing or foreign shared receipts, stale installation/subscription generations, and revoked access deny delivery. Denied commands and turns become failed, existing input ledger rows become rejected, and unrelated commands can still proceed. Revocation committed before admission blocks delivery; it does not recall input already admitted to a session.
Revoking an organization grant disables that grant’s subscriptions in the same transaction as access revocation. The Sentry row’s Disconnect instead removes only the current auto project’s allocations and subscriptions, preserving the shared grant and other projects. Unsubscribing one project affects only its subscription; later resubscription does not reauthorize old event generations. Neither operation remotely uninstalls the App, even for its last subscriber. Sentry trigger test-fire is rejected as unsupported; do not use it as activation proof. Shared events skip the legacy App-control-backed remote lifecycle acknowledgement notes. Legacy persisted Sentry events without shared receipt provenance retain their existing behavior; new webhook ingress does not fall back to that path.
Issue and PR lifecycles
Entity identity is grant-scoped, and the template has no agent-wide concurrency cap. There is no
sentry.issue.updated event. Sentry’s issue.unresolved maps to sentry.issue.reopened; regressed_or_escalating is ambiguous, not proof of a regression. The adapter’s recovery lifecycle means reopen, not terminal resolution. A report or PR does not end an unresolved investigation, and closing a PR does not resolve the Sentry issue.
Fix-PR opened, reopened, synchronize, CI, review, conflict and close events route only to an existing PR owner; unmatched events never spawn. Head changes, including auto-authored updates, invalidate stale validation/readiness and require fresh scoped validation. Readiness requires current-head CI and the repository’s required review policy; the agent must not poll for checks. Closing a fix PR releases only its PR binding. A later PR reopen drops unless a live investigation has explicitly rebound the verified open PR.
Duplicate-safe outcomes
The stable source key is installation ID, project ID and issue ID, carried in the remediation PR body:validationCommand, and create or update one draft PR. Never push failed validation or unrelated changes. Preserve evidence, tests, risks and the source marker. Every outcome needs a durable session report with the source key, issue link, impact, evidence/confidence, diagnosis, action or no-op reason, validation, PR link, and missing evidence or next human step. Tool outages and rate limits are gaps, not success.
Finalize only after durable reporting
On resolution, stop new work rather than stopping the session immediately. A delayed created/reopened delivery whose live issue is already resolved follows the same no-new-work finalization path:- Get the current session ID with
auto.session.getand fresh-read any fix PR. - For an open PR, upsert and read back a human handoff with its link, head, checks and unfinished work. State explicitly that automated PR follow-up ownership ends on self-stop. This requests human pickup; it does not claim acceptance, close the PR or prove a fix shipped.
- Publish the final session report, including the handoff or an explicit no-PR outcome, and confirm its completed entry through
auto.sessions.conversation. - Only after those records are confirmed durable, call
auto.sessions.stopon this session with the final report and PR handoff inhandoff, omittingrespawn. Successful stop releases remaining session-lifecycle bindings, including the fix PR.
effects.complete; the router applies bind/release effects, not that completion flag. Its seven-day session.archiveAfterInactive setting is presentation-only, not an issue-resolution or binding-expiry timeout. Missing terminal events require operator investigation; the template adds no scheduler or inactivity backstop.
TEST mode and rollout proof
The project filter also acceptsauto-test-project for marked synthetic events. For auto.test: true, the template requires a TEST session report with externalWrites: none: no provider queries, pushes, PRs or handoff comments. Synthetic resolution uses only internal reporting, readback and self-stop.
After the repository-generated immutable release is deployed, an authorized installation needs valid inbound registration/resource ownership, outbound tools and a validated runtime. Proof must cover created/reopened continuity, duplicate delivery without duplicate outcomes, unmatched resolution dropping, other-project exclusion, owned/unowned PR head changes, no-PR resolution, open-PR handoff, delayed live-resolved no-op, and failed finalization without stopping. Verify real report/handoff and stop evidence before any separately authorized predecessor retirement; schema and routing-replay tests alone do not prove runtime termination.
Canonical Sentry connection
This canonical contract is published in@auto/agents@1.15.0/sentry-triage.yaml with seven variables: repoFullName, baseBranch, githubConnection, sentryConnection, sentryOrganizationSlug, sentryProjectId and validationCommand. sentryConnection names one Public App connection for both issue events and investigation; sentryMcpConnection is removed from this entrypoint. The exact Sentry tool allowlist is get_issue_details and search_issues, a subset of the connection’s four read-only tools. The template still creates no connection and grants no provider mutation or merge authority.
Published 1.13/1.14 keeps its eight variables and old three-tool MCP allowlist; do not point that unchanged allowlist at the new four-tool surface and assume compatibility. The merged 1.15.0 release also publishes the retained-follow-up finalization policy. It does not migrate grants, tenant pins or existing sessions. Catalog deployment, authorized installation and newly created session snapshots still require separate evidence.
Canonical inactivity policy
The canonical inactivity changes are published in@auto/agents@1.15.0 and @auto/fragments@1.10.0. They use session.archiveAfterInactive and ordinary end-of-turn settlement instead of declaring completion or stopping a session merely because an artifact has an outcome. Older role files remain unchanged, but their independently tracked @latest fragments can advance. Backend behavior, published template content, applied tenant resources and existing session snapshots are separate boundaries.
These published versions configure the following intervals, not a global platform default:
Repository facade overrides also set reviewers to 600 seconds, documentation/customer-health/Butcher/Janitor/Default/implementer/digest sessions to 43,200 seconds, and incident response to 86,400 seconds. Those authored overrides do not activate new integrations or prove GitHub Sync has applied them. An interval override does not import canonical prompts beyond the pinned version. The platform’s sweeper reads the agent’s configured interval; reopening an existing session does not refresh its snapshotted tools or instructions.
Sentry finalization in canonical source
The finalization contract in@auto/agents@1.15.0/sentry-triage.yaml stops new investigation work on resolution or a live-confirmed resolved no-op, not the session:
- Get the current session ID and fresh-read any fix PR. Report its link, head, checks, unfinished work and current follow-up owner without implying human acceptance.
- Publish the final session report with the handoff or an explicit no-PR outcome, then confirm its completed entry through
auto.sessions.conversation. - Finish the turn without self-stop. Resolution releases the
provider.entitybinding; existing PR and chat bindings remain available for follow-ups to the same session, including after inactivity archiving.
externalWrites: none; it does not query providers, publish artifacts or stop the session.
After catalog deployment and a separately authorized installation, verify the applied interval and newly created session instructions. Prove retained follow-up routing and reopening on genuinely new input, duplicate/suppressed-event non-revival, durable final reporting and the unresolved/closed-PR boundaries. A source or release merge, archive flag or passing source test is not live rollout proof. Inactivity archiving adds no durable sandbox checkpoint/restore guarantee and does not authorize predecessor retirement.
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@latestfresh every time anyway, so such a project picks up the new version on its next apply.
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-blockinginfo 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.”
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 compiledtools 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.