Add a new 'operator' slash command to kubectl-operator to allow users to interact with kubectl-operator

.claude/commands/README.md

@@ -0,0 +1,125 @@
+# kubectl-operator Claude Code Slash Commands
+
+This directory contains slash commands that give Claude Code awareness of the kubectl-operator plugin.
+
+## Available Commands
+
+### `/operator`
+**General help with kubectl operator plugin**
+
+Use this for general questions about kubectl operator commands, workflows, and best practices.
+
+**Example usage:**
+```
+/operator
+How do I install the prometheus operator?
+```
+
+```
+/operator
+What's the difference between OLMv0 and OLMv1 commands?
+```
+
+### `/operator-install`
+**Install a Kubernetes operator**
+
+Focused helper for installing operators using `kubectl operator olmv1 install extension`.
+
+**Example usage:**
+```
+/operator-install
+I want to install the prometheus operator
+```
+
+```
+/operator-install
+Install cert-manager in the cert-manager namespace
+```
+
+### `/operator-catalog`
+**Manage operator catalogs**
+
+Helper for creating, listing, updating, and deleting ClusterCatalogs.
+
+**Example usage:**
+```
+/operator-catalog
+Create a catalog from quay.io/operatorhubio/catalog:latest
+```
+
+```
+/operator-catalog
+How do I check if my catalog is serving?
+```
+
+### `/operator-debug`
+**Troubleshoot kubectl operator issues**
+
+Debug helper that matches error messages to documented scenarios and provides fixes.
+
+**Example usage:**
+```
+/operator-debug
+I got error: "no bundles found for package prometheus-operator"
+```
+
+```
+/operator-debug
+My extension shows INSTALLED: False. How do I debug?
+```
+
+## How These Work
+
+Each slash command is a Markdown file that:
+1. Loads context about kubectl-operator
+2. References `olmv1.md` for accurate, up-to-date documentation
+3. Follows documented workflows and error scenarios
+4. Provides step-by-step guidance with verification
+
+## Knowledge Base
+
+All commands reference `olmv1.md` which contains:
+- Complete command syntax and flags
+- Prerequisites for each operation
+- Success verification steps
+- Common error scenarios and fixes
+- Recommended workflows
+- Example outputs (YAML, JSON, table formats)
+
+## Customization
+
+You can edit any of these `.md` files to customize the behavior. The format is:
+
+```markdown
+---
+description: Short description for the command list
+---
+
+Instructions for Claude Code...
+```
+
+## Adding New Commands
+
+Create a new `.md` file in this directory with your command name:
+
+```bash
+.claude/commands/my-command.md
+```
+
+Then use it in Claude Code:
+```
+/my-command
+```
+
+## No MCP Server Required
+
+These slash commands work without an MCP server - they're just Markdown files that expand into prompts. This makes them:
+- Easy to version control
+- Simple to edit
+- Fast to load
+- No dependencies to manage
+
+## Documentation
+
+For more on Claude Code slash commands, see:
+https://docs.claude.com/en/docs/claude-code/custom-commands

.claude/commands/operator-catalog.md

@@ -0,0 +1,40 @@
+---
+description: Manage operator catalogs using kubectl operator olmv1
+---
+
+Help the user manage ClusterCatalogs using kubectl operator olmv1 catalog commands.
+
+## Instructions
+
+1. **Read the create catalog section from olmv1.md** (around line 61-258)
+2. **Follow the catalog workflow** from "Recommended Workflows" (around line 1240-1258)
+3. **Ask the user what they want to do**:
+   - Create a new catalog
+   - List existing catalogs
+   - Update a catalog
+   - Delete a catalog
+   - Search a catalog for packages
+
+4. **For catalog creation, provide the complete workflow**:
+   ```bash
+   # Step 1: Verify catalog doesn't exist
+   kubectl operator olmv1 get catalog <catalog-name>
+
+   # Step 2: Create catalog
+   kubectl operator olmv1 create catalog <catalog-name> <image>
+
+   # Step 3: Poll for serving status
+   kubectl operator olmv1 get catalog <catalog-name>
+
+   # Step 4: Verify packages available
+   kubectl operator olmv1 search catalog --catalog <catalog-name>
+   ```
+
+5. **Include**:
+   - Prerequisites (image accessibility, valid FBC)
+   - Expected success message: `catalog "<name>" created`
+   - Polling guidance (wait for SERVING: True)
+   - How to check conditions with yq if catalog fails to serve
+   - Common errors and fixes from the docs
+
+Now help the user with their catalog operation.

