CNTRLPLANE-3659: Add CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, and CLAUDE.md

[bryan-cox]

Summary

• Add CONTRIBUTING.md with development workflow, PR guidelines, testing commands, and high-risk area warnings
• Add AGENTS.md with AI agent instructions: forbidden imports, repo structure, key patterns, build/test commands
• Add ARCHITECTURE.md documenting major subsystems (operator framework, encryption/KMS, dual-layer crypto, manifest client), dependency map, and design decisions
• Add CLAUDE.md as a symlink to AGENTS.md

Part of the Hybrid Platforms Agentic SDLC initiative (OCPSTRAT-3200) — Shift Week contextification effort.

Jira: CNTRLPLANE-3659

Test plan

• Verify markdown renders correctly on GitHub
• Review with team for accuracy and completeness

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added AGENTS.md with repository contribution guardrails, required verification/CI steps, and dependency restrictions for this shared Go library.
  • Added ARCHITECTURE.md describing the library’s major subsystems, design decisions (including static pod lifecycle and crypto/KMS approach), dependency constraints, and testing strategy.
  • Added CONTRIBUTING.md with detailed PR expectations, development workflow, and coverage guidance.
  • Updated CLAUDE.md to link to the primary contribution guidance.

[openshift-ci-robot]

@bryan-cox: This pull request explicitly references no jira issue.

Details

In response to this:

Summary

• Add CONTRIBUTING.md with development workflow, PR guidelines, testing commands, and high-risk area warnings
• Add AGENTS.md with AI agent instructions: forbidden imports, repo structure, key patterns, build/test commands
• Add ARCHITECTURE.md documenting major subsystems (operator framework, encryption/KMS, dual-layer crypto, manifest client), dependency map, and design decisions

Part of the Hybrid Platforms Agentic SDLC initiative (OCPSTRAT-3200) — Shift Week contextification effort.

Test plan

• Verify markdown renders correctly on GitHub
• Review with team for accuracy and completeness

🤖 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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Enterprise

Run ID: 0f983176-55a9-47d1-bbe4-23b217f2b79e

📥 Commits

Reviewing files that changed from the base of the PR and between e82e7d1 and b6529b2.

📒 Files selected for processing (4)

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

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

• CLAUDE.md
• CONTRIBUTING.md
• ARCHITECTURE.md

---

Walkthrough

Adds four documentation files to library-go: AGENTS.md defines contribution rules and implementation patterns; ARCHITECTURE.md describes the library's subsystems and design decisions; CONTRIBUTING.md documents the contributor workflow and expectations; and CLAUDE.md links to AGENTS.md.

Changes

Repository Documentation

