The contract
ecosystem.yaml — one file every part reads
Nine components, four repositories and one website agree about a vault. They agree because they all read the same file, not because anyone remembered to keep them in step.
ecosystem.yaml declares the parts and what each reads and writes, every path
in the vault with its writers and readers, the enumerations several tools must agree on,
and 19 rules that each carry a declared strength. This site renders it. So does the
README, and so does the framework's own help command.
Why a file and not documentation
Because documentation is a copy. The version number on this page once sat in a Python constant and fell two releases behind without anyone noticing, which is not a story about carelessness — it is what a second copy does.
The rule the contract applies to itself: declared once, rendered by many, restated by none. Where you see a fact on this site, it came from the file.
Three version numbers, and why they must not match
The most common misreading is that they should be equal. They measure different things.
| Number | Today | What it is |
|---|---|---|
core_skills_version | 1.89.4 | the contract and the framework — one number, one repository |
contract_version | 41 | how many times the SHAPE changed. Additive changes bump it; a skill fix does not |
| this site's build | 2.0.0-alpha | independent. It says what is deployed here, not what the framework is at |
A consumer that pins a framework version is claiming something it cannot know. A consumer that reads the contract cannot be wrong about it. That is the difference this page exists to make.
Read on
- The 19 conventions — and what a level actually commits you to
- The vault — 36 declared paths, with writers and readers
- The checks — including what they cannot see
From ecosystem.yaml, contract 41 · core-skills 1.89.4 · read at build 2026-10-08