docs: add an agent entry point and document the spec as the source of truth

[nielspardon]

Three gaps in the contributor docs, and no entry point for agents at all.

• The spec is upstream. Nothing stated that this repository implements the Substrait specification rather than defining it, or what to do when the spec is ambiguous. CONTRIBUTING.md now leads with that and gives an escalation order — the sibling bindings under Active Libraries for modeling questions, the engines under Powered by Substrait for runtime semantics, a clarification issue upstream only when neither shows a consensus. AGENTS.md, imported by CLAUDE.md, carries the agent-specific half: filling a spec gap with something plausible and then describing it as spec-defined is a failure mode worth naming outright.
• The PR description is changelog input. Nothing said that the title and description are linted together and become the squash-merge commit body that semantic-release turns into release notes. The ⚠ BREAKING CHANGES section of v0.30.0 shows the cost: one entry is just a repeated commit subject, because that commit marked its title with ! but put the prose under a ## Breaking change heading instead of a BREAKING CHANGE: footer, so its migration instruction never reached the notes. The new .github/pull_request_template.md states only what a PR author needs while typing, and links the rest.
• The documented setup step was broken. uv sync --extra test fails, because no test extra exists. The testing section now also says why a clean run reports skips — the tests/sql engine round-trips are opt-in behind SUBSTRAIT_ENGINE_TESTS=1 — and which examples CI does not cover.
• The README gains the contributing and community pointers it lacked, a note on what sets the spec version a release targets, and three fixes that make its >>> sessions runnable: p.SerializeToString() before p exists, mesage= for message=, and a dangling functions: line.

🤖 Generated with AI