CNTRLPLANE-3728: Add AI agent documentation files

[bhperry]

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds AI SDLC documentation for openshift fork

Which issue(s) this PR is related to:

https://redhat.atlassian.net/browse/CNTRLPLANE-3728

Special notes for your reviewer:

Does this PR introduce a user-facing change?

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

Summary by CodeRabbit

• Documentation
  • Added repository guidance for AI-assisted contributors, including build/test expectations, commit message conventions, and downstream change rules.
  • Added an architecture overview describing the fork model, key integration areas, build and test workflow, and maintenance considerations.
• Chores
  • Added a linked companion guide for easier access to the repository instructions.

[openshift-ci-robot]

@bhperry: This pull request references CNTRLPLANE-3728 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:

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds AI SDLC documentation for openshift fork

Which issue(s) this PR is related to:

https://redhat.atlassian.net/browse/CNTRLPLANE-3728

Special notes for your reviewer:

Does this PR introduce a user-facing change?

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

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

@bhperry: the contents of this pull request could not be automatically validated.

The following commits could not be validated and must be approved by a top-level approver:

• 8e0ea96|UPSTREAM: : add AI agent documentation files: does not specify an upstream backport in the commit message

Comment /validate-backports to re-evaluate validity of the upstream PRs, for example when they are merged upstream.

[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

[coderabbitai]

Walkthrough

Adds repository-specific agent instructions, a CLAUDE.md symlink to them, and an architecture reference covering the OpenShift/Kubernetes fork model, build and test flow, integration points, and maintenance guidance.

Changes

Repository guidance and architecture reference

Layer / File(s)	Summary
Agent instructions AGENTS.md, CLAUDE.md	Adds repository-specific AI agent instructions and points CLAUDE.md at AGENTS.md.
Fork model and component surface ARCHITECTURE.md	Describes the fork model, rebase workflow, and OpenShift-specific API server, controller, feature-gate, cloud-provider, binary, and auth extensions.
Testing and design rules ARCHITECTURE.md	Documents the staging/ source-of-truth flow, build wrappers, preserved Make targets, test architecture, and architecture decision table.
Dependency flow and hotspots ARCHITECTURE.md	Shows the dependency path to downstream components and lists rebase-sensitive areas and carry-patch hotspots.
Runtime and references ARCHITECTURE.md	Covers observability, security, performance, future direction, and repository and external references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 15

✅ Passed checks (15 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the change set, which adds AI agent documentation files.
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	PR only adds docs/symlink files; no Ginkgo test definitions or titles were added or modified, so nothing dynamic to flag.
Test Structure And Quality	✅ Passed	This PR only adds documentation files; no Ginkgo or other test code was modified, so the test-quality check is not applicable.
Microshift Test Compatibility	✅ Passed	PR only adds docs/metadata files (AGENTS.md, ARCHITECTURE.md, CLAUDE.md, etc.); no new Ginkgo e2e tests or MicroShift-relevant APIs were added.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	The commit adds docs and no e2e test paths, so there are no new Ginkgo specs to evaluate for SNO compatibility.
Topology-Aware Scheduling Compatibility	✅ Passed	PASS: The PR only adds docs/symlink (AGENTS.md, ARCHITECTURE.md, CLAUDE.md); no deployment manifests, controllers, or scheduling code were changed.
Ote Binary Stdout Contract	✅ Passed	PASS: the commit only adds AGENTS.md, ARCHITECTURE.md, and a CLAUDE.md symlink; no process-level code or stdout writes were touched.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	Only AGENTS.md, ARCHITECTURE.md, and CLAUDE.md changed; no e2e/Ginkgo test code was added, so IPv4/disconnected-network concerns don't apply.
No-Weak-Crypto	✅ Passed	PASS: The PR only adds docs/symlink; scans of AGENTS.md and ARCHITECTURE.md found no MD5/SHA1/DES/RC4/3DES/Blowfish/ECB or custom-crypto code.
Container-Privileges	✅ Passed	This PR only adds markdown docs/symlink; no K8s manifests or privileged/securityContext settings were introduced.
No-Sensitive-Data-In-Logs	✅ Passed	No sensitive data or risky log examples were found in the new docs; logging mentions are generic and contain no secrets, PII, or internal hostnames.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[openshift-ci-robot]

@bhperry: This pull request references CNTRLPLANE-3728 which is a valid jira issue.

Details

In response to this:

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds AI SDLC documentation for openshift fork

Which issue(s) this PR is related to:

https://redhat.atlassian.net/browse/CNTRLPLANE-3728

Special notes for your reviewer:

Does this PR introduce a user-facing change?

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

Summary by CodeRabbit

• Documentation
• Added repository guidance for AI-assisted contributors, including build/test expectations, commit message conventions, and downstream change rules.
• Added an architecture overview describing the fork model, key integration areas, build and test workflow, and maintenance considerations.
• Chores
• Added a linked companion guide for easier access to the repository instructions.

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: bhperry
Once this PR has been reviewed and has the lgtm label, please assign jubittajohn 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:

• DOWNSTREAM_OWNERS

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

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@AGENTS.md`:
- Around line 36-40: The fenced example in AGENTS.md is missing a language tag,
which will trigger markdownlint MD040. Update the fenced block to use a bash
language label (or remove the fence entirely) in the section containing the
upstream carry/drop examples so the markdown stays lint-clean.

In `@ARCHITECTURE.md`:
- Around line 196-210: The fenced architecture diagram in ARCHITECTURE.md is
missing a language tag, which triggers markdownlint. Update the fenced block
that contains the upstream/staging/OpenShift flow diagram to use a suitable
language identifier such as text so the documentation passes lint consistently.

🪄 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: 1e90941f-1f4a-4b0b-8800-9375d2674f0b

📥 Commits

Reviewing files that changed from the base of the PR and between a466682 and 8e0ea96.

📒 Files selected for processing (3)

• AGENTS.md
• ARCHITECTURE.md
• CLAUDE.md

[bhperry]

/retest

[bhperry]

/retest

[openshift-ci]

@bhperry: 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-ovn-runc	8e0ea96	link	false	/test e2e-aws-ovn-runc

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.

[bhperry]

/retest