docs: add API conventions and deprecation guidance to AGENTS.md (#2763)

Add a section documenting OpenShift and Kubernetes API conventions
that must be followed for API changes, including the deprecation
pattern for CRD fields.

Signed-off-by: Predrag Knezevic <pknezevi@redhat.com>
Co-authored-by: Claude <noreply@anthropic.com>