NO-JIRA: docs: make CLAUDE.md a symlink to AGENTS.md across the repo

[devguyio]

What this PR does / why we need it:

Makes CLAUDE.md a symlink to AGENTS.md in every directory that has an AGENTS.md, so there is a single source of truth for AI agent guidance with no content duplication or drift.

Changes:

• Root CLAUDE.md (was a stub pointing to AGENTS.md) → replaced with symlink
• api/CLAUDE.md → new symlink
• control-plane-operator/CLAUDE.md → new symlink
• support/controlplane-component/CLAUDE.md → new symlink
• contrib/ai/adding-marketplace-plugins.md → updated link from CLAUDE.md to AGENTS.md to avoid GitHub symlink rendering indirection

test/e2e/v2/CLAUDE.md already had this pattern and was untouched.

Which issue(s) this PR fixes:

N/A

Special notes for your reviewer:

The old root CLAUDE.md content (skills pointer, agents directory, Effective Go note) was all Claude Code plumbing that the harness auto-discovers — no content was lost.

Checklist:

• Subject and description added to both, commit and PR.
• Relevant issues have been referenced.
• This change includes docs.
• This change includes unit tests.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated documentation references across multiple locations to ensure consistent and current resource 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-robot]

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

Details

In response to this:

What this PR does / why we need it:

Makes CLAUDE.md a symlink to AGENTS.md in every directory that has an AGENTS.md, so there is a single source of truth for AI agent guidance with no content duplication or drift.

Changes:

• Root CLAUDE.md (was a stub pointing to AGENTS.md) → replaced with symlink
• api/CLAUDE.md → new symlink
• control-plane-operator/CLAUDE.md → new symlink
• support/controlplane-component/CLAUDE.md → new symlink
• contrib/ai/adding-marketplace-plugins.md → updated link from CLAUDE.md to AGENTS.md to avoid GitHub symlink rendering indirection

test/e2e/v2/CLAUDE.md already had this pattern and was untouched.

Which issue(s) this PR fixes:

N/A

Special notes for your reviewer:

The old root CLAUDE.md content (skills pointer, agents directory, Effective Go note) was all Claude Code plumbing that the harness auto-discovers — no content was lost.

Checklist:

• Subject and description added to both, commit and PR.
• Relevant issues have been referenced.
• This change includes docs.
• This change includes unit tests.

🤖 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.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[devguyio]

/area ai