Layer / File(s)	Summary
Agent instructions and quick reference AGENTS.md, CLAUDE.md	AGENTS.md specifies library-go as a shared Go helper library and establishes critical rules: forbidden dependency imports (k8s.io/kubernetes, openshift/origin), mandatory go mod tidy && go mod vendor after dependency changes, required make verify and make test-unit completion, and no breaking public API changes. Documents repository structure under pkg/ and test/, key implementation patterns (ConfigObserver with RawExtension output, preconditions-over-defaults for static resources, controller naming), high-risk areas (encryption state machine, crypto/cert rotation, atomic pod swaps), standard build/test commands, and prohibited practices (no OWNERS changes, no code generation, no real-service unit test dependencies). CLAUDE.md is created as a symbolic link to AGENTS.md.
Architecture and subsystem design ARCHITECTURE.md	Documents library-go as OpenShift's shared foundation library and details major subsystems: operator controller framework (configuration observation, resource sync, static pod lifecycle with revision/status/management state controllers and atomic renameat2 directory swaps), encryption and KMS (state machine, controllers, pluggable crypto providers for KMS v1/v2 and AES/secretbox variants, API-server deployer with preflight checks), certificate management (crypto primitives, rotation controller with 80%-lifetime expiry trigger and CSR handling, PKI profile system), manifest-based client behavior, and configuration utilities. Specifies dependency architecture and constraints, design rationales (vendoring strategy, no code generators, atomic static pod swaps, dual crypto/PKI layering), and testing architecture covering unit tests with fake clientsets, E2E encryption tests with etcd/KMS sidecars, E2E monitoring tests, and shared test helpers.
Contribution and development workflow CONTRIBUTING.md	Establishes that contributions require a high bar given library-go's wide OpenShift impact. Specifies development expectations: feature branching, local build/test/vendor, target master branch, mandatory go mod tidy && go mod vendor when dependencies change. Sets PR expectations: focused scope, commit message conventions, unit/E2E test coverage as appropriate, OWNERS approval required. Documents available make test targets and where unit tests reside, Go code conventions, backward compatibility requirements for API-facing changes. Highlights subsystems needing extra care (encryption/KMS, certificate rotation, static pod management), notes CI merge-gating requirements, and provides guidance for determining whether a change belongs in library-go.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 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 and specifically summarizes the main change: adding four new documentation files to 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.
Stable And Deterministic Test Names	✅ Passed	This PR adds only documentation files (AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md symlink). No test files or Ginkgo test patterns are present, making the check not applicable.
Test Structure And Quality	✅ Passed	This PR only adds documentation files (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, CLAUDE.md). No Go test code or Ginkgo tests are present, making this check not applicable.
Microshift Test Compatibility	✅ Passed	PR adds only documentation files (AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md). No Ginkgo e2e tests are present, so the MicroShift test compatibility check does not apply.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	No Ginkgo e2e tests are added in this PR. Changes consist only of documentation files (AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md symlink) with no test code or test definitions.
Topology-Aware Scheduling Compatibility	✅ Passed	PR adds only documentation files (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, CLAUDE.md symlink). No deployment manifests, operator code, controllers, or scheduling constraints are introduced.
Ote Binary Stdout Contract	✅ Passed	PR only adds markdown documentation and a symlink (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, CLAUDE.md); no Go code or executable code present, so OTE stdout contract check is not applicable.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	This PR adds documentation files (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md, CLAUDE.md) and standard Go testing.T test files, but no Ginkgo e2e tests (It(), Describe(), Context(), When(), etc.)....
No-Weak-Crypto	✅ Passed	PR adds only documentation files (CONTRIBUTING.md, AGENTS.md, ARCHITECTURE.md) and a symlink (CLAUDE.md). No code implementations, weak crypto algorithms (MD5, SHA1, DES, RC4, 3DES, Blowfish, ECB),...
Container-Privileges	✅ Passed	PR only adds Markdown documentation files (AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md) and symlink (CLAUDE.md); no K8s manifests or container configs present.
No-Sensitive-Data-In-Logs	✅ Passed	PR contains only documentation files (AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md symlink) with no logging code or sensitive data. Check not applicable to documentation-only changes.

_{✏️ 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.}

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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 18-38: The tree structure block in AGENTS.md starting with the
pkg/ directory listing is missing a language label on its opening code fence.
Add the language identifier `text` (or `plaintext`) to the opening triple
backticks before pkg/ so it reads ```text instead of just ```. This satisfies
markdownlint requirements and improves rendering and scannability of the
documentation.

In `@ARCHITECTURE.md`:
- Around line 62-80: The fenced code block containing the dependency tree
diagram is missing a language specifier, which causes Markdown linting to fail.
Add the language identifier `text` immediately after the opening triple
backticks (```) at the start of the code block to properly format it and pass
linting validation.

🪄 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: 632adb71-0575-429f-afaa-e8168c8bb20a

📥 Commits

Reviewing files that changed from the base of the PR and between cb15bee and 17d9104.

📒 Files selected for processing (4)

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

[openshift-ci-robot]

@bryan-cox: This pull request references CNTRLPLANE-3659 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

• Add CONTRIBUTING.md with development workflow, PR guidelines, testing commands, and high-risk area warnings
• Add AGENTS.md with AI agent instructions: forbidden imports, repo structure, key patterns, build/test commands
• Add ARCHITECTURE.md documenting major subsystems (operator framework, encryption/KMS, dual-layer crypto, manifest client), dependency map, and design decisions
• Add CLAUDE.md as a symlink to AGENTS.md

Part of the Hybrid Platforms Agentic SDLC initiative (OCPSTRAT-3200) — Shift Week contextification effort.

Jira: CNTRLPLANE-3659

Test plan

• Verify markdown renders correctly on GitHub
• Review with team for accuracy and completeness

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

[bryan-cox]

/retest ci/prow/unit

[bryan-cox]

/test unit

[openshift-ci]

@bryan-cox: 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.