Provider Interop Commands

Shared conventions

These command definitions inherit the cross-cutting CLI conventions in:

• ../contributing/design-principles

Adjacent command docs (outside provider interop scope)

• oat init (bootstrap): ../cli-utilities/bootstrap.md
• oat tools ... (tool-pack lifecycle — install, update, remove, list, info): ../cli-utilities/tool-packs.md
• oat doctor (cross-cutting diagnostics): ../reference/cli-reference.md

Quick Look

• What it does: defines the day-to-day provider-sync command surface for inspecting state, reconciling provider views, and changing provider enablement.
• When to use it: after you have canonical assets in place and need to check sync state, write provider views, or change provider config.
• Primary commands: oat status, oat sync, oat providers list, oat providers inspect, oat providers set

oat status

Purpose:

• Report in_sync, drifted, missing, and stray states

Key behavior:

• Scope support (project, user, all)
• Optional interactive stray adoption
• JSON output for automation

oat sync

Purpose:

• Reconcile provider views from canonical sources

Key behavior:

• Mutates by default; use --dry-run to preview
• Strategy-aware operations (symlink, copy, auto)
• Provider enable/disable honored via sync config

oat providers list

Purpose:

• Summarize adapters, detection, and mapping-level health summary

oat providers inspect <provider>

Purpose:

• Show adapter mappings and per-scope mapping state details

oat providers set

Purpose:

• Enable or disable project providers in sync config

Key behavior:

• Modifies .oat/sync/config.json to toggle provider enablement
• Options: --enabled <providers>, --disabled <providers> (comma-separated)
• Changes take effect on next oat sync

Notes

• oat init --scope project is commonly used before provider-interop commands because it initializes .oat/sync/config.json.
• oat doctor complements interop workflows by surfacing environment and bundled-skill version issues before or after sync operations.

Adjacent Instruction Integrity Commands

These commands are documented here because they are commonly used during interop-only repo maintenance, but they are not provider sync/drift commands.

oat instructions validate

Purpose:

• Validate project-scoped AGENTS.md to CLAUDE.md integrity

Key behavior:

• Read-only validation of nested project-scoped instruction directories
• Supports --strategy pointer|symlink|copy to validate the expected file shape
• Reports ok, missing, content_mismatch, and stray states
• Detects Claude-only adoptable directories and unreadable/broken instruction paths as drift
• Exit code 0 when all entries are valid, 1 when drift is detected
• Detailed behavior: Instruction Sync

oat instructions sync

Purpose:

• Repair project-scoped AGENTS.md to CLAUDE.md drift

Key behavior:

• Mutates by default; use --dry-run to preview changes
• Supports --strategy pointer|symlink|copy
• Creates missing CLAUDE.md files using the selected strategy
• Adopts Claude-only stray files by writing canonical AGENTS.md content first, then regenerating CLAUDE.md
• Skips mismatched files unless --force is provided
• Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
• Uses pointer content @AGENTS.md\n, file symlinks, or hard copies depending on the selected strategy
• Detailed behavior and examples: Instruction Sync