[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: fe6c1bb6-f166-4eb4-b7ae-912b09427c86

📥 Commits

Reviewing files that changed from the base of the PR and between 5a83831 and 57f6e25.

📒 Files selected for processing (6)

• CLAUDE.md
• CLAUDE.md
• api/CLAUDE.md
• contrib/ai/adding-marketplace-plugins.md
• control-plane-operator/CLAUDE.md
• support/controlplane-component/CLAUDE.md

---

📝 Walkthrough

Walkthrough

Multiple CLAUDE.md files across the repository were updated to reference AGENTS.md. The changes span five different CLAUDE.md files located in the root directory, api/, control-plane-operator/, and support/controlplane-component/ directories. Additionally, a documentation reference in contrib/ai/adding-marketplace-plugins.md was updated from CLAUDE.md to AGENTS.md. These are purely documentation and reference updates with no changes to code logic or public APIs.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Stable And Deterministic Test Names	❌ Error	Test files use dynamic interpolation in test names. control_plane_workloads_test.go has 11 It() calls with fmt.Sprintf(workload.Name); control_plane_infrastructure_test.go has 1 similar violation.	Remove fmt.Sprintf from test names; use static strings. Move workload.Name to test bodies. Change It(fmt.Sprintf("should test X for %s", workload.Name)...) to It("should test X for workloads")...

✅ Passed checks (11 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: replacing CLAUDE.md files with symlinks to AGENTS.md across multiple directories in the repository.
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.
Test Structure And Quality	✅ Passed	PR contains only documentation and symlink changes (CLAUDE.md → AGENTS.md). No Ginkgo test code or test files are added/modified. Test structure check is not applicable.
Microshift Test Compatibility	✅ Passed	This PR only adds symlinks and updates documentation (CLAUDE.md files and one markdown doc). It does not add any new Ginkgo e2e tests, making the MicroShift Test Compatibility check not applicable.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	This PR contains only documentation and symlink changes (CLAUDE.md files and markdown updates). No new Ginkgo e2e tests are added, so the SNO test compatibility check is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	PR contains only documentation changes and workflow deletions. No deployment manifests, operator code, or scheduling constraints introduced. Check not applicable.
Ote Binary Stdout Contract	✅ Passed	PR modifies documentation files (CLAUDE.md symlinks and markdown). Test harness properly configures logging to stderr/GinkgoWriter, not stdout. No OTE Binary Stdout Contract violations detected.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	Check does not apply. PR only modifies documentation files and creates symlinks to AGENTS.md. No new Ginkgo e2e tests are added, which is the prerequisite for this check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.44%. Comparing base (e827093) to head (57f6e25).
⚠️ Report is 26 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8444   +/-   ##
=======================================
  Coverage   37.44%   37.44%           
=======================================
  Files         751      751           
  Lines       91969    91969           
=======================================
  Hits        34435    34435           
  Misses      54894    54894           
  Partials     2640     2640           

Flag	Coverage Δ
cmd-support	32.63% <ø> (ø)
cpo-hostedcontrolplane	36.48% <ø> (ø)
cpo-other	37.73% <ø> (ø)
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.

[bryan-cox]

/approve

[Nirshal]

/lgtm

[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

[hypershift-jira-solve-ci]

The e2e-aws test step never started — started_at and finished_at are both null. The job failed during the release image import phase before any test execution began.

Now I have all the evidence. Let me compile the report:

Test Failure Analysis Complete

Job Information

• Prow Job: pull-ci-openshift-hypershift-main-e2e-aws
• Build ID: 2052685565446328320
• Target: e2e-aws
• PR: NO-JIRA: docs: make CLAUDE.md a symlink to AGENTS.md across the repo #8444 (NO-JIRA: docs: make CLAUDE.md a symlink to AGENTS.md across the repo)

Test Failure Analysis

Error

step [release:n2minor] failed: failed to get CLI image: unable to find the 'cli' image
in the provided release image: unable to delete completed pod: could not delete completed
pod: Operation cannot be fulfilled on Pod "release-images-n2minor-cli": the UID in the
precondition (c7049eb9-8c78-42c4-8cd5-056b16f7216a) does not match the UID in record
(6fcd12ee-dca6-47f2-a281-e79b7c825304). The object might have been deleted and then recreated

Summary

This is a CI infrastructure flake — not a product or test code bug and completely unrelated to PR #8444's documentation changes. The job failed during the [release:n2minor] release image import phase (OCP 4.21) before any test step executed. The e2e-aws test never started. The root cause is a Kubernetes Pod UID race condition in the CI cluster's ci-operator: the release-images-n2minor-cli pod completed successfully at 09:43:09Z, but when ci-operator attempted to delete it ~34 minutes later at 10:17:12Z, the pod had been garbage-collected and recreated with a new UID, causing the precondition-based delete to fail. The 34-minute gap was caused by severe scheduling pressure on the CI cluster — the release-images-n1minor-cli pod was stuck Pending/unscheduled for 33 minutes (09:43:10Z → 10:16:14Z, 398 scheduling poll iterations), which blocked the entire release import pipeline.

Root Cause

CI infrastructure race condition in ci-operator's pod lifecycle management, exacerbated by CI cluster scheduling pressure. The failure chain:

1. 09:43:01Z–09:43:09Z: The release-images-n2minor-cli pod was created, ran, and completed successfully in ~4 seconds. It extracted the CLI image from the OCP 4.21 release payload. The pod had UID c7049eb9-8c78-42c4-8cd5-056b16f7216a.

2. 09:43:09Z–10:16:14Z (~33 minutes): The release-images-n1minor-cli pod was stuck in Pending/unscheduled state for 33 minutes (398 polling iterations logged). This blocked the entire release import pipeline because ci-operator processes releases sequentially after CLI extraction. The CI build cluster (build01) was under significant scheduling pressure during this window.

3. During the 33-minute wait: The completed release-images-n2minor-cli pod was garbage-collected by the Kubernetes cluster (completed pods are ephemeral resources) and subsequently recreated with a new UID 6fcd12ee-dca6-47f2-a281-e79b7c825304.

4. 10:17:12Z: When ci-operator finally finished waiting and tried to delete the release-images-n2minor-cli pod using the original UID as a precondition, the Kubernetes API rejected the delete with Operation cannot be fulfilled on Pod: the UID in the precondition does not match the UID in record.

5. 10:17:12Z: ci-operator interpreted this delete failure as a failure in the overall [release:n2minor] step, failing the entire job. The e2e-aws test step was never reached (started_at: null, finished_at: null).

This failure is entirely unrelated to PR #8444, which only modifies documentation files (CLAUDE.md symlinks). The PR changes were successfully built — all four images (hypershift-operator, hypershift, hypershift-tests, hypershift-cli) built and tagged into stable without error. The failure occurred in CI infrastructure code, not in any code built or tested from this PR.

Recommendations

1. Retry the job — This is a transient CI infrastructure flake. A simple re-trigger (/retest or /test e2e-aws) should pass since the failure is not related to the PR's code changes.

2. No code changes needed — PR NO-JIRA: docs: make CLAUDE.md a symlink to AGENTS.md across the repo #8444 only modifies documentation files (CLAUDE.md → AGENTS.md symlinks). All image builds succeeded. The test step was never reached.

3. CI infrastructure note — The ci-operator has a known fragility where long scheduling delays can cause Pod UID mismatches during cleanup. This is a ci-operator bug (it should handle UID-mismatch errors on completed pods gracefully rather than failing the entire job). Consider filing an issue against openshift/ci-tools if this pattern recurs frequently.

Evidence

Evidence	Detail
Failed step	[release:n2minor] — Import release payload "n2minor" (OCP 4.21.0-0.ci-2026-05-07-003508)
e2e-aws test status	Never started (started_at: null, finished_at: null)
n2minor-cli pod initial success	Pod completed successfully at 09:43:09Z after 4s
Original Pod UID	c7049eb9-8c78-42c4-8cd5-056b16f7216a
Recreated Pod UID	6fcd12ee-dca6-47f2-a281-e79b7c825304
n1minor-cli scheduling delay	33 minutes Pending (09:43:10Z → 10:16:14Z), 398 poll iterations
n1minor-cli scheduling latency	1,987 seconds (~33 min) per pod lifecycle metrics
PR #8444 files changed	CLAUDE.md, api/CLAUDE.md, control-plane-operator/CLAUDE.md, support/controlplane-component/CLAUDE.md (docs only)
Image builds	All 4 images (hypershift-operator, hypershift, hypershift-tests, hypershift-cli) built successfully
CI cluster	build01 (console.build01.ci.openshift.org), namespace ci-op-4yj19pfr
Failure reporting reason	executing_graph:step_failed:importing_release
JUnit summary	25 tests, 1 failure (release:n2minor), 0 skipped

---

[cwbotbot]

Test Results

e2e-aks

• Status: ✅ PASS
• Started: 2026-05-08T09:42:57Z
• View Job
• View Job History

e2e-aws

• Status: ❌ FAIL
• Started: 2026-05-08T09:42:57Z
• View Job
• View Job History

[devguyio]

/retest-required

[enxebre]

control-plane-operator/CLAUDE.md → new symlink
support/controlplane-component/CLAUDE.md → new symlink

We'll want to have adhoc content for these two

/approve

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bryan-cox, devguyio, 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,devguyio,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

[devguyio]

control-plane-operator/CLAUDE.md → new symlink
support/controlplane-component/CLAUDE.md → new symlink

We'll want to have adhoc content for these two

/approve

agreed.

[bryan-cox]

/verified bypass

[openshift-ci-robot]

@bryan-cox: The verified label has been added.

Details

In response to this:

/verified bypass

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.

[openshift-ci]

@devguyio: 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.