/agnosticv:catalog-builder

🔧 Catalog Builder

Create or update AgnosticV catalog files for RHDP deployments (unified skill).

What You’ll Need Before Starting

Click to view full workflow diagram

Prerequisites

📁

Clone AgnosticV Repository

cd ~/work/code
git clone git@github.com:rhpds/agnosticv.git
cd agnosticv

🔐

Verify RHDP Access

Write access to AgnosticV repository
Test: gh repo view rhpds/agnosticv
Ability to create pull requests

📝

Workshop Content Ready

Workshop lab content (from /showroom:create-lab)
Infrastructure requirements (CNV, AWS, etc.)
Workload list (OpenShift AI, AAP, etc.)

What You’ll Need (By Mode)

Mode 1: Full Catalog

Catalog name (e.g., "Agentic AI on OpenShift")
Category (Workshops, Demos, or Sandboxes)
Infrastructure type: OCP cluster / RHEL+AAP VMs / Sandbox API CI
For Sandbox API CI: Cluster CI (provision shared cluster) or Tenant CI (deploy on pre-configured cluster)
Workloads to deploy
Multi-user requirements (yes/no)

Mode 2: Description Only

Path to Showroom repository
Brief overview (2-3 sentences starting with product name)

Mode 3: Info Template

Data keys from agnosticd_user_info.data

Mode 4: Virtual CI (published/)

Base component path (e.g. openshift_cnv/kafka-developer-workshop-cnv)
Handles uniqueness check, UUID, dev restriction, prod.yaml version pinning
Supports bulk processing of multiple base components

Quick Start

Navigate to Repository
Open your AgnosticV repository directory
Run Catalog Builder
/agnosticv:catalog-builder
Choose Mode
Select: Full Catalog / Description Only / Info Template
Answer Questions
Follow guided prompts
Review & Commit
Files auto-committed to new branch

What It Can Generate

Mode 1: Full Catalog

Creates complete catalog with all files:

agd_v2/your-catalog-name/
├── common.yaml
├── dev.yaml
├── description.adoc
└── info-message-template.adoc

Mode 2: Description Only

Updates just the description:

agd_v2/your-catalog-name/
└── description.adoc

Mode 3: Info Template

Creates user notification:

agd_v2/your-catalog-name/
└── info-message-template.adoc

Common Workflows

Workflow 1: Create Full Catalog from Scratch

/agnosticv:catalog-builder
→ Mode: 1 (Full Catalog)
→ Step 0: AgV path auto-detected, branch created
→ Step 1: Q1=type (Workshop/Demo/Sandbox), Q2=event?, Q3=tech
→ Step 2: Discovery searches agd_v2/ + openshift_cnv/
→ Step 3: Infrastructure gate (OCP cluster / RHEL+AAP VMs / Sandbox API CI)
→ Step 4: Auth (unified ocp4_workload_authentication)
→ Step 5: Workloads + LiteMaaS
→ Step 6: Showroom (recommended name shown)
→ Step 7: Catalog details (name, description, maintainer)
→ Step 9: __meta__, includes, event restrictions
→ Step 10: Path auto-generated (event) or asked (no-event)
→ Generate all 4 files, auto-commit to branch

Workflow 2: Update Description After Content Changes

/agnosticv:catalog-builder
→ Mode: 2 (Description Only)
→ Point to Showroom repo
→ Auto-extracts modules and technologies
→ Generates description.adoc
→ Auto-commits to branch

Workflow 3: Add Info Template for User Data

/agnosticv:catalog-builder
→ Mode: 3 (Info Template)
→ Specify data keys from workload
→ Generates template with placeholders
→ Shows how to use agnosticd_user_info

Mode Details

Mode 1: Full Catalog - Detailed Workflow

What it creates:

common.yaml - Main configuration (infrastructure, auth, workloads, includes)
dev.yaml - Development environment overrides
description.adoc - UI description following RHDP structure
info-message-template.adoc - User notification template

Step-by-step process:

