Interoperability Patterns¶

When to Use This Guide¶

Read this guide if you:

Have an existing agent team in one framework and need it to work in another
Are unsure whether to use --convert-from, --interop-from, or --bridge-from
Need compatibility artifacts for tooling that consumes agent manifests
Want lightweight target-framework entrypoints that keep your source team as the single source of truth

For the concise reference on all three modes, see Interoperability. This guide adds decision guidance and worked patterns.

Choosing a Mode¶

Does target runtime need fully standalone agent files?
  ├── Yes → Are you moving permanently to the new framework?
  │            ├── Yes → --convert-from  (format migration)
  │            └── No  → --interop-from  (dual-framework with CAI normalization)
  └── No  → --bridge-from  (lightweight reference artifacts; source stays canonical)

Mode	Source docs stay canonical?	Target files are standalone?	CAI bundle artifacts?
`--convert-from`	No — target becomes the new canonical	Yes	No
`--interop-from`	Depends on usage	Yes	Optional (`--interop-mode bundle`)
`--bridge-from`	Yes	No — reference source	No

Pattern 1: One-Shot Framework Migration¶

Goal: You are moving permanently from copilot-vscode to claude. Source files are no longer maintained after the migration.

agentteams \
  --convert-from /path/to/project/.github/agents \
  --framework claude \
  --output /path/to/project/.claude/agents

What happens: 1. Every agent's body prose is preserved. 2. Front matter is rewritten for the Claude format. 3. Target-framework instructions are written (for Claude targets, CLAUDE.md). 4. Live security freshness preflight runs before writing. Stale intelligence blocks the write unless a valid signed waiver exists in references/security-waivers.log.csv.

After migration, validate converted output and preserve rollback history before deciding whether to archive or keep the source directory as canonical.

Pattern 2: Dual-Framework Team (CAI Interop)¶

Goal: You maintain a copilot-vscode team as canonical source but need a copilot-cli version that stays in sync with re-generation.

# Full bundle (interop artifacts + target files):
agentteams \
  --interop-from /path/to/project/.github/agents \
  --interop-source-framework copilot-vscode \
  --framework copilot-cli \
  --interop-mode bundle \
  --output /path/to/project/.github/copilot

Bundle artifacts appear in references/interop/copilot-vscode-to-copilot-cli/:

File	Contents
`team-manifest.cai.json`	Canonical Agent Interface manifest
`interop-manifest.json`	Source-to-target field mapping
`routing-map.json`	Agent slug routing equivalences
`instructions-map.json`	Instructions file mapping
`compatibility-report.md`	Human-readable translation summary

Refresh the target team whenever the source is updated:

agentteams \
  --interop-from /path/to/project/.github/agents \
  --framework copilot-cli \
  --interop-mode direct \
  --output /path/to/project/.github/copilot \
  --overwrite

Pattern 3: Bridge (Source Stays Canonical)¶

Goal: You want Claude users to access your copilot-vscode team without regenerating or duplicating source documentation.

agentteams \
  --bridge-from /path/to/project/.github/agents \
  --bridge-source-framework copilot-vscode \
  --framework claude \
  --output /path/to/project

Bridge artifacts appear in references/bridges/copilot-vscode-to-claude/:

File	Purpose
`bridge-manifest.json`	Source-to-target agent resolution map
`agent-inventory.md`	Human-readable list of agents accessible through the bridge
`quickstart-snippet.md`	Framework-neutral first-prompt snippet for the bridged target runtime
`entrypoint.md`	Canonical entry point for Claude routing through bridge
`domain-boundary.md`	Clarifies the memory-index vector-mode boundary vs project-level retrieval-integrator contracts

Source agent documentation is never modified. The bridge references it by path.

Bridging From a Canonical Source¶

If your source of truth is already a durable canonical directory (see Interoperability: The Durable Canonical Format), point --bridge-from at its root — the directory holding team.cai.json, not the agents/ subdirectory underneath it:

agentteams \
  --bridge-from /path/to/project/.agentteams/canonical \
  --bridge-source-framework canonical \
  --framework claude \
  --output /path/to/project

