Vendor Independence for AI Coding Tools

1. Why vendor independence matters

AI coding tools change fast. Product names change, plugin systems change, marketplaces change, hook models change, and sometimes entire clients disappear. If your useful behavior lives only inside one vendor's plugin manifest or one client's hook syntax, you do not really own your workflow.

The goal is not to make every tool identical. The goal is to make the important parts portable enough that switching from Claude to Codex, or from Codex to the next thing, does not mean rewriting your whole operating model.

Working rule: move the durable logic into your own files, and keep the vendor-specific layer as thin as possible.

2. What should be portable

Not everything needs to be vendor-neutral. The right split is:

Layer	Should be portable?	Why
Operating principles and rules	Yes	These are the behaviors you want regardless of which client is active.
Workflow instructions and reusable recipes	Yes	These are the highest-value parts to preserve when tools churn.
Tool access protocol	Mostly	Prefer open layers like MCP where possible.
Plugin manifests and marketplace metadata	No	These are packaging adapters. Keep them thin and disposable.
Launch policy, secret release, sandboxing	Yes	Security should not depend on a specific AI vendor.

AGENTS.md / rules → shared skills & prompts → thin vendor plugin wrappers → MCP / tools → bondage / envchain-xtra / nono → exact client

3. Passive instructions first

The most durable layer is plain markdown instruction files that the client can load every turn. This is why CLAUDE.md / AGENTS.md-style files matter so much.

The research in the internal wiki strongly favors passive context for broad framework knowledge. The important distinction is:

Passive context for stable rules, conventions, API surface notes, and project operating principles.
Active skills for vertical workflows such as migrations, diagnosis, refactoring recipes, or specialized commands.

If you put general guidance only inside a vendor-specific skill system, the model has to remember to invoke it. If you put it in `AGENTS.md`-style files, it is available every turn.

# AGENTS.md
- Prefer the local screenshot helper for localhost UI checks.
- Use the launcher wrapper, not the raw agent binary.
- Keep reviews focused on bugs, regressions, and missing tests.
- For new repositories where the initial branch is your choice, use master.

That file shape is portable in a way a proprietary hook system is not.

4. Shared workflow sources

The next layer is your reusable workflow logic: skill content, prompt recipes, helper scripts, small reference docs, and task-specific instructions. Keep that as a shared source tree, not as separate behavior trees per client.

The strongest pattern from the local stack is this:

write the real workflow once
keep the shared skill or markdown content as the source of truth
generate or adapt vendor wrappers from that source

That is how the same capability can survive across multiple clients without becoming four divergent implementations.

skills/
  wiki/
    SKILL.md
    references/
scripts/
  sync-codex-wrapper.sh
  sync-claude-wrapper.sh

If you find yourself manually maintaining separate logic trees for Claude, Codex, OpenCode, and Pi, you are rebuilding lock-in by hand.

5. Plugins as thin adapters

Plugins are still useful. They are just not where your core workflow should live.

Claude and Codex both support plugin-like packaging, but the packaging surface is different:

Claude uses `.claude-plugin/plugin.json` plus plugin-root content such as skills, hooks, commands, agents, and optional MCP config.
Codex uses `.codex-plugin/plugin.json`, bundled `skills/`, optional apps and MCP, and marketplace catalogs for distribution.

For a concrete migration pattern, see claude-to-codex-plugins, which uses llm-wiki as the case study for making Codex first-class without duplicating the workflow.

The portable insight is not “pick one and hope.” The portable insight is:

Make the manifest disposable. The plugin manifest should describe the shared workflow, not contain the only copy of it.

plugin-root/
  skills/
    my-workflow/
      SKILL.md
  .claude-plugin/
    plugin.json
  .codex-plugin/
    plugin.json
  .mcp.json

Codex-specific details like marketplaces and enable flags are real, but they should be treated as distribution metadata. Claude-specific hook wiring is real, but it should be treated as adaptation glue. The durable part is the shared skill content and helper logic underneath.

If a plugin needs both Claude and Codex packaging, generate or synchronize the wrappers from one shared source rather than hand-editing them separately.

6. MCP and tool portability

When you need external tool access, prefer an open protocol layer like MCP instead of burying tool logic inside one vendor's proprietary extension format.

