CNTRLPLANE-3718: Replace standalone CLAUDE.md with symlink to AGENTS.md

[sanchezl]

Summary

• Replace the standalone CLAUDE.md (101 lines, from PR NO-JIRA: Add CLAUDE.md #333) with a symlink to AGENTS.md
• All content in the old CLAUDE.md is now covered by AGENTS.md + ARCHITECTURE.md + CONTRIBUTING.md (added in PR CNTRLPLANE-3718: Add AI SDLC context files #362)
• Ensures Claude Code and other AI tools read the same single source of truth

Test plan

• readlink CLAUDE.md → AGENTS.md
• diff <(cat CLAUDE.md) <(cat AGENTS.md) → no output (identical content)
• Only CLAUDE.md changed vs main

Summary by CodeRabbit

• Documentation
  • Updated the project guidance file to use a shared reference instead of keeping separate inline content.
  • Removed the duplicated local text representation from that file, keeping repository guidance more consistent.

[openshift-ci-robot]

@sanchezl: This pull request references CNTRLPLANE-3718 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Migrate CLAUDE.md to AGENTS.md with symlink (Claude Code still discovers it automatically)
• Add CONTRIBUTING.md with development workflow, testing, commit conventions, and OWNERS structure
• Rewrite README.md with concise quick-start, OTE examples, and doc links
• Add ARCHITECTURE.md with component overview, CA rotation lifecycle, design decisions grounded in work-log research

Details

All four files are cross-referenced and consistent. AGENTS.md links to ARCHITECTURE.md for detailed architecture rather than duplicating it.

Design Decisions in ARCHITECTURE.md are sourced from code analysis, git history, and internal research notes — not just inferred from code structure.

Test plan

• Verify CLAUDE.md symlink resolves: readlink CLAUDE.md → AGENTS.md
• Verify all cross-references between docs resolve
• Verify build commands in docs match Makefile: make build, make test-unit, make verify

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]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign atiratree 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

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

[coderabbitai]

Walkthrough

CLAUDE.md is replaced with a single-line symbolic link marker pointing to AGENTS.md, removing the previously inlined guideline text from the file.

Changes

Documentation link update

Layer / File(s)	Summary
Convert CLAUDE.md to symlink marker CLAUDE.md	CLAUDE.md now resolves to AGENTS.md via a single-line link marker rather than containing inline content.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 15

✅ Passed checks (15 passed)

Check name	Status	Explanation
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	PASS: PR only changes CLAUDE.md documentation; no test files or Ginkgo titles were added or modified, so the rule isn’t applicable.
Test Structure And Quality	✅ Passed	PASS: The PR only changes CLAUDE.md docs/symlink; no Ginkgo test code was added or modified, so the test-quality check is not applicable.
Microshift Test Compatibility	✅ Passed	Only CLAUDE.md changed, and it became a symlink to AGENTS.md; no Ginkgo e2e tests or MicroShift-sensitive APIs were added.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	The PR only changes CLAUDE.md to a symlink; no Ginkgo e2e test files or specs were added, so SNO compatibility is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	Only documentation changed; the sole code delta is CLAUDE.md becoming a symlink to AGENTS.md, so no scheduling logic or manifests were introduced.
Ote Binary Stdout Contract	✅ Passed	PASS: The PR only changes CLAUDE.md into a symlink to AGENTS.md; no main/TestMain/RunSpecs or stdout-writing code was modified.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	The patch only changes CLAUDE.md to a symlink; no Ginkgo/e2e test files or network-dependent tests were added.
No-Weak-Crypto	✅ Passed	Only CLAUDE.md changed, and it became a symlink to AGENTS.md; no weak algorithms, custom crypto, or secret comparisons were introduced.
Container-Privileges	✅ Passed	PR diff vs origin/main changes only CLAUDE.md to a symlink; no YAML/K8s manifests or privilege-related fields were touched.
No-Sensitive-Data-In-Logs	✅ Passed	Only change is CLAUDE.md symlink to AGENTS.md; no logging code or sensitive-data strings appear in the modified docs.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: migrating CLAUDE.md to a symlink pointing at AGENTS.md.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ARCHITECTURE.md`:
- Around line 29-37: The controller package paths in the architecture table are
inconsistent with the repo layout and should be normalized. Update the Package
column entries to use the actual controller paths from the codebase, especially
the serving cert controller path referenced by starter.go, so the table matches
the navigable package structure. Keep the same controller names, but correct
each package reference to the real `pkg/controller/...` locations used in the
repository.
- Around line 57-65: The CA rotation timeline example is internally inconsistent
because the automated rotation trigger does not line up with the 26-month
lifetime and the “remaining < 13m” condition. Update the timeline in
ARCHITECTURE.md so the rotation point referenced by the example is consistent
with the trigger logic in the signing CA lifetime explanation, either by
changing the trigger threshold or adjusting the T+13m event to reflect when the
condition actually becomes true.

In `@README.md`:
- Line 34: The README link is pointing to the wrong location because the
`enhancements/` path segment is missing from the GitHub URL. Update the existing
documentation link in README so it matches the adjacent link pattern and points
to the correct `openshift/enhancements` path for the “Testing a
ClusterOperator/Operand image in a cluster” section.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6902ad55-1fe2-40cc-a076-0323fe97b2b5

📥 Commits

Reviewing files that changed from the base of the PR and between 35cf518 and aa84198.

📒 Files selected for processing (6)

• AGENTS.md
• ARCHITECTURE.md
• CLAUDE.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md

[openshift-ci]

@sanchezl: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/e2e-aws-upgrade	9488716	link	true	/test e2e-aws-upgrade

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.