opencode-compatibility-audit
Read-only compatibility audit between `opencode-setup` and the latest stable `opencode-ai` release plus official OpenCode docs. Use whenever the task is to decide whether this repository still matches
SKILL.md.claude/skills/opencode-compatibility-audit/SKILL.md
GitHubOpenCode Compatibility Audit
Purpose
Use this skill to answer one practical question:
is opencode-setup still compatible with the current stable upstream OpenCode
contract or not?
This is a read-only compatibility gate. The job is to compare official upstream OpenCode behavior against the assumptions encoded in this repository and return a clear verdict, not to design or apply a migration.
Scope
Cover the repository's current and planned OpenCode-facing contract, especially:
- config location, merge order, and precedence assumptions for
~/.config/opencode/opencode.json,OPENCODE_CONFIG, and projectopencode.json - project activation assumptions where user-level config owns
provider.gonkagateand project scope writes only activation settings - custom-provider wiring through
provider.<id>, including custom providernpm,name,options.baseURL,models,options.apiKey, andoptions.headers - model selection assumptions around
model,small_model,opencode models, andprovider/modelidentifiers - auth strategy assumptions around
/connect,opencode providers login,~/.local/share/opencode/auth.json, and the repository's decision not to useauth.jsonas its integration contract - variable-substitution assumptions such as
{env:...}and{file:...}for secret handling - transport expectations such as
@ai-sdk/openai-compatiblefor current/v1/chat/completionsand@ai-sdk/openaifor future/v1/responses - workflow and CLI assumptions documented by this repository, such as
opencode,opencode run,opencode models, andopencode providers login - newly required settings, renamed fields, removed commands, or release-level behavior changes that would make the documented GonkaGate OpenCode plan stale or unsafe
Default compatibility target:
- latest stable
opencode-airelease from the npmlatestdist-tag
Secondary watch target:
- newer prerelease channels such as
next,alpha, orbeta, but only as an early-warning watchlist unless the user explicitly asks for prerelease compatibility
Boundaries
Do not:
- modify repository code or docs
- broaden product scope beyond the current GonkaGate OpenCode contract
- propose
.envwriting, shell profile mutation, directauth.jsonmutation, or runtime/v1/modelsdiscovery as the default integration path unless the user explicitly asks for a product change - use secondary summaries when primary sources are available
- treat prerelease drift as a stable compatibility failure unless the user explicitly asked to audit prereleases
- turn the audit into an auto-remediation or full migration plan
Primary-Source Discipline
Use primary sources only:
- npm registry metadata for
opencode-ai - official OpenCode docs, especially:
https://opencode.ai/docs/config/https://opencode.ai/docs/providers/https://opencode.ai/docs/models/https://opencode.ai/docs/cli/https://opencode.ai/config.json
- official repository URL, homepage, releases, and tagged source discovered from npm metadata for the matching stable version
- shipped package behavior or CLI help for the same stable version
Prefer this discovery order:
npm view opencode-ai version dist-tags repository.url homepage --json- official docs and config schema
- official release notes or tagged source for the exact stable version
- tagged upstream source or tests when docs are incomplete
- isolated CLI help or read-only inspection when source and docs are still insufficient
Useful starting points:
npm view opencode-ai version dist-tags repository.url homepage --jsoncurl -fsSL https://opencode.ai/config.jsoncurl -fsSL https://opencode.ai/docs/config/curl -fsSL https://opencode.ai/docs/providers/npx -y opencode-ai@<version> --helpnpx -y opencode-ai@<version> models --helpnpx -y opencode-ai@<version> providers login --help
If official docs and the shipped stable artifact disagree, trust the shipped stable artifact, schema, or tagged source and call out documentation drift explicitly.
Safe Read-Only Execution
Keep the audit read-only.
- Prefer docs, schema, release notes, CLI help, source, and tests over running stateful commands.
- Never run upstream OpenCode commands against the user's real
~/.config/opencode,~/.local/share/opencode, or project config. - If you need CLI help or read-only behavior inspection, isolate it in a
disposable temp directory and point
HOME,XDG_CONFIG_HOME,XDG_DATA_HOME,OPENCODE_CONFIG, and any other relevant config roots at temp paths. - Do not run login flows or commands that mutate real state.
- Treat isolated local execution as a last resort after docs, schema, release notes, and tagged source.
Repository Surfaces To Compare
Start from the current repository contract surfaces:
README.mdAGENTS.mddocs/how-it-works.mddocs/security.mddocs/troubleshooting.mddocs/specs/opencode-setup-prd/spec.mdsrc/cli.tspackage.jsontest/package-contract.test.tstest/docs-contract.test.tstest/skills-contract.test.ts
Inspect local skills when they encode product assumptions that affect the audit, especially:
.claude/skills/coding-prompt-normalizer/.agents/skills/coding-prompt-normalizer/- this compatibility-audit skill itself, if its assumptions look stale
If the repository later adds implementation modules, inspect those too instead of stopping at docs. In particular, compare any future surfaces under:
src/install/src/constants/- config-writing modules
- provider or secret helpers
- model-registry generation
- runtime verification flows
Upstream Evidence To Gather
For the target stable release, gather evidence for:
- the exact stable version, release tag if available, and publish date
- whether npm
latestand the official homepage or repository links agree - whether newer prerelease channels exist and whether they signal upcoming contract drift
- where OpenCode loads global config from and how project
opencode.jsonoverrides are discovered and merged - the official shape of
provider.<id>, custom providernpm,name,options.baseURL,models,model, andsmall_model - whether custom-provider auth still relies on
/connectoropencode providers loginstorage plus config, and whetherauth.jsonremains an internal credential store detail rather than a stable integration contract - whether current custom-provider guidance still recommends
@ai-sdk/openai-compatiblefor/v1/chat/completionsand@ai-sdk/openaifor/v1/responses - whether OpenCode added or removed CLI surfaces relevant to this repository's documented flow
- whether release notes mention changes to config precedence, custom providers, provider auth, project config loading, model loading, or command surfaces
- any newly required settings, schema migrations, or structural requirements that this repository does not currently satisfy
When searching source or docs, start with these literals:
~/.config/opencode/opencode.jsonopencode.jsonOPENCODE_CONFIGproviderprovider.gonkagatesmall_model@ai-sdk/openai-compatible@ai-sdk/openaichat_completionsresponsesauth.json/connectopencode providers loginopencode modelsopencode run{file:custom provider
Workflow
- Identify the audit target.
- Determine the latest stable
opencode-airelease from npm metadata. - Confirm the matching repository URL and any stable release notes.
- Note any newer prerelease channels from dist-tags, but keep them separate from the stable compatibility verdict unless the user asked for them.
- Determine the latest stable
- Capture the upstream contract before judging compatibility.
- Read official config, providers, models, and CLI docs.
- Read the official config schema.
- Read tagged source or tests when docs are vague, incomplete, or missing exact field or behavior details.
- Use isolated CLI help only when docs and source still leave an important ambiguity.
- Map the repository's assumptions.
- Read
README.md,AGENTS.md, anddocs/first. - Then inspect
src/cli.ts,package.json, tests, and any implementation surfaces that exist. - Keep current scaffold truthfulness separate from the planned future product contract.
- Read
- Compare the critical seams one by one.
Config locations and precedenceCompare upstream global and project config behavior against the repo's~/.config/opencode/opencode.json,OPENCODE_CONFIG, andopencode.jsonassumptions.Provider wiringCompare upstream custom-provider expectations against the repo's plannedprovider.gonkagate,baseURL,npm,models,model, andsmall_modelusage.Auth and secret handlingCompare upstream auth surfaces against the repo's planned use of user-managed secret files,{file:...}substitution, and refusal to useauth.jsonas a write target.Model and transport contractCompare upstream model-loading and custom-provider transport guidance against the repo's curated-model andchat_completionstoday /responseslater plan.Workflow and command surfacesCompare upstream CLI surfaces and documented workflows against what this repo promises users today.Recent release driftCompare the latest stable release notes, and optionally newer prerelease signals, against the repo's setup plan.
- Classify the evidence.
- Label each material point as:
confirmed upstream change,confirmed still compatible,confirmed repo-overstatement, orinferred risk. - Keep observed upstream facts separate from your interpretation of impact.
- Label each material point as:
- Decide the verdict.
compatibleNo confirmed upstream stable change breaks the repository's current or planned OpenCode contract.compatible with caveatsNo confirmed stable break yet, but there is meaningful ambiguity, documentation drift, prerelease warning, or repository overstatement that weakens confidence.incompatibleA confirmed upstream stable change conflicts with a required repository assumption or makes the documented GonkaGate OpenCode plan stale or unsafe.
- Name the minimum follow-up.
- Point to the exact repo surfaces that would need attention.
- Keep this as
recommended fix areas, not a redesign.
Reasoning Discipline
- Separate confirmed upstream changes from inferred risk.
- Base the main verdict on the latest stable release, not on prereleases.
- Use prerelease channels only as an explicit watchlist unless the user asked for prerelease compatibility.
- If the repo docs are still compatible with upstream but the placeholder implementation is misleading, call that a repository truthfulness issue, not an upstream break.
- If the upstream docs are vague but the schema, release tag, or shipped stable behavior is clear, cite the shipped behavior and call out doc drift.
- Treat config precedence, custom providers, secret handling, and
small_modelbehavior as high-sensitivity by default. - Do not infer support for out-of-scope product changes that this repository explicitly rejects.
Output
Load references/report-template.md before writing the final answer.
The report should:
- cite the exact stable version audited and its publish date
- link the primary sources used
- separate confirmed upstream changes from inferred risk
- separate stable-verdict impact from prerelease watchlist signals
- point to the exact repository surfaces that would break or need clarification
- include a short
recommended fix areassection only when the verdict iscompatible with caveatsorincompatible
Keep the output short, decisive, and evidence-backed.