docs: improve AGENTS.md and DEVELOPMENT.md guidance for AI agents

[cssjr]

Summary

• AGENTS.md: Add standard header with project description and CLAUDE.md symlink explanation; add references to CONTRIBUTING.md, agentic SDLC framework, and pre-commit hooks
• DEVELOPMENT.md: Add single-test/envtest commands, pre-PR gate section, Go version requirement, Jira integration guidance, expanded commit message format; fix stale skill references and command descriptions
• api/AGENTS.md, control-plane-operator/AGENTS.md, ARCHITECTURE.md: Fix stale references (karpenter v1beta1→v1 path, component count 30→40, add missing GCP platform)

Test plan

• Verify all referenced files exist and links are valid
• Confirm no functional code changes
• Documentation-only — no make verify required

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Platform support documentation now includes GCP as a supported platform.
  • Expanded developer guidance with test execution instructions, pre-commit verification steps, and minimum Go version requirements (1.25+).
  • Enhanced contributor workflow documentation with clearer setup steps and common troubleshooting guidance.

[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]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: cssjr
Once this PR has been reviewed and has the lgtm label, please assign csrwng for approval. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS
• api/OWNERS

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

[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: 87ed789b-c28b-46b6-8bbf-0b00031f45f0

📥 Commits

Reviewing files that changed from the base of the PR and between a6c3012 and 2dee5dc.

📒 Files selected for processing (5)

• AGENTS.md
• ARCHITECTURE.md
• DEVELOPMENT.md
• api/AGENTS.md
• control-plane-operator/AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR updates five documentation files across the repository to clarify AI agent guidance, expand developer contribution workflow instructions, document platform support, and adjust component inventory metrics. AGENTS.md was rewritten to explicitly note the CLAUDE.md symlink and emphasize minimal intentional scope with references to ARCHITECTURE.md; its Key References section was extended with links to CONTRIBUTING.md and pre-commit documentation. DEVELOPMENT.md received substantial additions including targeted testing instructions, clarified make-target behaviors, new pre-PR gate requirements, expanded gotchas guidance, and revised commit restructuring references. ARCHITECTURE.md added GCP to the platform support list. API and operator-specific documentation were updated to reflect the current Karpenter v1 API reference and adjusted component counts to ~40 for the control-plane-operator.

Possibly related PRs

• openshift/hypershift#8668: Adds root-level ARCHITECTURE.md documentation; this PR updates ARCHITECTURE.md with GCP platform support and other guidance doc changes.

Suggested reviewers

• bryan-cox
• enxebre
• csrwng

🚥 Pre-merge checks | ✅ 4 | ❌ 7

❌ Failed checks (7 inconclusive)

Check name	Status	Explanation	Resolution
Stable And Deterministic Test Names	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
Test Structure And Quality	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
Topology-Aware Scheduling Compatibility	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
Ipv6 And Disconnected Network Test Compatibility	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
No-Weak-Crypto	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
Container-Privileges	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.
No-Sensitive-Data-In-Logs	❓ Inconclusive	Repository clone failed, so this custom check could not run with code access.	Retry the review run. If this persists, inspect pre-merge custom-check logs for infrastructure or agent runtime failures.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: improvements to AGENTS.md and DEVELOPMENT.md documentation for AI agents, which aligns with all five files modified (AGENTS.md, DEVELOPMENT.md, api/AGENTS.md, control-plane-operator/AGENTS.md, and ARCHITECTURE.md).
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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 and usage tips.}

[cssjr]

/area ai

[cssjr]

/assign @bryan-cox

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 41.50%. Comparing base (a6c3012) to head (2dee5dc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8703   +/-   ##
=======================================
  Coverage   41.50%   41.50%           
=======================================
  Files         758      758           
  Lines       93689    93689           
=======================================
  Hits        38882    38882           
  Misses      52070    52070           
  Partials     2737     2737           

Flag	Coverage Δ
cmd-support	34.86% <ø> (ø)
cpo-hostedcontrolplane	43.59% <ø> (ø)
cpo-other	43.17% <ø> (ø)
hypershift-operator	51.57% <ø> (ø)
other	31.64% <ø> (ø)

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.

[openshift-ci]

@cssjr: all tests passed!

Full PR test history. Your PR dashboard.

Details

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 kubernetes-sigs/prow repository. I understand the commands that are listed here.