TL;DR
Keep the workflow contract in the repository and separate it from each tool adapter. Define shared stages, required artifacts, checks, stop conditions and decision owners once. Then document what each coding host can enforce, record or only suggest. Portability means the team keeps the same delivery expectations while honestly exposing differences in hooks, permissions and automation. Retest every adapter after a meaningful host change.
In this article
6 min read
These two reader concerns frame the article: How do you keep an AI coding workflow portable across Claude Code, Codex and Gemini? and Can the same agent instructions work across different coding tools?. The links show the wording and context of the questions; the answer below uses primary or official sources for material claims.
Weak signal and stronger evidence
| Weak signal | Stronger evidence |
|---|---|
| The agent or tool says the work is complete | The named result is checked against the exact revision |
| A policy exists in a document | The rule is visible in the working delivery path |
| More output is produced | Accepted outcomes improve without hidden review debt |
Shared files do not create shared enforcement
Claude Code, Codex, Gemini, Cursor, and other hosts expose different hooks, tools, instruction layers, and session behavior. A common specification can travel across them, while a stop gate or file restriction may not. Document the distinction before rollout.
NIST AI RMF Core supports the boundary. Voluntary guidance, not endorsement or certification.
| Evidence point | Inspectable value |
|---|---|
| 1 | Five capability states |
| 2 | Four provider examples |
| 3 | One repository authority order |
| 4 | One test date per capability |
Use this as a diagnostic. Replace illustrative entries with current repository evidence before making a policy, staffing, or release decision.
Build one contract and several adapters
Keep the portable contract in ordinary repository artifacts: approved task, stages, required outputs, checks, decision owners and stopping rules. Put provider-specific instruction files, hook configuration, permission syntax and session commands in adapters. An adapter may strengthen the contract, but it must not quietly remove a required gate.
Test portability with a small change such as adding one configuration field and its validation. Run the same approved package through each host and compare the resulting evidence, not the wording of its conversation.
Capability states to record
| State | Meaning | Release treatment |
|---|---|---|
| Enforced | Host or external control blocks violation | Can satisfy the gate with current test evidence |
| Verified after action | Repository check detects violation before acceptance | Can satisfy the gate if the check cannot be skipped |
| Suggested | Instruction asks for behavior but cannot guarantee it | Requires review or stronger external control |
| Unsupported | Capability cannot be reproduced | Route elsewhere or block the workflow |
| Unknown | Current version has not been tested | Treat as unavailable until tested |
For each host, try a successful path and a deliberate violation: edit outside scope, skip a required check, request an unapproved tool or resume after interruption. Record host version, adapter version, repository revision and result. A shared AGENTS.md or similar file proves that text is available; only the test shows whether the current host follows or enforces it.
Define capabilities as observable tests
For each provider and version, test whether it can enforce edit scope, run deterministic checks, pause on decisions, preserve state, resume, record evidence, and export a receipt. Mark each capability full, record-only, advisory, unsupported, or unknown with a test date.
- List required controls. Record the owner, artifact, and completion evidence before the next transition.
- Run provider-specific tests. Record the owner, artifact, and completion evidence before the next transition.
- Publish enforcement levels. Record the owner, artifact, and completion evidence before the next transition.
- Retest on version change. Record the owner, artifact, and completion evidence before the next transition.
Sequence matters because later evidence inherits the intent and scope established earlier. A skipped step transfers uncertainty to the final reviewer.
Repository state should outrank provider confidence
When providers disagree, the repository-owned specification, executed evidence, and named human decision should define authority. A model’s confidence does not supersede a versioned criterion or a failed deterministic check. NIST guidance supports explicit roles and traceability without prescribing one host.
Google DORA 2025 provides a second evidence boundary. Observational associations, not universal causation.
Mistake: Calling a workflow provider agnostic because every host can read the same Markdown. Fix: Test enforcement pause resume evidence and export, then publish gaps as first-class compatibility data.
The fix is procedural so the team can rehearse and audit it. A warning without ownership disappears when delivery pressure returns.
Retest compatibility after every meaningful change
Retest when a provider, plugin, policy, or paqad-ai release changes. Keep compatibility records versioned. A green result from six months ago should not silently certify current behavior after a hook API or permission model changes.
Use the AI workflow audit guide for current-state mapping, compare the bar with production-ready AI code, and read the AI coding consultant guide when outside ownership is relevant.
- Provider version recorded
- Capabilities tested
- Enforcement tier explicit
- Known gaps visible
- Repository authority documented
Decision rule: Claim portability only for capabilities reproduced in the current provider test suite, with every weaker enforcement tier visible.
Run the provider capability matrix in a 45-minute working review with the product owner, module owner, and final reviewer. Do not turn it into a score. Read the decision rule aloud: Claim portability only for capabilities reproduced in the current provider test suite, with every weaker enforcement tier visible. Record disagreements, missing evidence, and the person responsible for the next action. Repeat the review after one real feature so the team can compare whether the artifact reduced ambiguity or only added paperwork.
Decide what portability is worth
Full parity may be unnecessary. A team may accept one host for read-only planning and another for repository changes, provided the routes and evidence are explicit. Define the minimum portable core and list optional capabilities separately. This prevents a lowest-common-denominator contract from discarding useful safeguards that only some hosts can enforce.
Version the contract and adapters independently. A contract change requires every active adapter to be retested against the affected behavior. A host update requires that adapter’s suite even when repository rules did not move. Store the result date and known gaps next to the compatibility claim.
Migration should be rehearsed before a provider becomes unavailable. Start an interrupted task in one host, preserve the approved artifacts and exact revision, then resume through another adapter. The second host should not need the first conversation to understand the goal, completed work, evidence or next decision. If it does, the workflow state is still provider-bound.
Keep provider-specific secrets, account identifiers and local paths out of the portable contract. Adapters can resolve them at runtime under local policy. This lets the same workflow identity travel without copying credentials or pretending that every host uses the same security model.
Record the person who accepted each gap.
Decision rule
Proceed only when the team can name the owner, inspect current evidence and stop or reverse the work without reconstructing an agent conversation.
Paqad is a first-party Eliyce product. Teams that want to test these controls on their own repository can explore the AI Delivery Programme.
Frequently Asked Questions
How do you keep an AI coding workflow portable across Claude Code, Codex and Gemini?
Store the delivery contract in the repository and isolate each host integration in an adapter. Test the same required artifacts, checks, stops and decisions on every host, and publish the weaker capability state instead of assuming feature parity.
Can the same agent instructions work across different coding tools?
Shared instructions can express intent, repository rules and required outputs. Tool syntax, precedence, hooks, permissions and persistence differ, so each host still needs an adapter and a compatibility test.
Which workflow rules should stay outside the coding tool?
Keep irreversible or high-consequence controls in systems the agent cannot rewrite or bypass: repository protection, CI requirements, credential boundaries, deployment approval and durable evidence storage.
What should a provider compatibility test include?
Run one accepted task, one prohibited action, one failed check and one interrupted handoff. Record the host and adapter versions, artifacts produced, controls enforced and any step that depended only on instruction following.
When is a provider adapter too weak to use?
Block it when a required capability is unsupported or unknown and no external control supplies the same protection. A polished prompt does not compensate for missing isolation, verification or human authority.
How do you switch providers without losing the delivery record?
Keep task, artifact and decision identities in provider-neutral storage. Let adapters translate commands and events into that schema. Preserve the original provider metadata for audit instead of flattening away where evidence came from.
