NO-JIRA: docs: update api-sme agent and api/AGENTS.md conventions

[enxebre]

Summary

• Add mandatory linter instruction to api-sme agent
• Add field grouping rule to api/AGENTS.md
• Add best practices section pointing to etcdbackup and karpenter types

Extracted from #8419.

Test plan

• Documentation-only change, no tests required

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Enforced linter checks must run and linter results now lead review output before submission.
  • Added best-practices for API field organization, requiring related spec fields be grouped into dedicated structures.
  • Clarified and reorganized API code review guidance and required pre-PR checks.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: LGTM mode

[openshift-ci-robot]

@enxebre: This pull request explicitly references no jira issue.

Details

In response to this:

Summary

• Add mandatory linter instruction to api-sme agent
• Add field grouping rule to api/AGENTS.md
• Add best practices section pointing to etcdbackup and karpenter types

Extracted from #8419.

Test plan

• Documentation-only change, no tests required

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 60a66b2e-0cbc-4b91-8132-0bc42bac1a13

📥 Commits

Reviewing files that changed from the base of the PR and between 5efafc3 and 3147f40.

📒 Files selected for processing (2)

• .claude/agents/api-sme.md
• api/AGENTS.md

✅ Files skipped from review due to trivial changes (2)

• api/AGENTS.md
• .claude/agents/api-sme.md

---

📝 Walkthrough

Walkthrough

The pull request updates agent and API documentation. .claude/agents/api-sme.md now requires running make api-lint-fix before review, instructs including the linter output at the start of reviews, and points reviewers to api/AGENTS.md instead of prior OpenShift guidance. api/AGENTS.md adds a "Best Practices and Patterns" section with a required "Field Grouping" rule and relocates the "Key make targets for API work," now requiring all listed checks to pass before opening a PR.

🚥 Pre-merge checks | ✅ 12

✅ Passed checks (12 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: updating the api-sme agent documentation and api/AGENTS.md conventions with specific guidance on linting and field grouping.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Stable And Deterministic Test Names	✅ Passed	Documentation-only PR with no test files or Ginkgo test code. Check for stable test names is not applicable.
Test Structure And Quality	✅ Passed	This PR contains only documentation changes (markdown files). The custom check requires reviewing Ginkgo test code for quality, but no test code exists in this PR.
Microshift Test Compatibility	✅ Passed	No Ginkgo e2e tests were added. PR includes documentation updates and a standard Go unit test, which are outside the scope of this check.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PR is documentation-only (api-sme agent and AGENTS.md conventions). No new Ginkgo e2e tests are added. Pre-existing test files in git history are unrelated to PR scope.
Topology-Aware Scheduling Compatibility	✅ Passed	PR contains only documentation changes to Markdown files. No deployment manifests, operator code, or controllers are modified. The topology-aware scheduling check is not applicable.
Ote Binary Stdout Contract	✅ Passed	PR contains only documentation updates. OTE Binary Stdout Contract check is not applicable as no test code was modified.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	Check not applicable. PR contains only documentation changes with no Ginkgo e2e tests added.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[bryan-cox]

Should we tell it to look at the go.mod to see the newest k8s version to pick from?

[bryan-cox]

/lgtm

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bryan-cox, enxebre

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [bryan-cox,enxebre]
• api/OWNERS [enxebre]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[openshift-merge-bot]

Scheduling tests matching the pipeline_run_if_changed or not excluded by pipeline_skip_if_only_changed parameters:
/test e2e-aks
/test e2e-aws
/test e2e-aws-upgrade-hypershift-operator
/test e2e-azure-self-managed
/test e2e-kubevirt-aws-ovn-reduced
/test e2e-v2-aws

[enxebre]

/verified by @enxebre

[openshift-ci-robot]

@enxebre: This PR has been marked as verified by @enxebre.

Details

In response to this:

/verified by @enxebre

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.55%. Comparing base (bded456) to head (3147f40).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8477      +/-   ##
==========================================
+ Coverage   37.53%   37.55%   +0.01%     
==========================================
  Files         751      751              
  Lines       92026    92029       +3     
==========================================
+ Hits        34544    34557      +13     
+ Misses      54841    54830      -11     
- Partials     2641     2642       +1     

see 2 files with indirect coverage changes

Flag	Coverage Δ
cmd-support	32.76% <ø> (ø)
cpo-hostedcontrolplane	36.78% <ø> (+0.01%)	⬆️
cpo-other	37.84% <ø> (+0.08%)	⬆️
hypershift-operator	47.93% <ø> (ø)
other	27.77% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.