.claude/commands/operator-debug.md

@@ -0,0 +1,52 @@
+---
+description: Troubleshoot kubectl operator issues
+---
+
+Help the user debug and troubleshoot kubectl operator issues.
+
+## Instructions
+
+1. **Read olmv1.md** to understand all documented error scenarios
+2. **Ask the user to provide**:
+   - The command they ran
+   - The error message they received
+   - Output of relevant `get` commands
+
+3. **Follow this diagnostic process**:
+
+   **For extension installation failures**:
+   ```bash
+   # Check extension status
+   kubectl operator olmv1 get extension <name>
+
+   # Check detailed conditions
+   kubectl operator olmv1 get extension <name> -o yaml | yq eval '.status.conditions'
+
+   # Check catalogs are serving
+   kubectl operator olmv1 get catalog
+
+   # Search for the package
+   kubectl operator olmv1 search catalog --package <package-name>
+   ```
+
+   **For catalog creation failures**:
+   ```bash
+   # Check catalog status
+   kubectl operator olmv1 get catalog <name>
+
+   # Check detailed conditions
+   kubectl operator olmv1 get catalog <name> -o yaml | yq eval '.status.conditions[] | select(.type=="Progressing")'
+   ```
+
+4. **Match error messages to documented scenarios**:
+   - Read the "Common errors" sections in olmv1.md
+   - For install extension errors: see lines ~380-420
+   - For create catalog errors: see lines ~237-255
+
+5. **Provide**:
+   - Root cause analysis
+   - Specific fix from the documentation
+   - Verification commands
+   - Prevention tips
+
+Now help the user debug their issue.

.claude/commands/operator-install.md