That does not make everything magically portable, but it does give you a better seam:

the tool contract can stay stable even if the client changes
plugins can bundle MCP servers without owning the whole workflow
you can reuse the same MCP server across multiple clients

Use plugins when you need packaging and distribution. Use MCP when you need a cross-client tool layer.

7. Keep security below the vendor layer

This is where most portability stories fail. People keep their prompts portable, but leave secrets, launch policy, and sandboxing embedded in one client.

The cleaner pattern is the one described in agent-stack:

shell name → bondage → [envchain-xtra] → [nono] → exact pinned client

That means:

launcher verification is not a Claude feature or a Codex feature
secret release is not a vendor plugin feature
sandbox profiles are not tied to one client's own self-description

It also means your tiers can be named by capability, not by vendor accident:

base
plugin
unsafe but still sandboxed
explicit true bypass

That is much easier to port across tools than a forest of one-off exceptions.

8. Portability checklist

Put broad operating rules in `AGENTS.md` / `CLAUDE.md`-style passive files.
Keep shared workflow logic in reusable markdown or skill sources.
Generate or synchronize vendor-specific plugin wrappers from that shared source.
Use MCP for cross-client tool access where possible.
Treat plugin manifests and marketplaces as thin distribution layers.
Keep secrets, launch policy, and sandboxing outside the vendor client.
Name capability tiers by behavior, not by one client's quirks.
Assume the vendor UI and packaging model will change.

If you want the security side of this pattern, start with agent-stack and sandbox-profiles. If you want the instruction side, read claude-md. If you want the tool side, read mcp-servers.

9. Research prompts for your agent

The easiest way to use this pattern is to make your agent audit the current stack for you. The goal is not “rewrite everything now.” The goal is to identify what is shared, what is vendor-specific, and what should move below the client layer.

Inventory the current lock-in

Audit this repository for AI-tool vendor lock-in.

Find:
- instructions that live only in one client's format
- plugin logic duplicated across vendors
- hooks that should really be passive docs or shared scripts
- security or credential logic embedded in one client instead of a launcher/sandbox layer

Return:
1. a portability inventory
2. the highest-risk lock-in points
3. the smallest first migration steps

Extract a shared source of truth

Review our Claude/Codex/OpenCode/Pi workflow files and propose a shared source tree.

Goal:
- one source of truth for reusable skill/workflow content
- thin vendor-specific wrappers generated or synced from that source

Return:
1. proposed directory layout
2. which files become shared
3. which files remain vendor-specific adapters
4. migration order with low-risk first

Move general rules into passive context

Identify guidance that should live in AGENTS.md / CLAUDE.md-style passive files instead of only in skills, hooks, or plugin metadata.

Focus on:
- coding standards
- review behavior
- safety rules
- workflow defaults
- repo conventions

Return a draft passive instruction file plus a list of things that should remain active skills.

Design thin plugin adapters

Given our shared workflow sources, design the thinnest possible plugin wrappers for Claude and Codex.

Assume:
- the shared skill/prompt content stays outside the manifest
- plugin manifests are packaging adapters only
- MCP can be bundled if needed

Return:
1. Claude-side wrapper shape
2. Codex-side wrapper shape
3. what can be generated automatically
4. what must stay hand-maintained

Separate security from the client

Audit our agent setup and move any vendor-specific security logic out of the client layer.

Look for:
- secret loading in client-specific config
- sandbox assumptions tied to one tool
- shell wrappers acting as the trust boundary

Return:
1. what should move into launcher policy
2. what should move into secret release
3. what should move into sandbox policy
4. what should remain client-specific

Produce a migration plan, not a rewrite fantasy

Create a practical migration plan to make our AI tool stack more vendor-independent.

Constraints:
- minimize churn
- preserve current working behavior
- prioritize the highest-value shared layers first
- avoid rewriting every plugin at once

Return:
1. phase 1 quick wins
2. phase 2 structural cleanup
3. phase 3 optional improvements
4. clear "do not migrate" items where vendor-specific code is acceptable

Tip: ask the agent to write findings into a report file, not directly refactor the whole stack on the first pass. Portability work goes better when the first deliverable is an inventory and migration plan, not a speculative rewrite.