Publish an agent compatibility matrix backed by adapter contract tests

[richardmhope]

What & why

Adds docs/compatibility.md, a public compatibility matrix linked from the README and docs/adapters.md. It covers all eight adapters: the five native ones plus the copilot-prompt, cursor-rule and kiro-steering legacy adapters. For each adapter it gives:

• a status: tested, supported or experimental, each defined on the page. When the only evidence is a related vendor package, the status is experimental, so both Cursor adapters are experimental;
• project and global paths, and the environment variables that move them;
• how the skill is invoked in that agent;
• the minimum agent version;
• the date, agent version and vendor sources it was checked against (2026-09-23).

Anything a primary source doesn't confirm is marked unverified. The page also explains how the project responds when a vendor deprecates or moves a location or format, including urgent releases.

CI now pins each adapter's contract. tests/fixtures/adapter-contracts/ holds a synthetic skill, a contracts.json, and the exact rendered file every adapter should produce, stamp included. contracts.json records paths, scope-error text (for install and for other commands), the expected frontmatter, and the behaviour with each config-directory variable set to an absolute path, empty, or relative. tests/test_adapter_contracts.py:

• installs with every adapter into temp dirs and compares byte for byte. This is Windows-safe: UTF-8 reads, POSIX-relative paths, fixtures marked -text, no symlinks;
• requires the fixture directory to hold exactly the contract's files;
• checks each matrix row's paths, "not supported", "Moved by" and scope-error text against the contracts. Status, minimum versions, dates and notes are maintained by hand, and the page says so;
• requires the matrix's <!-- adapter-contract: sha256:… --> line to match a digest of the contract files. contracts.json is hashed as canonical JSON without its _about notes;
• requires CHANGELOG.md to mention the digest prefix, either under [Unreleased] or, once a release is cut, in the newest dated section. This is tested against prepare_release.cut_changelog.

Unsupported scopes now fail with an actionable message. install --agent cursor-rule --scope global says "Use --scope project, or --agent cursor (Agent Skills), which supports --scope global". status, uninstall and update name only --scope project, because the native adapter would act on different files.

Review. An independent review raised eight findings, all fixed here:

• the scope hint now depends on the command;
• the fixture file set is checked exactly;
• the matrix is checked cell by cell;
• the CHANGELOG rule survives a release cut;
• the Cursor adapters are marked experimental;
• the cursor-rule invocation caveat is added;
• the claim about Codex $name resolution is hedged as unverified;
• _about is excluded from the digest.

Closes #79

Tracking: #94

Type of change

• Bug fix
• New feature
• New or updated skill
• Docs only
• Refactor / internal

Checklist

• Ran uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev mypy && uv run --extra dev pytest (817 passed, also with -W error::EncodingWarning and with --resolution lowest-direct)
• Added or updated tests
• Updated docs where relevant (README, docs/adapters.md, new docs/compatibility.md, CLAUDE.md)
• Added a CHANGELOG.md entry under ## [Unreleased]
• For a skill change: bumped that skill's version in meta.yaml (no skill content changed)

🤖 Generated with Claude Code

https://claude.ai/code/session_01HtiCGzpikMrkDYBkfQG5CX

---

Generated by Claude Code