OLM team development utilities and onboarding tools

version
0.2.1
GitHub stars
123

Install

/plugin install olm-team@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 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 repository
  • OLM_V0_UPSTREAM_OLM - Path to operator-lifecycle-manager
  • OLM_V0_UPSTREAM_REGISTRY - Path to operator-registry
  • OLM_V0_UPSTREAM_API - Path to operator-framework/api
  • OLM_V0_DOWNSTREAM_OLM - Path to operator-framework-olm
  • OLM_V0_DOWNSTREAM_MARKETPLACE - Path to operator-marketplace
  • OLM_V1_UPSTREAM_CONTROLLER - Path to operator-controller
  • OLM_V1_DOWNSTREAM_CONTROLLER - Path to operator-framework-operator-controller
  • OLM_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)

OCP Layered Products

  • Layered products are operators that ship in the default catalogs in OCP
Layered Product Lifecycle Categories

(From https://docs.google.com/presentation/d/1GD29PRJwYckO6zw73fw3eVUu1hmsdMYhNuKxx4uX7SM/edit?slide=id.g1ccea862d8c_46_0#slide=id.g1ccea862d8c_46_0)

Tier 1 - Platform AlignedTier 2 - Platform AgnosticTier 3 - Rolling Stream
Release strategyMultiple minor versions supported in parallelMultiple minor versions supported in parallelA single rolling release (minor or major)
VersioningSemantic versioningSemantic versioningSemantic versioning
OCP coverageDifferent 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 lengthFor 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 OCPDetermined by the release cadence
EUS-to-EUSFor each EUS-to-EUS upgrade path the layered product offers an update path or supports both EUS releases in one product versionFor each EUS-to-EUS upgrade path the layered product offers an update path or supports both EUS releases in one product versionDoes not support EUS-to-EUS upgrades
Release cadenceThe aligned release within 1 month after OCP minor release GA, further releases are independent of OCP datesReleases independently of OCP minor releasesReleases independently of OCP minor releases
Release deliveryOLM channels are named 'stable', optionally 'fast' and 'candidate' for the aligned version, optionally one OLM release channels per minor-version of your productOne OLM release channels per minor-version and a 'stable' channel containing the preferred minor version for each OCP versionOLM 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

  1. 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
  2. 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
  3. 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:
    1. Use Grep with multiple search patterns to find relevant files in ${OPENSHIFT_DOCS}
    2. Read the most promising files to verify relevance and extract specific content
    3. Note line numbers where key information appears
  • 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
  • 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
  1. 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
  2. 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)
  3. 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:

  1. Start with a clear, concise, direct answer to the question or solution to the problem
  2. Provide context and concise explanation for your recommendation
  3. Include concrete examples (YAML snippets, commands, etc.)
  4. Include references to relevant OpenShift documentation files from ${OPENSHIFT_DOCS} with specific file paths and line numbers
  5. Highlight any important caveats or considerations
  6. Suggest verification steps or testing approaches
  7. 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:

  1. 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
  2. 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
  3. 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:

  1. Inform the user immediately
  2. 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
    
  3. 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:

  1. Expand ~ to home directory
  2. Verify the path exists and is a directory
  3. Check if it's a git repository (has .git directory)
  4. 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:

  1. 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
    
  2. 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
    
  3. 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
  4. 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:

  1. Detection Results: Which repositories were found automatically
  2. Configuration Status: Success/warning/error for config file creation
  3. Validation Results: Which paths are valid/invalid
  4. 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

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

  2. Configuration Location: The configuration file is stored at ~/.config/claude-code/olm-agent-config.json. This location is standard for Claude Code user configurations.

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

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

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

  6. Manual Editing: You can always manually edit ~/.config/claude-code/olm-agent-config.json if you need to update paths later. Just ensure the JSON syntax remains valid.

  7. 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 configuration
  • plugins/olm-team/skills/k8s-ocp-olm-expert/README.md - Agent documentation
  • plugins/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:

  1. Verify GitHub CLI is installed:

    which gh
    

    If not installed, provide installation instructions for the user's platform.

  2. Verify GitHub CLI authentication:

    gh auth status
    

    If not authenticated, prompt user to run:

    gh auth login
    
  3. Verify git is installed:

    which git
    
  4. Get GitHub username:

    gh api user --jq '.login'
    

    Store this for later use when determining fork URLs.

Step 2: Determine Target Directory

  1. If target directory is provided as argument:

    • Use the provided directory path
    • Expand ~ to home directory if present
  2. 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)
  3. Create the selected directory if it does not exist

  4. 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:

  1. Check if fork exists: Uses gh repo view to check for existing fork
  2. Fork repository if needed: Creates fork using gh repo fork if it doesn't exist
  3. Clone repository: Clones the fork to $target_directory/$github_username/$repo_name
  4. Add upstream remote: Adds the original repository as "upstream" remote
  5. Fetch upstream: Fetches all upstream branches and tags
  6. 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:

  1. Show repository locations: List all cloned repositories with their paths

  2. 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
    
  3. 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:

  1. Fork creation fails:

    • Check if user has permission to fork
    • Verify repository exists and is accessible
    • Provide manual fork instructions if needed
  2. Clone fails:

    • Check SSH key configuration:
      ssh -T git@github.com
      
    • Suggest HTTPS alternative if SSH fails
    • Check disk space
  3. Remote configuration fails:

    • Verify remote URL format
    • Check network connectivity
    • Provide manual remote add instructions
  4. 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:

  1. Repository Setup Status: Success/failure for each repository operation
  2. Location Mapping: Table showing repository paths and remote configurations
  3. Educational Context: Explanation of each repository's role in the OLM ecosystem
  4. Next Steps: Guidance for beginning development work
  5. 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

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

  2. Directory Structure: Repositories are organized by username to support working with multiple GitHub accounts or collaborating with others who have different forks.

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

  4. Selective Setup: If you only need specific repositories, you can manually run the commands for individual repos after understanding the process from the overview.

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

  6. 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:

  1. Filter out OLM team PRs

    • Check if PR author is in OLM_TEAM_MEMBERS list
    • Skip if created by OLM team
  2. 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
  3. 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

  1. Basic usage:

    /olm-team:ep-watch
    

    Example 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

  1. GitHub CLI (optional but recommended)

  2. GITHUB_TOKEN (recommended)

  3. jq (for JSON parsing)

    • Check: which jq
    • Install: brew install jq (macOS) or apt install jq (Linux)
  4. 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

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