ai-tooling: add a claude slash command for identifying appropriate stakeholders to review an enhancement

.claude/commands/find-stakeholders.md

@@ -0,0 +1,111 @@
+---
+description: Find potential stakeholder reviewers for an OpenShift enhancement proposal
+---
+
+You are helping to identify potential stakeholders who should review a new OpenShift enhancement proposal.
+
+## Your Task
+
+1. **Locate and read the enhancement proposal:**
+   - Ask the user which enhancement file they want to find stakeholders for (if not obvious from context)
+   - Read the entire enhancement proposal to understand:
+     - What the enhancement does (Summary, Motivation sections)
+     - Which domains/components it affects (look for references to operators, APIs, subsystems)
+     - Whether it involves API changes (API Extensions section, api-approvers field)
+     - Specific technologies mentioned (networking, storage, authentication, etcd, etc.)
+     - Any existing reviewers/approvers already listed in the YAML frontmatter
+
+2. **Identify the affected OpenShift components and repositories** based on what you learned from reading the enhancement:
+   - Look for references to specific operators (e.g., cluster-authentication-operator, console-operator, machine-config-operator)
+   - Look for references to core components (e.g., openshift/api, hypershift, installer, oauth-server)
+   - Look for references to domain-specific components (e.g., cluster-monitoring-operator, cluster-network-operator, cluster-ingress-operator)
+   - Create a list of potential repository names to search for
+
+3. **Query the openshift GitHub organization** to find the actual repository names:
+   - Use WebFetch to query the GitHub API for openshift repositories: `https://api.github.com/orgs/openshift/repos?per_page=100&page=1`
+   - Note: The API returns paginated results (100 per page). You may need to fetch multiple pages if needed.
+   - Search through the repository list to find repositories that match the components mentioned in the enhancement
+   - Look for repositories containing relevant keywords (e.g., if enhancement mentions "authentication", look for repos with "authentication" or "oauth" in the name)
+   - Common repository patterns (but don't rely solely on these):
+     - `<component>-operator` (e.g., console-operator, machine-config-operator)
+     - `cluster-<component>-operator` (e.g., cluster-authentication-operator, cluster-network-operator)
+     - Component names without "-operator" suffix (e.g., installer, hypershift, api)
+
+4. **Fetch OWNERS files from the identified repositories** to get current maintainers:
+   - Use WebFetch to retrieve OWNERS files from the matched repositories
+   - Try both `master` and `main` branches:
+     - `https://raw.githubusercontent.com/openshift/<repo-name>/master/OWNERS`
+     - `https://raw.githubusercontent.com/openshift/<repo-name>/main/OWNERS`
+   - Fetch multiple repository OWNERS files in parallel when the enhancement affects multiple components
+   - Extract the `approvers` and `reviewers` lists from each OWNERS file
+
+5. **Use local enhancement OWNERS files as supplementary context** (lower priority):
+   - Look in `enhancements/<domain>/OWNERS` files for related domains (if they exist)
+   - Available domains include: network, ingress, storage, installer, authentication, machine-config, kube-apiserver, etcd, monitoring, observability, cluster-logging, dns, security, and many others
+   - Check the root `OWNERS` file for staff engineers who handle broad-scope enhancements
+   - **Important:** Local enhancement OWNERS files may be outdated or missing. Always prioritize repository OWNERS files from step 4 over enhancement OWNERS files
+
+6. **Verify API reviewer assignment** (critical step):
+   - Check if the enhancement involves API changes (new APIs, API extensions, CRDs, webhooks, etc.)
+   - If it does, verify that the `api-approvers` field in the YAML frontmatter is populated
+   - Use WebFetch to retrieve the openshift/api OWNERS file: https://github.com/openshift/api/blob/master/OWNERS
+   - Verify that at least one person listed in the enhancement's `api-approvers` field appears in the openshift/api OWNERS file as an approver or reviewer
+   - If there is NO api-approver listed OR the listed api-approver is not in the openshift/api OWNERS file, recommend that the author reach out to the #forum-api-review Slack channel to request an API reviewer be assigned
+   - Slack channel link: https://redhat.enterprise.slack.com/archives/CE4L0F143
+
+7. **Present your findings** in this format:
+
+   ```
+   ## Potential Stakeholder Reviewers for [Enhancement Name]
+
+   ### Primary Repository: openshift/[repo-name]
+   **Approvers:**
+   - @username1
+   - @username2
+
+   **Reviewers:**
+   - @username3
+   - @username4
+
+   ### Related Repository: openshift/[related-repo-name]
+   **Approvers:**
+   - @username5
+
+   **Reviewers:**
+   - @username6
+
+   ### API Review Status
+
+   [Either:]
+   ✅ **Good news!** The enhancement has @username listed as api-approver, who is confirmed as an [approver/reviewer] in the openshift/api OWNERS file.
+
+   [Or:]
+   ⚠️ **Action needed:** This enhancement introduces API changes but [does not have an api-approver listed / has @username listed who is not in the openshift/api OWNERS file]. Please reach out to the #forum-api-review Slack channel (https://redhat.enterprise.slack.com/archives/CE4L0F143) to request an API reviewer be assigned.
+
+   ### Recommended Next Steps:
+   1. For the primary repository (openshift/[repo]), consider reaching out to [specific approver] as your enhancement approver
+   2. Include reviewers from [list repositories] to ensure all affected areas are covered
+   3. If this is a broad-scope enhancement affecting multiple pillars, consider consulting with staff engineers from the root OWNERS file
+   ```
+
+8. **Provide guidance** on:
+   - Which approver would be most appropriate (remind them that a single approver is preferred)
+   - Which reviewers to include and what domain expertise they should focus on
+   - Whether they should reach out in `#forum-arch` on Slack if this is high-priority or broad-scope
+
+## Important Context
+
+- Enhancement reviewers should include representatives from any team that will need to do work for the enhancement
+- The approver helps recognize when consensus is reached and doesn't need to be a subject-matter expert (but it helps)
+- For broad-scope enhancements (changing OpenShift definition, adding required dependencies, changing customer support), a staff engineer approver is appropriate
+- Clearly indicate what aspect of the enhancement each reviewer should focus on (see guidelines/README.md for examples)
+
+## Tool Usage
+
+- Use WebFetch to query the GitHub API for openshift organization repositories
+- Use WebFetch to retrieve OWNERS files from identified openshift repositories (primary source of truth)
+- Use WebFetch to retrieve the openshift/api OWNERS file for API reviewer verification
+- Use the Glob tool to find local enhancement OWNERS files: `find enhancements -name "OWNERS"` (supplementary context only)
+- Use the Read tool to read local enhancement OWNERS files if needed (supplementary context only)
+- Be efficient: fetch multiple OWNERS files in parallel when possible
+- Remember: Repository OWNERS files are the authoritative source and should take priority over local enhancement OWNERS files

AGENTS.md

@@ -0,0 +1,178 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Repository Overview
+
+This is the OpenShift Enhancement Proposals repository, inspired by the Kubernetes enhancement process. It provides a centralized place to propose, discuss, and document enhancements to OpenShift (both OKD and OCP). Enhancements are tracked as markdown documents with YAML frontmatter metadata.
+
+## Repository Structure
+
+- `enhancements/` - Enhancement proposals organized by domain (e.g., `network/`, `installer/`, `machine-config/`, `authentication/`, etc.)
+- `guidelines/` - Process documentation including the enhancement template
+- `dev-guide/` - Developer guides for various OpenShift subsystems
+- `tools/` - Go-based CLI tools for managing enhancements
+- `this-week/` - Weekly and annual enhancement summary reports
+- `hack/` - Shell scripts for linting and automation
+
+## Common Commands
+
+### Linting
+```bash
+# Build the linter container image
+make image
+
+# Run markdown linter on changed files
+make lint
+
+# Override the base ref for template checking
+PULL_BASE_SHA=origin/master make lint
+```
+
+### Enhancement Tools
+The `tools/` directory contains a Go CLI for managing enhancements. Run from the `tools/` directory:
+
+```bash
+# Generate weekly enhancement report
+cd tools && go run ./main.go report
+
+# Generate annual summary
+cd tools && go run ./main.go annual-summary
+
+# Show reviewer statistics (last 31 days)
+cd tools && go run ./main.go reviewers
+
+# Show stale enhancement status
+cd tools && go run ./main.go closed-stale --dry-run
+
+# Leave comments on stale enhancements
+cd tools && go run ./main.go closed-stale
+```
+
+### Makefile Targets
+```bash
+# Show all available make targets
+make help
+
+# Run weekly report generation (includes closed-stale check and linting)
+make report
+
+# Generate annual summary
+make annual-summary
+```
+
+## Working with Enhancements
+
+### Creating a New Enhancement
+
+1. Choose the appropriate domain directory under `enhancements/` (or use root for broad-scope enhancements)
+2. Copy `guidelines/enhancement_template.md` to your chosen location
+3. Fill out the YAML metadata header (required fields: title, authors, reviewers, approvers, api-approvers, creation-date, tracking-link)
+4. Complete all required sections - the linter enforces this
+5. Create a PR and assign domain experts as reviewers
+
+### Enhancement Metadata
+
+Each enhancement must have YAML frontmatter with:
+- `title` - lowercased, spaces/punctuation replaced with `-`
+- `authors` - list of GitHub handles
+- `reviewers` - list of reviewers with their domain expertise
+- `approvers` - single approver preferred (responsible for consensus)
+- `api-approvers` - required for API changes, use "None" if no API changes
+- `creation-date` - format: `yyyy-mm-dd`
+- `tracking-link` - link to Jira feature/epic
+
+### Review Process
+
+- Authors manage the enhancement through review and approval
+- Reviewers must include representatives from teams doing implementation work
+- Approvers recognize when consensus is reached
+- PRs are merged when design is complete and consensus achieved
+- Implementation should ideally wait until enhancement is merged
+
+### Life-cycle
+
+- Active PRs stay open indefinitely
+- Inactive PRs get `life-cycle/stale` label after 28 days
+- Stale PRs become `life-cycle/rotten` after 7 more days
+- Rotten PRs close after another 7 days
+
+## Writing Conventions
+
+### Terminology
+- "OpenShift" or "openshift" (NEVER "Openshift")
+- Use U.S. English spelling and grammar
+- Always use the Oxford comma
+- "bare metal" - follow the [metal3-io style guide](https://github.com/metal3-io/metal3-docs/blob/master/design/bare-metal-style-guide.md)
+
+### Naming Patterns
+- Repository names match component names (e.g., `openshift/console-operator`)
+- Image names tagged into ImageStreams match component names
+- Git branches: `master` for development, `release-4.#` for maintenance
+- API objects follow [Kubernetes API naming conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#naming-conventions)
+
+## OpenShift Architecture Concepts
+
+### Operator-Based Architecture
+All cluster components are managed by operators that:
+- Deploy, reconfigure, self-heal, and report health status
+- Are coordinated by the cluster-version-operator (CVO) for core operators
+- Use OLM (Operator Lifecycle Manager) for optional components with independent lifecycles
+
+### Global Configuration
+- Exposed via API resources in `config.openshift.io` API group
+- Singleton objects named "cluster" control cluster-wide settings
+- `spec` contains user configuration, `status` contains system state
+- Components watch/poll configuration for changes
+
+### High Availability Patterns
+For 3-node control plane + 2-worker minimum topology:
+- 2 replicas with hard pod anti-affinity on hostname
+- Use maxUnavailable rollout strategy (25% default)
+- For >=3 replicas on workers: soft pod anti-affinity
+- Persistent storage considerations affect HA deployment
+
+### Priority Classes
+- `openshift-user-critical` - can be preempted by user workloads
+- `system-cluster-critical` - not preempted but can be OOMKilled
+- `system-node-critical` - not preempted, OOMKilled last
+
+### Resource Requests
+- Components MUST declare CPU and memory requests
+- Components SHOULD NOT set resource limits
+- CPU requests based on proportional baseline (etcd for control plane, SDN for all nodes)
+- Memory requests: 90th percentile usage + 10% overhead
+
+### Metrics and Monitoring
+Core operators should expose Prometheus metrics:
+- Use HTTPS with TLS client certificate authentication
+- Read API server's TLS security profile for allowed versions/ciphers
+- Support local authorization for well-known scraping identity
+- Deploy ServiceMonitors for collection by in-cluster Prometheus
+
+## Tools Configuration
+
+The enhancement tools require `~/.config/ocp-enhancements/config.yml`:
+
+```yaml
+github:
+  token: "your-github-personal-access-token"
+reviewers:
+  ignore:
+    - openshift-ci-robot
+```
+
+## Testing and CI
+
+- Markdown linting runs via containerized markdownlint
+- Template validation ensures all required sections are present
+- Metadata validation via `tools/cmd/metadataLint.go`
+- Linter can be overridden if template changes after PR creation (see README for guidance)
+
+## Key References
+
+- Enhancement template: `guidelines/enhancement_template.md`
+- OpenShift conventions: `CONVENTIONS.md`
+- API conventions: `dev-guide/api-conventions.md`
+- Breaking changes guide: `dev-guide/breaking-changes.md`
+- Test conventions: `dev-guide/test-conventions.md`

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Refer to @AGENTS.md for more information.