docs: refactor AGENTS.md into an entry point, move build mechanics to CONTRIBUTING

[nielspardon]

Aligns this repo's AGENTS.md with the ecosystem convention introduced for the spec repo in substrait-io/substrait#1117: a lean entry point plus the notes agents specifically need, with generally-applicable build and contribution mechanics living in the human-facing docs so there is a single source of truth.

What changes

• AGENTS.md becomes an entry point. The intro is now a "Start here" pointer to README.md and CONTRIBUTING.md rather than a standalone build guide.
• Adds "Keep PR descriptions high-signal." Tells agents to drop the noise they tend to add — lists of files touched, claims that CI-verified things pass, implicit process notes — and to keep commit bodies free of git trailers, since the PR title + body become the semantic-release commit message and feed CHANGELOG.md.
• Moves the general build mechanics to CONTRIBUTING.md. The build/test/format command reference, PMD ruleset and tripwires, and the build-logic included-build note land in a new "Building and testing" section; the JDK 17 daemon-consistency and GraalVM native-image details fold into the existing "Gradle & JDK 17" section. AGENTS.md keeps only the agent-specific verification workflow (build-before-push, cross-module compile check).

The codebase-specific architecture knowledge (module layout, Immutables/visitor/proto-converter patterns, Isthmus/Spark change-safety notes) stays in AGENTS.md — it is this repo's equivalent of the spec PR's "what agents need to get right." No content was lost; the build mechanics were relocated, not removed.

🤖 Generated with AI

[benbellick]

Thanks! I think this is a great improvement. There may be some more places worth slimming down, but we can save it for a subsequent PR. 🚀

[benbellick]

Also think we don't really need this now, it should just be in the README if it isn't already.

[benbellick]

Suggested change

	## Building and testing
	The build / test / format command reference, the PMD ruleset and its tripwires, the JDK 17
	daemon consistency rules, and the GraalVM native-image toolchain all live in
	[`CONTRIBUTING.md`](CONTRIBUTING.md#building-and-testing). Two habits matter most for agents:
	- **Build the whole thing before pushing.** Narrower local tasks pass while CI fails: **PMD**
	runs only via `check`/`build` and `javadoc` doclint only via `build`/`javadocJar` — never
	via `compileJava` / `test` / `spotlessCheck` — while CI runs the full `./gradlew build
	--rerun-tasks`. Run `./gradlew :core:check :core:javadoc` (and the module you touched)
	before pushing.
	- **When you extend the public expression/visitor API, verify the dependent modules still
	compile** — they have their own visitor implementors:
	`./gradlew :core:spotlessCheck :isthmus:compileJava :spark:spark-3.5_2.12:compileScala :examples:substrait-spark:compileJava`

Do we need all of that since its already in the CONTRIBUTING.md? If we find the agent isn't doing this itself, then we can add a single line that says:

run all tests and ensure they are passing before pushing

[benbellick]

I also think this whole section can reasonably be removed. Its all stuff you'd want a human to know as well, and there is a section called Commit Conventions already in CONTRIBUTING.md.

[benbellick]

➕

Thanks for adding this bit