Step 0 — Setup: AgV path auto-detected; branch created from main (no feature/ prefix)
Step 1 — Context: 3 questions: Q1=Workshop/Demo/Sandbox, Q2=Is this for an event? (Summit 2026 / RH One 2026 / Other), Q3=Technologies. Event selection overrides category to Brand_Events and asks for Lab ID.
Step 2 — Discovery: Searches agd_v2/ and openshift_cnv/; shows reference catalogs with [OCP cluster] or [RHEL/AAP VMs] labels
Step 3 — Infrastructure gate: Three options — OCP cluster, RHEL/AAP VMs, or Sandbox API CI. Routes to a separate @reference file per type:
- OCP path (ocp-catalog-questions.md): SNO or multinode, OCP version (4.18/4.20/4.21), pool with /prod suffix, autoscale, AWS gate; auth (unified ocp4_workload_authentication + provider); OCP workloads + LiteMaaS; Showroom with ocp4_workload_ocp_console_embed; multi-user with worker scaling
- VM path (cloud-vms-base-catalog-questions.md): CNV or AWS, RHEL image, sizing, ports; auth skipped (OS-level only); VM workloads; vm_workload_showroom with showroom_git_repo/showroom_git_ref; multi-user isolation warning
- Sandbox API CI path: Choose Cluster CI or Tenant CI:
  - Cluster CI (sandbox-cluster-ci-questions.md): Provisions a shared OCP cluster for N tenant placements. Pool type (CNV/AWS), OCP version, lab label (tenants target by this), worker sizing. Auto-sets config: openshift-workloads, cloud_provider: none, num_users: 0, required includes (sandbox-api.yaml, access-restriction-admins-only.yaml), full propagate_provision_data.
  - Tenant CI (sandbox-tenant-ci-questions.md): Deploys per-user workloads on a pre-configured cluster via __meta__.sandboxes.cloud_selector labels. Asks cloud (cnv/aws-dedicated-shared) + lab label, namespace suffixes + quotas, optional GitOps bootstrap, optional Showroom. Auto-sets config: namespace, cloud_provider: none, username pattern user-, sandbox_api.destroy.catch_all: false.
Step 7 — Catalog details: Display name, short name, description (starts with product name), maintainer name and email
Step 9 — __meta__: Deployer actions (start/stop only); remove_workloads via sandbox_api.actions.destroy.catch_all; product label + family; keywords
Step 9.1 — Includes: Event restriction in common.yaml (summit-devs or rh1-2026-devs); AWS extras; LiteMaaS (litemaas-master_api + litellm_metadata); workload-specific TODO
Step 10 — Path: Event catalogs → auto-generated path (e.g. summit-2026/lb2298-short-cnv); no-event → asks subdirectory
UUID auto-generated and validated for uniqueness; files committed to branch

Naming Standards (Developer Guidelines):

AgV config: summit-2026/lbXXXX-short-name-cnv
Showroom repo: short-name-showroom
OCP pool: cnv-cluster-4.18/prod (always /prod suffix)
Collections: tag: "" for standard; fixed tag ≥ v1.5.3 for showroom

Event branding (mandatory — Question 2 never skipped):

Event catalogs: category: Brand_Events, Brand_Event: Red_Hat_Summit_2026 label, Lab ID keyword, event access restriction include
anarchy.namespace — NEVER define
catalog.reportingLabels.primaryBU — ALWAYS define

Bundled real examples (no network needed):

ocp-demo/ — OCP with CNV pool
ocp-aws/ — OCP with AWS pool
ocp-cnv/ — openshift_cnv pool
cloud-vms-base/ — RHEL VMs on AWS
published-virtual-ci/ — Virtual CI structure

Mode 2: Description Only - RHDP Official Structure

v1.8.0: Enhanced with full module analysis

With Showroom content:

Reads ALL modules (not just index.adoc)
Extracts overview from index.adoc
Detects Red Hat products across all modules
Extracts version numbers
Identifies technical topics
Shows extracted data for review before generating

Without Showroom content:

Guided questions for RHDP structure
Brief overview (3-4 sentences)
Warnings (optional)
Guide link
Featured products (max 3-4)
Module details (title + 2-3 bullets per module)

