Add OpenCode v2 compatibility and migration guidance #46

Area

Runtime compatibility / agents / installation / CI

Problem

The project currently targets OpenCode 1.x. The README explicitly defers OpenCode 2 support, and the installer targets major version 1.

Please support current OpenCode v2 installations so contributors and users do not have to stay on the older major version to use the team.

A native Windows contribution is already proposed in #44 for #42. V2 support should be a separate compatibility effort rather than expanding that PR.

Proposal

Audit the team against an explicitly selected OpenCode 2.x release and implement/document the required adaptations:

• Agent, command, and skill discovery and frontmatter.
• Global/project configuration, instruction paths, and permissions.
• Orchestrator delegation, task completion, model inheritance/overrides, and approval gates.
• Project memory initialization, reading, logging, and compaction.
• Installation/version checks and the official v2 distribution method.

Decide and document whether v1 and v2 are supported together or whether v2 support is a new major release. Avoid silently installing or downgrading a different OpenCode major.

Acceptance criteria

• State the supported OpenCode versions and compatibility policy.
• Verify team agents, slash commands, and local skills are discovered on a documented 2.x release.
• Verify orchestration can dispatch a specialist, receive its result, and respect a human approval gate.
• Verify memory persists and is read on a subsequent session; compaction still works.
• Validate permissions and model selection behavior against v2 instead of assuming v1 behavior.
• Provide macOS, Linux, and native Windows installation/check/uninstall instructions.
• Add appropriate v2 CI/smoke coverage and record any provider-backed scenarios that were not executed.
• Include upgrade/migration guidance for existing v1 users and explain any shared data/configuration incompatibilities.
• Preserve user configuration and session data; do not reset databases as an implicit upgrade step.
• Update README(s), support notes, examples, and release notes.

Alternatives considered

Continue v1-only support, or maintain separate compatibility adapters/releases. The maintainer should choose the smallest sustainable compatibility policy.

Compatibility

This issue does not assume v1/v2 database compatibility or require automatic session migration. Any breaking changes should be explicit and released accordingly.