--bridge-check against a canonical source covers both agents/*.md and team.cai.json itself, so a hand-edit to instructions/MCP/framework-extension data (which lives inside team.cai.json, not as a sibling file) is caught, not just agent-file changes.

Bridging to a Consumer With No Adapter¶

--framework generic is a bridge-only target for a consumer with no agentteams framework adapter of its own — it writes only the framework-agnostic pair-dir artifacts (manifest, inventory, quickstart, entrypoint, domain-boundary), zero native entry files:

agentteams \
  --bridge-from /path/to/project/.github/agents \
  --framework generic \
  --output /path/to/project

The generated quickstart points the consumer at the durable canonical tree as the fuller source of truth, and at the command to generate one if it doesn't already exist.

Checking Bridge Freshness¶

agentteams \
  --bridge-from /path/to/project/.github/agents \
  --framework claude \
  --output /path/to/project \
  --bridge-check

--bridge-check is read-only: it compares current source-file hashes to the hashes recorded in bridge-manifest.json and reports stale, missing, or new source files. Use it in CI to detect when bridge artifacts need refresh.

Refreshing a Bridge¶

agentteams \
  --bridge-from /path/to/project/.github/agents \
  --framework claude \
  --output /path/to/project \
  --bridge-refresh

--bridge-refresh rewrites bridge artifacts to reflect the current source manifest. It cannot be combined with --bridge-check.

Pattern 4: Portable Team Package¶

Goal: You want to hand a team to someone outside your project — a different machine, a different organization — as one file, without them needing your project checked out.

agentteams \
  --package-team /path/to/project/.github/agents \
  --package-source-framework copilot-vscode \
  --output /path/to/project/dist/my-team.zip

What happens: 1. The source team is exported to the durable canonical format (Mode B) and bridged to a generic target (Mode C) in a temporary staging area. 2. Both trees are zipped together at the requested output path. 3. The recipient unzips it, gets .agentteams/canonical/ plus a generic bridge pair-dir, and can import the canonical tree into their own framework of choice with --interop-from.

This is not a fourth interoperability mode — it composes Mode B's canonical export with Mode C's generic-target bridge into one distributable artifact. It cannot be combined with any other standalone CLI operation (fleet, goose-switch, recipe-check, stale-check, etc.). See CLI Reference: Portable Team Package for the full flag list.

Security Preflight Behaviour¶

All write-path interoperability operations (convert, interop direct, interop bundle, bridge-refresh) run the same live security freshness preflight as main generation. If threat intelligence is stale and no valid signed waiver exists, the write is blocked.

--bridge-check is read-only and does not trigger the security preflight.

Supported Conversion Directions¶

The CAI interop pipeline (--interop-from) supports every registered framework as both source and target, plus the durable canonical pseudo-framework (durable-canonical-agent-format plan, Phases F/G). Convert and bridge cover the original three-framework core plus goose as target:

Source → Target	`--convert-from`	`--interop-from`	`--bridge-from`
`copilot-vscode` → `copilot-cli`	✓	✓	✓
`copilot-vscode` → `claude`	✓	✓	✓
`copilot-cli` → `copilot-vscode`	✓	✓	✓
`copilot-cli` → `claude`	✓	✓	✓
`claude` → `copilot-vscode`	✓	✓	✓
`claude` → `copilot-cli`	✓	✓	✓
any of the three → `goose`	✓	✓	✓
any registered framework → `canonical`	✗	✓	✗
`canonical` → any registered framework	✗	✓	✗
`goose` / `agents-md` / `codex` sources → any target	✗	✓ ^*	✗

^* goose sources parse recipe YAML (title/description/instructions, extension scoping, sub_recipes/load(...) handoffs, recipe parameters/response/retry). agents-md sources carry no front matter, so capabilities/handoffs land inferred-or-empty — best-effort by nature, surfaced via compatibility-report.md in bundle mode. codex sources (.codex/agents/*.toml) round-trip tools and handoffs through each agent's codex_translation block.

canonical is interop-only: export with --interop-from <src> --framework canonical, import with --interop-from <canonical dir> --interop-source-framework canonical. The canonical round trip is lossless (byte-identical re-render for every framework — pinned by tests/test_dogfood_canonical.py), and its carried MCP servers re-validate against mcp-server.schema.json (security-review hard gates included) at import time.

Troubleshooting¶

Security preflight blocked the conversion¶

See the Security Hardening Guide for waiver creation and offline mode options.

Bridge check reports stale but source hasn't changed¶

Bridge check compares source file hashes and path inventory against bridge-manifest.json. Stale means one of the following: source file content hash changed, a source file is missing, or a new source file exists. Run --bridge-refresh to synchronize.

`--interop-mode bundle` created a compatibility-report.md with warnings¶

The compatibility report documents any agent sections or attributes that could not be fully translated between frameworks. Review the warnings and manually adjust the target files if fidelity is required. Warnings do not block the write.