@@ -0,0 +1,38 @@
+---
+description: Install a Kubernetes operator using kubectl operator olmv1
+---
+
+Help the user install a Kubernetes operator using the kubectl operator olmv1 install extension command.
+
+## Instructions
+
+1. **Read the install extension section from olmv1.md** (around line 274-420)
+2. **Follow the documented workflow** from the "Recommended Workflows" section (around line 1260-1287)
+3. **Ask the user for required information if not provided**:
+   - Package name (use search if they don't know it)
+   - Namespace to install into
+   - ServiceAccount name (default: "default")
+
+4. **Provide the complete workflow**:
+   ```bash
+   # Step 1: Search for the package
+   kubectl operator olmv1 search catalog --package <package-name>
+
+   # Step 2: Verify catalogs are serving
+   kubectl operator olmv1 get catalog
+
+   # Step 3: Install the extension
+   kubectl operator olmv1 install extension <name> -n <namespace> -p <package-name>
+
+   # Step 4: Verify installation
+   kubectl operator olmv1 get extension <name>
+   ```
+
+5. **Include**:
+   - Prerequisites from the docs
+   - Expected outputs at each step
+   - How to verify success (INSTALLED: True)
+   - Common errors and how to fix them
+   - Polling guidance (wait for INSTALLED: True)
+
+Now help the user install their operator.

.claude/commands/operator.md

@@ -0,0 +1,69 @@
+---
+description: Help with kubectl operator plugin commands and workflows
+---
+
+You are an expert assistant for the kubectl-operator plugin, which manages Kubernetes operators via OLM (Operator Lifecycle Manager).
+
+## Your Knowledge Base
+
+You have access to comprehensive documentation in `olmv1.md` which covers all olmv1 commands. When the user asks about kubectl operator commands:
+
+1. **Always read olmv1.md first** to get accurate, up-to-date command syntax and examples
+2. **Use the documented workflows** in the "Recommended Workflows" section
+3. **Reference specific error scenarios** from the documentation when troubleshooting
+
+## Initial setup
+Before helping the user, ensure that the `kubectl-operator` plugin is installed and has the `olmv1` subcommand. This can be verified by running `kubectl operator olmv1`, which should not fail.
+If this fails with an `unknown command` error, ensure that kubectl-operator is installed correctly following the steps in the `Installing from source` section on the `README.md` at the root level of the `kubectl-operator` repository.
+
+## Available Commands
+
+The kubectl operator plugin has two main command sets:
+
+### OLMv0 Commands (Legacy)
+- `kubectl operator install <package>` - Install an operator (OLMv0)
+- `kubectl operator uninstall <package>` - Uninstall an operator
+- `kubectl operator list` - List installed operators
+- `kubectl operator list-available` - List available operators
+- `kubectl operator catalog add/remove/list` - Manage catalogs
+
+### OLMv1 Commands (Modern)
+Read `olmv1.md` for complete documentation. Main commands:
+- `kubectl operator olmv1 create catalog` - Create a ClusterCatalog
+- `kubectl operator olmv1 install extension` - Install a ClusterExtension
+- `kubectl operator olmv1 delete catalog|extension` - Delete resources
+- `kubectl operator olmv1 update catalog|extension` - Update resources
+- `kubectl operator olmv1 get catalog|extension` - View resources
+- `kubectl operator olmv1 search catalog` - Search for packages
+
+## How to Help
+
+1. **For command help**: Read `olmv1.md` and provide the exact syntax with examples
+2. **For workflows**: Use the "Recommended Workflows" section from `olmv1.md`
+3. **For errors**: Match error messages to the "Common errors" sections and provide the documented fixes
+4. **For installation**: Follow the complete workflow: search → verify catalogs → install → verify
+5. **For catalog creation**: Include prerequisites, success verification, and polling guidance
+
+## Important Guidelines
+
+- **Always verify prerequisites** before suggesting commands
+- **Provide expected outputs** so the user knows what success looks like
+- **Include verification commands** after operations
+- **Reference specific line numbers** from olmv1.md when citing documentation
+- **Use the documented error scenarios** for troubleshooting
+- **Follow the workflows** in olmv1.md for multi-step operations
+
+## Example Interaction Pattern
+
+User: "How do I install the prometheus operator?"
+
+Your response should:
+1. Read `olmv1.md` to get current install extension syntax
+2. Provide the complete workflow:
+   - Search for the package first
+   - Verify catalogs are serving
+   - Show the install command with all required flags
+   - Explain how to verify installation
+   - Include common errors and fixes
+
+Now, how can I help you with kubectl operator?

README.md

@@ -19,3 +19,49 @@ The `kubectl operator` plugin is distributed via [`krew`](https://krew.sigs.k8s.
 ```console
 kubectl krew install operator
 ```
+
+# Installing from source
+
+Prerequisites:
+- [go 1.23.4+](https://go.dev/dl/)
+- `GOPATH` environment variable must be set.
+
+To build the latest version from the repository, run `make install`. This should install the kubectl-operator plugin to the `$GOPATH`/bin directory. 
+
+To enable `kubectl` to discover the plugin, ensure that the '$GOPATH'/bin directory is either part of the '$PATH' environment variable, or that the newly installed `kubectl-operator` is moved to a directory in the `$PATH`.
+
+You should see that the plugin has successfully installed:
+```bash
+$ kubectl operator
+
+Manage operators in a cluster from the command line.
+
+kubectl operator helps you manage operator installations in your
+cluster. It can install and uninstall operator catalogs, list
+operators available for installation, and install and uninstall
+operators from the installed catalogs.
+
+Usage:
+  operator [command]
+
+Available Commands:
+  catalog        Manage operator catalogs
+  completion     Generate the autocompletion script for the specified shell
+  describe       Describe an operator
+  help           Help about any command
+  install        Install an operator
+  list           List installed operators
+  list-available List operators available to be installed
+  list-operands  List operands of an installed operator
+  olmv1          Manage OLMv1 extensions and catalogs
+  uninstall      Uninstall an operator and operands
+  upgrade        Upgrade an operator
+  version        Print version information
+
+Flags:
+  -h, --help               help for operator
+  -n, --namespace string   If present, namespace scope for this CLI request
+      --timeout duration   The amount of time to wait before giving up on an operation. (default 1m0s)
+
+Use "operator [command] --help" for more information about a command.
+```