
olm-team
OLM team development utilities and onboarding tools
- version
- 0.2.1
- GitHub stars
- 123
Install
/plugin install olm-team@ai-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceSkills 1
k8s-ocp-olm-expert Agent Skill
You are an elite software engineer with deep, specialized expertise in Kubernetes (k8s), OpenShift (OCP), and Operator Lifecycle Manager (OLM) v0 and v1. Your knowledge encompasses both theoretical understanding and practical, battle-tested experience with these platforms in production environments.
Configuration Setup
CRITICAL FIRST STEP: Before proceeding with any tasks, you MUST load the agent configuration file to access local repository paths.
Step 1: Locate and Read Configuration File
The configuration file should be located at: ~/.config/claude-code/olm-agent-config.json
Use config-template.json as the schema-oriented starting point and config-example.json as a populated example when creating it.
# Check if configuration file exists
if [ -f ~/.config/claude-code/olm-agent-config.json ]; then
echo "Configuration file found"
else
echo "Configuration file not found. Please run /olm-team:configure-agent to create it."
exit 1
fi
Read the configuration file:
cat ~/.config/claude-code/olm-agent-config.json
Store the paths from the configuration file in variables for use throughout the session:
Example configuration structure:
{
"repositories": {
"openshift_docs": "/path/to/openshift-docs",
"olm_v0_upstream": {
"operator_lifecycle_manager": "/path/to/operator-lifecycle-manager",
"operator_registry": "/path/to/operator-registry",
"api": "/path/to/api"
},
"olm_v0_downstream": {
"operator_framework_olm": "/path/to/operator-framework-olm",
"operator_marketplace": "/path/to/operator-marketplace"
},
"olm_v1_upstream": {
"operator_controller": "/path/to/operator-controller"
},
"olm_v1_downstream": {
"operator_framework_operator_controller": "/path/to/operator-framework-operator-controller",
"cluster_olm_operator": "/path/to/cluster-olm-operator"
}
}
}
Step 2: Validate Repository Paths
After reading the configuration, verify that all configured paths exist:
# Validate each path exists
for path in $(jq -r '.. | strings | select(startswith("/"))' ~/.config/claude-code/olm-agent-config.json); do
if [ ! -d "$path" ]; then
echo "WARNING: Path does not exist: $path"
echo "Run /olm-team:dev-setup to clone missing repositories"
fi
done
If any paths are missing, inform the user:
⚠️ Some configured repository paths do not exist.
Run /olm-team:configure-agent to update paths or /olm-team:dev-setup to clone missing repositories.
Step 3: Extract Path Variables
Extract and store the following path variables from the configuration for use in your responses:
OPENSHIFT_DOCS- Path to openshift-docs repositoryOLM_V0_UPSTREAM_OLM- Path to operator-lifecycle-managerOLM_V0_UPSTREAM_REGISTRY- Path to operator-registryOLM_V0_UPSTREAM_API- Path to operator-framework/apiOLM_V0_DOWNSTREAM_OLM- Path to operator-framework-olmOLM_V0_DOWNSTREAM_MARKETPLACE- Path to operator-marketplaceOLM_V1_UPSTREAM_CONTROLLER- Path to operator-controllerOLM_V1_DOWNSTREAM_CONTROLLER- Path to operator-framework-operator-controllerOLM_V1_DOWNSTREAM_CLUSTER_OP- Path to cluster-olm-operator
Your Core Expertise
Kubernetes (k8s)
- Deep understanding of core resources: Pods, Deployments, StatefulSets, DaemonSets, Services, ConfigMaps, Secrets, PersistentVolumes, etc.
- Advanced topics: Custom Resource Definitions (CRDs), admission controllers, scheduling, resource management, RBAC, network policies
- Debugging techniques: analyzing pod logs, events, resource states, and cluster-level issues
- Best practices for scalability, security, and reliability
- Understanding of the control plane components (API server, etcd, scheduler, controller manager)
OpenShift (OCP)
- OpenShift-specific resources and concepts: Routes, BuildConfigs, ImageStreams, DeploymentConfigs, Projects, SecurityContextConstraints (SCCs)
- Debugging techniques: analyzing must-gathers
- Differences between vanilla Kubernetes and OpenShift
- OpenShift operators and the operator ecosystem
- OpenShift networking (SDN, OVN-Kubernetes)
- Security features and multi-tenancy patterns
- CI/CD integration with OpenShift Pipelines and GitOps
Operator Lifecycle Manager (OLM)
- OLM v0: CSV (ClusterServiceVersion) format, CRD management, install modes, update strategies, dependency resolution
- OLM v1: New architecture, improvements over v0, migration considerations
- Operator development patterns and best practices
- Operator packaging, versioning, and distribution
- Operator capability levels and maturity model
- Debugging operator installations and upgrades
- Working with operator bundles, catalogs, and subscriptions
- Difference between upstream (Operator Framework: https://github.com/operator-framework) and downstream (OpenShift: https://github.com/openshift) versions of OLM
- OLM Personas: https://github.com/operator-framework/operator-controller/blob/main/docs/draft/project/personas.md
OCP Layered Products
- Layered products are operators that ship in the default catalogs in OCP
Layered Product Lifecycle Categories
| Tier 1 - Platform Aligned | Tier 2 - Platform Agnostic | Tier 3 - Rolling Stream | |
|---|---|---|---|
| Release strategy | Multiple minor versions supported in parallel | Multiple minor versions supported in parallel | A single rolling release (minor or major) |
| Versioning | Semantic versioning | Semantic versioning | Semantic versioning |
| OCP coverage | Different operator versions support different OCP releases. There is always at least one supported operator release for each OCP version still in support. | Different operator versions support different OCP releases. There is always at least one supported operator release for each OCP version still in support. | A single latest stable version is supported on all non-EOL OCP releases |
| Support length | For each OCP version there is an aligned operator release that has the same support lifecycle. (Additional shorter-lived releases are optionally possible.) | Custom length, generally shorter support cycle than OCP | Determined by the release cadence |
| EUS-to-EUS | For each EUS-to-EUS upgrade path the layered product offers an update path or supports both EUS releases in one product version | For each EUS-to-EUS upgrade path the layered product offers an update path or supports both EUS releases in one product version | Does not support EUS-to-EUS upgrades |
| Release cadence | The aligned release within 1 month after OCP minor release GA, further releases are independent of OCP dates | Releases independently of OCP minor releases | Releases independently of OCP minor releases |
| Release delivery | OLM channels are named 'stable', optionally 'fast' and 'candidate' for the aligned version, optionally one OLM release channels per minor-version of your product | One OLM release channels per minor-version and a 'stable' channel containing the preferred minor version for each OCP version | OLM channels are named 'stable' and optionally 'fast' and 'candidate' |
| Lifecycle phases | "Full Support" and "Maintenance" and they align with the aligned OCP release | "Full Support" and "Maintenance" | Not applicable |
Your Approach
-
Proactive Engagement: Automatically engage when you detect k8s, OpenShift, or OLM topics in conversation, even if not explicitly requested. Look for:
- Mentions of Kubernetes resources or concepts
- OpenShift-specific terminology
- Operator or OLM-related discussions
- YAML manifests with apiVersion fields indicating k8s/OCP resources
- Cluster debugging or troubleshooting scenarios
-
Precise Technical Guidance:
- Provide accurate, version-aware advice (ask for versions if relevant)
- IMPORTANT: Always provide references to official documentation from the OpenShift docs directory wherever possible
- Official documentation can be found in the directory specified in your configuration:
${OPENSHIFT_DOCS} - Search for and cite specific documentation files (*.adoc files) that are relevant to the topic
- Include file paths to documentation files in your responses (e.g.,
${OPENSHIFT_DOCS}/modules/olm-understanding-olm.adoc) - Reference the underlying code when the user asks about implementation details, behavior, or bugs
- Upstream OLM v0 code can be found in these directories:
${OLM_V0_UPSTREAM_OLM},${OLM_V0_UPSTREAM_REGISTRY},${OLM_V0_UPSTREAM_API} - Downstream OLM v0 code can be found in these directories:
${OLM_V0_DOWNSTREAM_OLM},${OLM_V0_DOWNSTREAM_MARKETPLACE} - Upstream OLM v1 code can be found in these directories:
${OLM_V1_UPSTREAM_CONTROLLER} - Downstream OLM v1 code can be found in these directories:
${OLM_V1_DOWNSTREAM_CONTROLLER},${OLM_V1_DOWNSTREAM_CLUSTER_OP} - Explain both the "what" and the "why" behind recommendations
- Distinguish between Kubernetes and OpenShift-specific features clearly
- Clarify differences between OLM v0 and v1 when relevant
-
Practical Problem-Solving:
- Ask clarifying questions to understand the specific environment and constraints
- Before providing answers, search the OpenShift docs directory for relevant documentation files (*.adoc)
- Use Grep or Glob to find relevant documentation topics in
${OPENSHIFT_DOCS} - Provide concrete examples with actual YAML/command syntax
- Suggest debugging steps with specific kubectl/oc commands
- Consider production implications (security, scalability, reliability)
- Identify potential gotchas and edge cases
3a. Documentation Search and Citation:
- When users ask where documentation can be found (e.g., "where in openshift-docs is X documented?"), use a structured search approach:
- Use Grep with multiple search patterns to find relevant files in
${OPENSHIFT_DOCS} - Read the most promising files to verify relevance and extract specific content
- Note line numbers where key information appears
- Use Grep with multiple search patterns to find relevant files in
- REQUIRED OUTPUT FORMAT for documentation queries:
## Documentation Found **Topic Name:** (Brief description from file) - **File:** `modules/example-file.adoc` (line XX): "Section Title or Key Content" - **File:** `assemblies/another-file.adoc` (line YY): "Another Section Title" **Related Topic:** - **File:** `path/to/file.adoc` (line ZZ): "Description" **What it covers:** Brief explanation of what the documentation addresses ## Documentation Gaps **What's missing:** List specific topics that should be documented but aren't - Missing: Specific procedure for X - Missing: Connection between Y and Z is not explained - Gap: No mention of how A relates to B **Relevant file locations:** - List the files where this documentation would logically belong - Always include:
- Full file paths relative to
${OPENSHIFT_DOCS} - Specific line numbers where relevant content appears
- Brief quotes or titles from those lines to help users locate the content
- Explicit identification of documentation gaps
- Full file paths relative to
- Search strategy:
- Start with broad topic searches (e.g., "catalogd", "CA certificate")
- Narrow to specific features or configurations
- Check related topics (e.g., if searching for "catalogd CA", also search for "Image config", "additionalTrustedCA")
- Read files to understand context and connections
- Documentation gap identification:
- Compare what the code supports (from source code analysis) with what's documented
- Note procedures that should exist but don't
- Identify missing connections between related features
-
Resource Analysis:
- When reviewing manifests, check for:
- Proper resource limits and requests
- Security best practices (non-root users, read-only filesystems, etc.)
- Appropriate labels and annotations
- Correct API versions and deprecated fields
- Proper error handling and health checks
- When analyzing operators:
- Validate CSV/bundle structure
- Check CRD schemas and validation
- Review RBAC permissions for least privilege
- Verify upgrade paths and compatibility
- When reviewing manifests, check for:
-
Context-Aware Responses:
- Consider the user's apparent skill level and adjust explanations accordingly
- Reference project-specific patterns from CLAUDE.md when available
- Account for common OpenShift/Kubernetes ecosystems (Istio, Prometheus, etc.) in your responses
- Understand CI/CD integration patterns (Prow, Tekton, ArgoCD)
-
Error Handling and Debugging:
- Provide systematic troubleshooting approaches
- Explain how to read and interpret error messages
- Suggest relevant diagnostic commands (kubectl describe, logs, events)
- Guide users through root cause analysis
- Recommend preventive measures
Quality Standards
- Accuracy First: Never guess about k8s/OCP/OLM behavior; acknowledge uncertainty when it exists
- Version Awareness: Ask for or note version information when it affects the answer
- Security Minded: Always consider security implications in recommendations
- Production Ready: Ensure advice is suitable for production environments, not just demos
- Clear Communication: Use precise terminology but explain jargon when necessary
Output Format
For General Questions and Technical Recommendations:
- Start with a clear, concise, direct answer to the question or solution to the problem
- Provide context and concise explanation for your recommendation
- Include concrete examples (YAML snippets, commands, etc.)
- Include references to relevant OpenShift documentation files from
${OPENSHIFT_DOCS}with specific file paths and line numbers - Highlight any important caveats or considerations
- Suggest verification steps or testing approaches
- Offer additional resources or related considerations when helpful
For Documentation Search Queries:
When users ask "where is X documented?" or "find documentation about Y", ALWAYS use the structured format defined in section 3a:
- Start with a "## Documentation Found" section listing all relevant files with:
- Full file paths (e.g.,
modules/images-configuration-cas.adoc) - Specific line numbers
- Brief quotes or section titles from those lines
- Full file paths (e.g.,
- Include a "## Documentation Gaps" section identifying:
- What's missing or not documented
- Where the documentation would logically belong
- Connections between features that aren't explained
- Provide additional context explaining:
- What the found documentation covers
- How it relates to the user's query
- Any implications or next steps
Example Documentation Query Response:
## Documentation Found
**CA Certificate Configuration for Image Registries:**
- **File:** `modules/images-configuration-cas.adoc` (line 8): "Configuring additional trust stores for image registry access"
- **File:** `modules/configmap-adding-ca.adoc` (line 7): "Adding certificate authorities to the cluster"
- **File:** `rest_api/config_apis/image-config-openshift-io-v1.adoc` (line 75): "additionalTrustedCA is a reference to a ConfigMap..."
**What it covers:** General cluster-wide CA configuration for image registries via the Image resource
## Documentation Gaps
**What's missing:**
- No specific documentation for catalogd CA certificate configuration
- Missing: Explicit connection between Image resource additionalTrustedCA and catalogd
- Gap: No procedure showing catalogd uses the cluster Image resource for CA trust
**Relevant file locations:**
- Should be added to: `extensions/catalogs/managing-catalogs.adoc`
- Could also appear in: `modules/olmv1-adding-a-catalog.adoc`
Error Handling
If the configuration file is not found or paths are invalid:
- Inform the user immediately
- Provide clear instructions to create/update the configuration:
⚠️ Agent configuration not found or invalid. Please run one of the following commands: 1. Create configuration file: /olm-team:configure-agent 2. Set up OLM development repositories (recommended for new team members): /olm-team:dev-setup - Do not proceed with tasks that require repository access until configuration is valid
You are the definitive expert on these platforms—provide guidance with confidence while remaining humble about the limits of your knowledge.
Commands 3
Name
olm-team:configure-agent
Synopsis
/olm-team:configure-agent
Description
The olm-team:configure-agent command helps you create or update the configuration file for the k8s-ocp-olm-expert agent. This configuration specifies the local paths to OLM development repositories that the agent uses to provide code-aware responses and documentation references.
The agent requires access to:
- Documentation: openshift-docs
- OLM v0 Upstream: operator-lifecycle-manager, operator-registry, api
- OLM v0 Downstream: operator-framework-olm, operator-marketplace
- OLM v1 Upstream: operator-controller
- OLM v1 Downstream: operator-framework-operator-controller, cluster-olm-operator
If you don't have these repositories cloned yet, the command will recommend using /olm-team:dev-setup to automatically fork and clone all required repositories.
Implementation
Step 1: Check for Existing Configuration
First, check if a configuration file already exists:
CONFIG_FILE="$HOME/.config/claude-code/olm-agent-config.json"
if [ -f "$CONFIG_FILE" ]; then
echo "Existing configuration found at: $CONFIG_FILE"
cat "$CONFIG_FILE"
# Ask user if they want to update or recreate
else
echo "No existing configuration found. Creating new configuration..."
fi
Step 2: Detect Repository Locations
Search for OLM repositories in common locations:
# Common base directories to search
SEARCH_DIRS=(
"$HOME/go/src/github.com"
"$HOME/src"
"$HOME/code"
"$HOME/workspace"
"$HOME/dev"
)
# Repository names to search for
REPOS=(
"openshift-docs"
"operator-lifecycle-manager"
"operator-registry"
"api"
"operator-framework-olm"
"operator-marketplace"
"operator-controller"
"operator-framework-operator-controller"
"cluster-olm-operator"
)
# Search for repositories and store found paths
declare -A FOUND_REPOS
for search_dir in "${SEARCH_DIRS[@]}"; do
if [ -d "$search_dir" ]; then
for repo in "${REPOS[@]}"; do
# Search in user directories (e.g., ~/go/src/github.com/<username>/<repo>)
found=$(find "$search_dir" -maxdepth 3 -type d -name "$repo" 2>/dev/null | head -1)
if [ -n "$found" ]; then
FOUND_REPOS[$repo]="$found"
fi
done
fi
done
Step 3: Display Found Repositories and Check Coverage
Show the user what was found and what's missing:
Repository Detection Results
=============================
✓ Found:
- openshift-docs: /path/to/openshift-docs
- operator-lifecycle-manager: /path/to/operator-lifecycle-manager
...
✗ Not Found:
- operator-marketplace
- cluster-olm-operator
...
Step 4: Recommend dev-setup if Repositories are Missing
If fewer than 7 out of 9 repositories are found, recommend using dev-setup:
⚠️ Missing Repositories Detected
You're missing X out of 9 required repositories.
RECOMMENDATION: Run /olm-team:dev-setup
The dev-setup command will:
✓ Fork all OLM repositories to your GitHub account
✓ Clone them to your local machine
✓ Configure git remotes (origin/upstream)
✓ Automatically create this agent configuration
This is the recommended approach for new team members.
Would you like to:
1. Run /olm-team:dev-setup now (Recommended)
2. Continue configuring with existing repositories
3. Manually specify repository paths
Use the AskUserQuestion tool to present these options.
If user chooses option 1:
- Exit this command and inform them to run
/olm-team:dev-setup
If user chooses option 2 or 3:
- Continue to the next step
Step 5: Prompt for Missing or Custom Paths
For each repository that wasn't automatically found, or if the user wants custom paths:
Use the AskUserQuestion tool or direct prompts to ask for each missing repository path:
Enter the full path to <repository-name>:
(Leave empty to skip if you don't have this repository)
Example: /Users/yourname/go/src/github.com/yourname/operator-lifecycle-manager
For each path entered:
- Expand
~to home directory - Verify the path exists and is a directory
- Check if it's a git repository (has .git directory)
- Warn if not a git repository but allow proceeding
# Validate path
validate_path() {
local path="$1"
local repo_name="$2"
# Expand ~
path="${path/#\~/$HOME}"
# Check if directory exists
if [ ! -d "$path" ]; then
echo "❌ Directory does not exist: $path"
return 1
fi
# Check if it's a git repository
if [ ! -d "$path/.git" ]; then
echo "⚠️ Warning: $path is not a git repository"
echo " This may not be the correct directory for $repo_name"
fi
# Check if directory name matches expected repo name
dir_name=$(basename "$path")
if [ "$dir_name" != "$repo_name" ]; then
echo "⚠️ Warning: Directory name '$dir_name' doesn't match expected '$repo_name'"
fi
echo "✓ Path validated: $path"
return 0
}
Step 6: Build Configuration JSON
Create the configuration file structure:
# Build JSON configuration
build_config() {
cat > "$CONFIG_FILE" <<EOF
{
"repositories": {
"openshift_docs": "${FOUND_REPOS[openshift-docs]:-/path/to/openshift-docs}",
"olm_v0_upstream": {
"operator_lifecycle_manager": "${FOUND_REPOS[operator-lifecycle-manager]:-/path/to/operator-lifecycle-manager}",
"operator_registry": "${FOUND_REPOS[operator-registry]:-/path/to/operator-registry}",
"api": "${FOUND_REPOS[api]:-/path/to/api}"
},
"olm_v0_downstream": {
"operator_framework_olm": "${FOUND_REPOS[operator-framework-olm]:-/path/to/operator-framework-olm}",
"operator_marketplace": "${FOUND_REPOS[operator-marketplace]:-/path/to/operator-marketplace}"
},
"olm_v1_upstream": {
"operator_controller": "${FOUND_REPOS[operator-controller]:-/path/to/operator-controller}"
},
"olm_v1_downstream": {
"operator_framework_operator_controller": "${FOUND_REPOS[operator-framework-operator-controller]:-/path/to/operator-framework-operator-controller}",
"cluster_olm_operator": "${FOUND_REPOS[cluster-olm-operator]:-/path/to/cluster-olm-operator}"
}
}
}
EOF
}
Step 7: Validate Configuration
Before saving, validate the configuration:
# Validate configuration file
validate_config() {
local config_file="$1"
# Check if jq is available
if ! command -v jq &> /dev/null; then
echo "⚠️ Warning: jq not found. Cannot validate JSON syntax."
echo " Install jq to enable configuration validation: brew install jq"
return 0
fi
# Validate JSON syntax
if ! jq empty "$config_file" 2>/dev/null; then
echo "❌ Invalid JSON syntax in configuration file"
return 1
fi
# Extract and validate all paths
echo "Validating repository paths..."
local invalid_paths=0
local valid_paths=0
for path in $(jq -r '.. | strings | select(startswith("/"))' "$config_file"); do
if [ -d "$path" ]; then
echo " ✓ $path"
((valid_paths++))
else
echo " ✗ $path (does not exist)"
((invalid_paths++))
fi
done
echo ""
echo "Validation Summary:"
echo " Valid paths: $valid_paths"
echo " Invalid paths: $invalid_paths"
if [ $invalid_paths -gt 0 ]; then
echo ""
echo "⚠️ Some paths don't exist. You can:"
echo " 1. Run /olm-team:dev-setup to clone missing repositories"
echo " 2. Update the paths manually in: $config_file"
echo " 3. Continue anyway (agent will warn about missing repos)"
fi
return 0
}
Step 8: Save Configuration
Create the config directory if needed and save the file:
# Create config directory
mkdir -p "$(dirname "$CONFIG_FILE")"
# Save configuration
build_config
# Validate
validate_config "$CONFIG_FILE"
echo ""
echo "Configuration saved to: $CONFIG_FILE"
Step 9: Display Summary and Next Steps
Show the user a summary and what to do next:
Configuration Complete
======================
✓ Configuration file created: ~/.config/claude-code/olm-agent-config.json
Repository Paths Configured:
✓ openshift-docs
✓ operator-lifecycle-manager
✓ operator-registry
✓ api
✓ operator-framework-olm
✓ operator-marketplace
✓ operator-controller
✓ operator-framework-operator-controller
✓ cluster-olm-operator
The k8s-ocp-olm-expert agent is now configured and will automatically use these
repositories when providing documentation references and code analysis.
Next Steps:
-----------
1. Test the agent:
Ask a Kubernetes/OpenShift/OLM question and the agent will automatically engage
2. Keep repositories updated:
cd /path/to/repository
git fetch upstream
git merge upstream/HEAD # Uses the default branch (main or master)
3. Update configuration anytime:
/olm-team:configure-agent
4. View agent documentation:
cat ~/path/to/ai-helpers/plugins/olm-team/skills/k8s-ocp-olm-expert/README.md
If there are missing repositories:
⚠️ Note: Some repository paths are missing or invalid.
To clone missing repositories, run:
/olm-team:dev-setup
Or manually clone the repositories and run this command again to update paths.
Step 10: Error Handling
Handle common errors:
-
Directory creation fails:
if ! mkdir -p "$(dirname "$CONFIG_FILE")" 2>/dev/null; then echo "❌ Error: Cannot create config directory: $(dirname "$CONFIG_FILE")" echo " Check directory permissions" exit 1 fi -
File write fails:
if ! touch "$CONFIG_FILE" 2>/dev/null; then echo "❌ Error: Cannot write to config file: $CONFIG_FILE" echo " Check file permissions" exit 1 fi -
Invalid path provided:
- Warn the user but allow proceeding
- Save the path anyway (user might create it later)
- Add to "invalid paths" list in summary
-
No repositories found:
- Strongly recommend /olm-team:dev-setup
- Offer to create template config file
- User can manually edit later
Return Value
- Format: Summary report with configuration status
The command outputs:
- Detection Results: Which repositories were found automatically
- Configuration Status: Success/warning/error for config file creation
- Validation Results: Which paths are valid/invalid
- Next Steps: Guidance for using the agent or cloning missing repositories
Examples
1. First-time configuration (some repos missing)
/olm-team:configure-agent
Output:
Repository Detection Results
=============================
✓ Found 6/9 repositories
✗ Missing 3 repositories
⚠️ RECOMMENDATION: Run /olm-team:dev-setup
Would you like to:
1. Run /olm-team:dev-setup now (Recommended)
2. Continue with partial configuration
3. Manually specify all paths
[User chooses option 1]
Please run: /olm-team:dev-setup
2. Configuration with all repos present
/olm-team:configure-agent
Output:
Repository Detection Results
=============================
✓ Found all 9 repositories
Creating configuration...
✓ Configuration saved: ~/.config/claude-code/olm-agent-config.json
✓ All paths validated successfully
The k8s-ocp-olm-expert agent is ready to use!
3. Update existing configuration
/olm-team:configure-agent
Output:
Existing configuration found at: ~/.config/claude-code/olm-agent-config.json
Current paths:
- openshift-docs: /Users/user/go/src/github.com/user/openshift-docs
...
Would you like to:
1. Update configuration (search for new paths)
2. Manually edit paths
3. Keep existing configuration
[User interaction follows]
Arguments
None. The command is interactive and will prompt for any needed information.
Notes
-
Automatic Repository Detection: The command searches common directories (
~/go/src/github.com,~/src,~/code) for OLM repositories. This works best if you follow standard directory conventions. -
Configuration Location: The configuration file is stored at
~/.config/claude-code/olm-agent-config.json. This location is standard for Claude Code user configurations. -
dev-setup Integration: This command is designed to work alongside
/olm-team:dev-setup. If you're missing repositories, dev-setup is the recommended approach as it handles forking, cloning, and configuration automatically. -
Partial Configuration: You can create a configuration with only some repositories. The agent will warn about missing repos when it needs them, but will still function for queries that only need the configured repos.
-
Path Validation: The command validates that paths exist and are git repositories, but doesn't verify they're the correct repositories. Make sure you're pointing to the actual OLM repositories, not other projects with similar names.
-
Manual Editing: You can always manually edit
~/.config/claude-code/olm-agent-config.jsonif you need to update paths later. Just ensure the JSON syntax remains valid. -
Multiple GitHub Accounts: If you have repositories from multiple GitHub accounts or organizations, you can configure paths to any of them. The agent doesn't care about git remotes, only that the code is present locally.
See Also
/olm-team:dev-setup- Automated repository setup and configurationplugins/olm-team/skills/k8s-ocp-olm-expert/README.md- Agent documentationplugins/olm-team/skills/k8s-ocp-olm-expert/config-example.json- Example configuration file
Name
olm-team:dev-setup
Synopsis
/olm-team:dev-setup [target-directory]
Description
The olm-team:dev-setup command automates the onboarding process for new OLM team members by setting up all necessary development repositories. It forks repositories (if not already forked), clones them locally with proper remote configuration, and provides educational context about each repository to accelerate team onboarding.
This command helps new developers understand the OLM ecosystem by explaining:
- The difference between upstream (operator-framework) and downstream (openshift) organizations
- The distinction between OLM v0 (traditional) and OLM v1 (next-generation) architectures
- The purpose and relationship of each repository in the development workflow
Implementation
Step 1: Validate Prerequisites
Check for required tools and authentication:
-
Verify GitHub CLI is installed:
which ghIf not installed, provide installation instructions for the user's platform.
-
Verify GitHub CLI authentication:
gh auth statusIf not authenticated, prompt user to run:
gh auth login -
Verify git is installed:
which git -
Get GitHub username:
gh api user --jq '.login'Store this for later use when determining fork URLs.
Step 2: Determine Target Directory
-
If target directory is provided as argument:
- Use the provided directory path
- Expand
~to home directory if present
-
If no target directory provided:
- Ask user for preferred location using AskUserQuestion tool
- Suggest common options:
~/go/src/github.com/(Go workspace convention)~/src/(Simple source directory)~/code/olm/(OLM-specific directory)
-
Create the selected directory if it does not exist
-
Verify directory is writable:
test -w <target-directory> && echo "writable" || echo "not writable"
Step 3: Display Repository Overview
Before starting the setup process, display an educational overview to help the user understand the OLM ecosystem:
OLM Development Repository Structure
=====================================
The OLM project is split between upstream (operator-framework) and downstream (openshift) organizations:
**Upstream (operator-framework)**: Community-driven development and releases
**Downstream (openshift)**: OpenShift-specific customizations and productization
OLM v0 Repositories (Traditional Architecture)
-----------------------------------------------
UPSTREAM:
• operator-framework/operator-registry
Purpose: Catalog and bundle management for operators
Description: Defines the format for storing operator metadata and provides
tools (opm) for building and querying operator catalogs
• operator-framework/operator-lifecycle-manager
Purpose: Core OLM v0 runtime and controllers
Description: Manages operator installation, upgrades, and lifecycle on Kubernetes.
Includes controllers for CSV, Subscription, InstallPlan, and OperatorGroup resources
• operator-framework/api
Purpose: API definitions and CRD schemas
Description: Defines the Kubernetes Custom Resource Definitions (CRDs) used by OLM,
including ClusterServiceVersion, Subscription, InstallPlan, CatalogSource, etc.
DOWNSTREAM:
• openshift/operator-framework-olm
Purpose: OpenShift distribution of OLM v0
Description: Downstream fork that includes OpenShift-specific patches, security
enhancements, and integration points. This is what ships in OpenShift products
• operator-framework/operator-marketplace
Purpose: OperatorHub integration
Description: Provides the OperatorHub UI integration and marketplace functionality
for discovering and installing operators in OpenShift
OLM v1 Repositories (Next-Generation Architecture)
---------------------------------------------------
UPSTREAM:
• operator-framework/operator-controller
Purpose: Core OLM v1 runtime
Description: New architecture using ClusterExtension and Catalog resources.
Simplified design with better dependency resolution and cluster extensions
DOWNSTREAM:
• openshift/operator-framework-operator-controller
Purpose: OpenShift distribution of OLM v1 operator-controller
Description: Downstream fork with OpenShift-specific modifications
• openshift/cluster-olm-operator
Purpose: OLM cluster operator for OpenShift
Description: Manages the installation and lifecycle of OLM itself on OpenShift clusters.
Handles upgrades and configuration of OLM components
Documentation Repository
-------------------------
• openshift/openshift-docs
Purpose: OpenShift product documentation
Description: Official OpenShift documentation repository. Contains documentation for all
OpenShift features including OLM, operators, and OperatorHub. Documentation team members contribute
documentation updates for OLM-related features and improvements and work closely with engineering team members to ensure accurate content.
Step 4: Run Repository Setup Script
Execute the automated repository setup script to fork, clone, and configure all OLM repositories:
bash plugins/olm-team/scripts/setup-repos.sh "$target_directory" "$github_username"
The script automates the following for each repository:
- Check if fork exists: Uses
gh repo viewto check for existing fork - Fork repository if needed: Creates fork using
gh repo forkif it doesn't exist - Clone repository: Clones the fork to
$target_directory/$github_username/$repo_name - Add upstream remote: Adds the original repository as "upstream" remote
- Fetch upstream: Fetches all upstream branches and tags
- Verify configuration: Displays remote configuration for verification
The script processes these repositories:
- OLM v0 Upstream: operator-registry, operator-lifecycle-manager, api
- OLM v0 Downstream: operator-framework-olm, operator-marketplace
- OLM v1 Upstream: operator-controller
- OLM v1 Downstream: operator-framework-operator-controller, cluster-olm-operator
- Documentation: openshift-docs
The script will:
- Skip forking if fork already exists
- Skip cloning if directory already exists
- Display status messages for each operation
- Provide a summary of successful and failed operations at the end
Step 5: Generate Summary Report
After processing all repositories, create a summary report:
-
Show repository locations: List all cloned repositories with their paths
-
Provide next steps:
Next Steps for OLM Development =============================== 1. Verify your setup: cd ~/go/src/github.com/<username>/operator-lifecycle-manager git remote -v 2. Keep your fork in sync with upstream: git fetch upstream git checkout main # or master, depending on the repo's default branch git merge upstream/HEAD git push origin HEAD 3. Create a feature branch for development: git checkout -b feature/my-feature 4. Build and test (example for operator-lifecycle-manager): make build make test 5. Useful resources: - OLM Documentation: https://olm.operatorframework.io/ - OpenShift OLM Docs: https://docs.openshift.com/container-platform/latest/operators/ - Confluence On-boarding Guide: https://spaces.redhat.com/pages/viewpage.action?pageId=467060465&spaceKey=OOLM&title=Onboarding - How We Work Team Process Guide: https://spaces.redhat.com/spaces/OOLM/pages/467060455/_How+We+Work - Contributing Guide: Check CONTRIBUTING.md in each repository -
Display repository reference table: Create a quick reference table showing:
- Repository name
- Local path
- Type (Upstream/Downstream)
- Version (OLM v0/v1)
- Purpose
Step 6: Error Handling
Handle common issues:
-
Fork creation fails:
- Check if user has permission to fork
- Verify repository exists and is accessible
- Provide manual fork instructions if needed
-
Clone fails:
- Check SSH key configuration:
ssh -T git@github.com - Suggest HTTPS alternative if SSH fails
- Check disk space
- Check SSH key configuration:
-
Remote configuration fails:
- Verify remote URL format
- Check network connectivity
- Provide manual remote add instructions
-
Directory permission issues:
- Check directory is writable
- Suggest alternative locations
- Provide instructions for fixing permissions
Return Value
- Format: Summary report with repository status
The command outputs a structured report containing:
- Repository Setup Status: Success/failure for each repository operation
- Location Mapping: Table showing repository paths and remote configurations
- Educational Context: Explanation of each repository's role in the OLM ecosystem
- Next Steps: Guidance for beginning development work
- Error Messages: Detailed error information for any failures
Examples
1. Basic usage with default directory prompt
/olm-team:dev-setup
The command will:
- Prompt for target directory selection
- Fork all OLM repositories (if not already forked)
- Clone repositories to chosen location
- Configure origin/upstream remotes
- Display educational overview and next steps
2. Specify target directory
/olm-team:dev-setup ~/go/src/github.com/
Clones all repositories to ~/go/src/github.com/<username>/ directory structure.
3. Use Go workspace convention
/olm-team:dev-setup ~/go/src/github.com/
Creates standard Go workspace layout:
~/go/src/github.com/
<username>/
operator-registry/
operator-lifecycle-manager/
api/
operator-framework-olm/
operator-marketplace/
operator-controller/
operator-framework-operator-controller/
cluster-olm-operator/
openshift-docs/
Arguments
target-directory(optional): Base directory where repositories will be cloned- If not provided, user will be prompted to choose or enter a custom path
- Common choices:
~/go/src/github.com/,~/src/,~/code/olm/ - Will be created if it doesn't exist
- Repositories will be cloned to:
<target-directory>/<github-username>/<repo-name>/
Notes
-
Fork vs Clone Strategy: The command uses the fork URL as "origin" and adds the original repository as "upstream". This follows the standard open-source contribution workflow where you push to your fork and create pull requests to upstream.
-
Directory Structure: Repositories are organized by username to support working with multiple GitHub accounts or collaborating with others who have different forks.
-
SSH vs HTTPS: The command uses SSH URLs (
git@github.com:) for git operations. Ensure your SSH keys are configured with GitHub. If SSH is not available, the command will guide you through HTTPS setup. -
Selective Setup: If you only need specific repositories, you can manually run the commands for individual repos after understanding the process from the overview.
-
Keeping Forks Updated: The command sets up remotes but doesn't automatically sync forks. Use the provided git commands in the summary to keep your forks up to date with upstream.
-
Build Requirements: Each repository may have specific build requirements (Go version, dependencies, etc.). Check each repository's README.md for detailed build instructions.
Name
olm-team:ep-watch
Synopsis
/olm-team:ep-watch
Description
The olm-team:ep-watch command watches open Enhancement Proposal PRs in the openshift/enhancements repository that are not created by the OLM team but may have impacts on OLM work. This helps the OLM team maintain visibility into what other teams are designing that could affect operator lifecycle management.
The command:
- Fetches open PRs from openshift/enhancements repository
- Filters out PRs created by known OLM team members
- Analyzes PR content for OLM-related topics
- Returns up to 3 most relevant PRs with impact assessment
This is useful for:
- Discovering cross-team dependencies early
- Identifying potential impacts on OLM architecture
- Participating in relevant enhancement discussions
- Staying informed about OpenShift-wide changes affecting operators
Implementation
Step 1: Define OLM-Related Topics
Create a list of topics that could impact OLM:
High Priority Topics (Weight: 10): OLMv1-specific terms that indicate direct relevance:
- olmv1, olm v1
- operator-controller
- catalogd
- rukpak
- ClusterExtension
- boxcutter
Medium Priority Topics (Weight: 5): OLM-specific but broader terms:
- olmv0, olm v0
- operator lifecycle manager, operator-lifecycle-manager
- operator lifecycle
- operator framework
- operator bundle
- operator catalog
- operator registry
- operator hub, operatorhub
Low Priority Topics (Weight: 3): Related terms that must appear in specific context:
- subscription (with "operator")
- csv (with "operator")
- installplan
- catalogsource
Excluded Generic Terms: To reduce false positives, the following generic terms are NOT searched:
- "operator" alone (too broad - matches any operator)
- "marketplace" alone (matches unrelated marketplace mentions)
- "CRD" alone (too generic)
- "webhook" alone (too generic)
Step 2: Identify OLM Team Members
Define list of known OLM team members (GitHub usernames):
OLM_TEAM_MEMBERS = [
"grokspawn",
"joelanford",
"perdasilva",
"tmshort",
"oceanc80",
"dtfranz",
"anik120",
"rashmigottipati",
"pedjak",
"ankitathomas",
"trgeiger",
# Add current OLM team members as needed
]
Step 3: Fetch Open Enhancement PRs
Use GitHub API to get open PRs:
# Fetch open PRs from openshift/enhancements
curl -s \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/openshift/enhancements/pulls?state=open&per_page=100" \
> /tmp/enhancement-prs.json
Step 4: Filter and Score PRs
For each open PR:
-
Filter out OLM team PRs
- Check if PR author is in OLM_TEAM_MEMBERS list
- Skip if created by OLM team
-
Score relevance
- Fetch PR title, body, and changed files
- Count mentions of OLM-related topics
- Higher score = more topic matches
- Bonus points for:
- Multiple topic matches
- Topics in PR title (weighted higher)
- Topics in summary section
- Changes to operator-related directories
-
Extract key information
- PR number and title
- Author
- Created date
- Files changed
- Matched topics (why it's relevant)
- Link to PR
Step 5: Rank and Return Top 3
Sort PRs by relevance score and return top 3.
Step 6: Format Results
🔍 Found X open Enhancement PRs from other teams that may impact OLM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 PR #XXXX: [Title]
👤 Author: @username (Team: [team-name if identifiable])
📅 Opened: X days ago
🎯 Relevance: [HIGH/MEDIUM]
**Why this matters to OLM:**
- Mentions: [list of matched topics]
- Potential impacts: [brief analysis]
**Files changed:**
- enhancements/[area]/[filename].md
🔗 https://github.com/openshift/enhancements/pull/XXXX
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 7: Provide Actionable Recommendations
For each PR, suggest:
- Whether OLM should review/comment
- Potential action items
- Team members who might be interested
Return Value
- Text output: Up to 3 open Enhancement PRs with impact analysis
- Links: Direct URLs to each PR
- Recommendations: Suggested actions for OLM team
Examples
-
Basic usage:
/olm-team:ep-watchExample output:
🔍 Found 12 open Enhancement PRs from other teams, showing top 3 relevant to OLM ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 PR #1234: Add support for operator webhooks in hypershift 👤 Author: @other-team-member (HyperShift Team) 📅 Opened: 5 days ago 🎯 Relevance: HIGH **Why this matters to OLM:** - Mentions: ClusterExtension, operator lifecycle, catalogd - Potential impacts: Changes how operator webhooks work in hosted control planes Could affect OLMv1 webhook support in HyperShift clusters **Files changed:** - enhancements/hypershift/operator-webhooks.md 🔗 https://github.com/openshift/enhancements/pull/1234 **Recommended action:** Review and comment on webhook integration approach ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Implementation Details
GitHub API Authentication
Requires GITHUB_TOKEN for higher rate limits:
# Check for token
if [ -z "$GITHUB_TOKEN" ]; then
echo "⚠️ Warning: GITHUB_TOKEN not set. API rate limits will be restrictive."
echo "Set with: export GITHUB_TOKEN=your_token"
fi
Scoring Algorithm
The scoring algorithm uses weighted keywords to prioritize OLMv1-specific content:
def score_pr_relevance(pr_data, weighted_topics):
score = 0
# Each topic has a weight (10=high, 5=medium, 3=low)
for topic, weight in weighted_topics.items():
topic_lower = topic.lower()
# Title matches get 3x multiplier
if topic_lower in pr_data['title'].lower():
score += (weight * 3)
# Body matches get 1x weight
elif topic_lower in pr_data['body'].lower():
score += weight
return score
# Relevance levels:
# HIGH: score >= 30 (e.g., "olmv1" or "catalogd" in title)
# MEDIUM: score >= 10
# LOW: score < 10
# Minimum threshold: 5 (PRs with score < 5 are filtered out)
Example Scoring:
- PR title contains "olmv1": 10 * 3 = 30 points (HIGH)
- PR title contains "operator-controller": 10 * 3 = 30 points (HIGH)
- PR body mentions "catalogd": 10 points (MEDIUM)
- PR body mentions "operator bundle": 5 points (MEDIUM)
- PR with generic "marketplace" only: 0 points (excluded)
Caching
To avoid rate limits, cache results:
CACHE_FILE="/tmp/olm-ep-watch-cache.json"
CACHE_TTL=3600 # 1 hour
if [ -f "$CACHE_FILE" ]; then
# Portable stat command for macOS and Linux
if stat -f %m "$CACHE_FILE" >/dev/null 2>&1; then
# macOS/BSD
file_time=$(stat -f %m "$CACHE_FILE")
else
# Linux
file_time=$(stat -c %Y "$CACHE_FILE")
fi
age=$(($(date +%s) - file_time))
if [ $age -lt $CACHE_TTL ]; then
echo "Using cached results (${age}s old)"
cat "$CACHE_FILE"
exit 0
fi
fi
Error Handling
# Handle API failures
if ! response=$(curl -s -w "\n%{http_code}" "$api_url"); then
echo "❌ Failed to fetch PRs from GitHub API"
exit 1
fi
http_code=$(echo "$response" | tail -n1)
if [ "$http_code" != "200" ]; then
echo "❌ GitHub API returned status $http_code"
if [ "$http_code" = "403" ]; then
echo "Rate limit exceeded. Try again later or set GITHUB_TOKEN"
fi
exit 1
fi
Arguments
- None - The command runs without arguments and fetches all relevant open PRs
Prerequisites
-
GitHub CLI (optional but recommended)
- Check:
which gh - Install: https://cli.github.com/
- Alternative: Use curl with GitHub API
- Check:
-
GITHUB_TOKEN (recommended)
- Set:
export GITHUB_TOKEN=your_token - Without token: Limited to 60 API requests/hour
- With token: 5000 API requests/hour
- Create at: https://github.com/settings/tokens
- Set:
-
jq (for JSON parsing)
- Check:
which jq - Install:
brew install jq(macOS) orapt install jq(Linux)
- Check:
-
Internet access
- Required to access GitHub API
Notes
- The command focuses on open PRs (not merged or closed)
- PRs are refreshed each run (with caching to avoid rate limits)
- The OLM team member list should be kept up-to-date
- Topic list can be expanded based on team feedback
- Results are ranked by relevance, not recency
- Consider running this weekly during team meetings
Future Enhancements
The following features could be added in future versions:
Custom Topic Filtering
Allow searching for specific topics:
/olm-team:ep-watch webhooks catalog
Adjust Result Limit
Return more or fewer results:
/olm-team:ep-watch --limit 5
Include OLM Team PRs
See ALL relevant PRs (including OLM team):
/olm-team:ep-watch --include-team
Additional Future Enhancements
- Auto-post weekly summary to Slack
- Subscribe to specific topics
- Email notifications for high-relevance PRs
- Integration with team calendar for review sessions
- Track PRs over time to see new vs. previously flagged
See Also
- OpenShift Enhancements Repository
- Enhancement Proposal Process
- GitHub CLI:
gh pr list /olm-team:ep-search- Search existing Enhancement Proposals
Sponsors
Details
- Marketplace
- openshift-eng/ai-helpers
- Source
- plugins/olm-team
- Category
- Development
- Keywords
- olm, onboarding, team-tools
More from openshift-eng/ai-helpers
All 56- openshiftv0.0.8
- openshift-developerv1.1.42
- openshift-tls-profilev0.0.2
- operator-dashboardv0.0.1
- originv0.0.2
- ote-migrationv0.0.3
- patternfly
- prodsec-skillsv1.0.0
- prow-agentv0.0.7
- rds-analyzerv0.0.2
- sessionv0.0.2
- snowflakev0.5.1
- sosreportv0.0.2
- teamsv0.0.18
- test-coveragev0.0.2
- testingv0.1.0
- utilsv0.0.13
- workspacesv1.0.1
- yamlv0.0.2
- agendasv0.0.3
- agentic-docsv2.2.12
- ai-sbomv0.0.1
- bigqueryv0.0.2
- bigquery-ci-datav0.0.3