Generated description.adoc follows RHDP structure:

Brief Overview (3-4 sentences max, starts with product name)
Warnings (optional, after overview)
Lab/Demo Guide (link to Showroom)
Featured Technology and Products (max 3-4)
Detailed Overview (each module + 2-3 bullets)
Authors (from __meta__.owners)
Support (Content + Environment)

Mode 3: Info Template - User Data Sharing

Documents how to share data with users:

# In your workload:
- name: Save user data
  agnosticd.core.agnosticd_user_info:
    data:
      api_url: ""
      api_key: ""

Template uses: {api_url} and {api_key}

Steps:

Select Info Template mode
Git workflow (automatic)
Specify data keys from agnosticd_user_info.data
Optional: add lab code (e.g., LB1234)
Template generated with proper placeholders

Tips & Best Practices

🏷️ Start with Product Name

Description overview must start with product, not "This workshop"

📚 Use Real Examples

Reference existing catalogs for patterns

✓ Validate Before PR

Always run /agnosticv:validator

🧪 Test in Dev First

Use dev.yaml for testing

🌿 No feature/ Prefix

Branch names should be descriptive without feature/

📝 Convert Lists to Strings

For info templates:

Troubleshooting

Skill not found?

Restart Claude Code or VS Code
Verify installation: ls ~/.claude/skills/agnosticv-catalog-builder
Check the Troubleshooting Guide

Branch already exists?

git branch -D old-branch
# Or use different name

UUID collision?

Skill auto-regenerates unique UUID
Check against existing catalogs automatically

Showroom content not found?

# Verify structure
ls ~/path/to/showroom/content/modules/ROOT/pages/
# Should contain .adoc files

Description starts with "This workshop"?

RHDP Requirement:

Description overview must start with the product name, not "This workshop teaches..."

Example: "OpenShift Pipelines enables..." NOT "This workshop teaches OpenShift Pipelines..."

Git Workflow

Always follows this pattern:

1. Pull latest main

git checkout main
git pull origin main

2. Create descriptive branch (NO feature/ prefix)

✅ Good

add-ansible-ai-workshop
update-ocp-pipelines-description

❌ Bad

feature/add-workshop

3. Auto-commit changes

git add agd_v2/your-catalog/
git commit -m "Add your-catalog catalog"

4. Push and create PR

git push origin your-branch
# Open GitHub → create PR from your branch to main

/agnosticv:validator

Validate catalog before PR

/showroom:create-lab

Create Showroom workshop first

/health:deployment-validator

Create automated health checks

/agnosticv:catalog-builder

What You’ll Need Before Starting

Prerequisites

Clone AgnosticV Repository

Verify RHDP Access

Workshop Content Ready

What You’ll Need (By Mode)

Mode 1: Full Catalog

Mode 2: Description Only

Mode 3: Info Template

Mode 4: Virtual CI (published/)

Quick Start

Navigate to Repository

Run Catalog Builder

Choose Mode

Answer Questions

Review & Commit

What It Can Generate

Common Workflows

Workflow 1: Create Full Catalog from Scratch

Workflow 2: Update Description After Content Changes

Workflow 3: Add Info Template for User Data

Mode Details

What it creates:

Step-by-step process:

Naming Standards (Developer Guidelines):

Event branding (mandatory — Question 2 never skipped):

Bundled real examples (no network needed):

v1.8.0: Enhanced with full module analysis

Generated description.adoc follows RHDP structure:

Documents how to share data with users:

Steps:

Tips & Best Practices

🏷️ Start with Product Name

📚 Use Real Examples

✓ Validate Before PR

🧪 Test in Dev First

🌿 No feature/ Prefix

📝 Convert Lists to Strings

Troubleshooting

RHDP Requirement:

Git Workflow

Always follows this pattern:

1. Pull latest main

2. Create descriptive branch (NO feature/ prefix)

3. Auto-commit changes

4. Push and create PR

Related Skills

/agnosticv:validator

/showroom:create-lab

/health:deployment-validator