Provider Sync

Provider Sync is the OAT lane for reconciling a canonical rules-and-skills layout with provider-specific surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.

You can adopt this layer on its own. It does not require tracked OAT projects, and it is the right starting point when you mainly want interoperability and drift control.

In practice, you edit the canonical layout in .agents/, and choose providers in .oat/sync/config.json; the rest of .oat/sync/, such as the manifest, is written by OAT. OAT generates provider-specific views where required, leaves native-read assets in their canonical directories, and keeps intentional provider-local adoption surfaces visible.

WARNING

oat sync and oat init default to scope all, so they also write under your home directory. Pass --scope project when you mean to change only this repository. Re-running oat sync also rewrites the files it generates in provider folders such as .claude/ and .codex/, so an edit made to a generated copy there is lost. Make changes in .agents/ instead.

Piloting with a team? Start with Pilot Provider Sync with One Team.

Pilot Provider Sync with One Team - A week-one plan for trying Provider Sync on one repository.
Provider Interop Commands - oat status, oat sync, and oat providers ... behavior.
Sync Config (.oat/sync/config.json) - Provider config model, enablement, and scope semantics.
Instruction Sync - Project-scoped AGENTS.md / CLAUDE.md validation, repair, and Claude-only adoption.
Manifest and Drift - How OAT tracks synced state, stray files, and adoption decisions.
Providers - Provider-specific mappings, capabilities, and path conventions.
Provider Interop CLI Scope and Surface - Canonical assets, provider views, scopes, and the sync surface area.

What This Section Is

This section explains how OAT treats .agents/ as the source of truth, with provider settings in .oat/sync/config.json, when provider views are derived from those canonical assets, how native-read mappings avoid redundant output, and how provider-local adoption surfaces remain discoverable.

What OAT Treats As Canonical

canonical skills, agents, and rules under .agents/
provider settings in .oat/sync/config.json, and sync state that OAT writes to .oat/sync/manifest.json
provider-specific files as derived views when a mapping requires output
native-read assets in canonical directories without mirrored provider files
provider-local extension files as adoption candidates until explicitly adopted or remembered as intentional strays

Who It's For

Teams adopting OAT primarily for provider interoperability
Users who want one canonical asset layout instead of hand-maintaining provider copies
Repos that need drift detection, adoption flows, and explicit sync control

Typical Flow

Run oat init --scope project to create the base OAT layout and setup state.
Inspect current sync state with oat status --scope project.
Adjust provider enablement with oat providers ... if needed.
Run oat sync --scope project to materialize required provider views and reconcile managed state. Native-read assets do not produce provider-view operations.
Re-run oat status --scope project after edits to confirm whether anything drifted or needs adoption.

Start Here

Use CLI Bootstrap when you are bootstrapping OAT and want the sync-relevant setup path.
Go to Commands once you are actively using oat status, oat sync, and oat providers.
Read Scope and Surface when you need the canonical/provider-view mental model.

Common Tasks

Understand the canonical/provider-view model in Scope and Surface.
Manage nested AGENTS.md / CLAUDE.md integrity in Instruction Sync.
Learn provider-specific mappings in Providers.
Diagnose drift and adoption behavior in Manifest and Drift.
Adjust provider enablement and scope behavior in Sync Config.

Go Deeper

CLI Bootstrap - Foundational setup before first sync.
Scope and Surface - Canonical assets, provider views, scopes, and the sync surface area.
Commands - oat status, oat sync, and oat providers ... behavior.
Instruction Sync - Project-scoped AGENTS.md / CLAUDE.md validation, repair, and Claude-only adoption.
Providers - Provider-specific mappings, capabilities, and path conventions.
Manifest and Drift - How OAT tracks synced state, stray files, and adoption decisions.
Sync Config - Provider config model, enablement, and scope semantics.