docs: add AGENTS.md for coding agents

[ianmiell]

Adds AGENTS.md, guidance for coding agents (Claude Code, Codex, Copilot, Cursor), plus a one-line CLAUDE.md (@AGENTS.md) so Claude Code loads it.

It covers what isn't obvious from the code:

• the checks CI runs (there is no lint target: make test, gofmt -l ., make check-opa-version), and that the gofmt check fails on any dirty tree;
• the plugin contract: what breaks plugins, add-only proto changes, the Unimplemented fallback pattern for older peers, and optional interfaces instead of new Runner methods;
• changes that must go together (config keys + docs, evidence props + docs/policy_artifacts.md, api bump + OPA version);
• working against an unreleased api (go.work, test with GOWORK=off);
• agent-owned vs API-owned props; the agent never computes artifact digests; never write into the evaluated policies/ directory.

Also pins buf.build/protocolbuffers/go:v1.36.11 in buf.gen.yaml. It was unpinned, so a new release would churn every generated file; with the pin, buf generate reproduces the committed code exactly.

Every command was run on main, and the paths checked. A fresh agent given only CLAUDE.md planned a plugin-facing change correctly; the gaps it hit (optional plugin behaviour, installing buf, the unpinned plugin) are covered.

Companion PRs: compliance-framework/api#467 and compliance-framework/ui#319.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 143a0d4e-381d-4850-85f3-4efc54159490

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}