Collection catalogs - YAML schema validation, and authoring tooling

.claude/skills/collection-compliance/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: collection-compliance
+description: |
+  Diagnose and fix `.catalog/` validation failures (schema, roster, banners, sample workflows, JSON mirror). Use when:
+  - `make validate` or CI reports collection compliance errors
+  - A PR adds skills but catalog was not updated
+  - `collection.json` is out of sync with `collection.yaml`
+  - Catalog metadata/fragments might have drifted from README/CLAUDE/SKILL golden sources
+
+  Remediation is via the create-collection workflow and `catalog_yaml_to_json.py`—not by weakening checks.
+model: inherit
+color: yellow
+allowed-tools: Read Glob Grep Bash
+---
+
+# Collection compliance
+
+**Audience:** Contributors fixing `.catalog/` CI failures.
+
+**Goal:** Clear reported violations from `scripts/validate_collection_compliance.py` and `scripts/validate_collection_schema.py`, then perform AI semantic alignment review against golden sources.
+
+## Prerequisites
+
+- Run from repository root.
+- Read [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md).
+
+## When to Use
+
+- After `make validate-collection-compliance` fails locally or in GitHub Actions.
+
+## Workflow
+
+1. **Re-run** `uv run python scripts/validate_collection_compliance.py` and capture errors (pack path + message).
+
+2. **Classify**
+   - **Missing file** — create `.catalog/collection.yaml` via create-collection skill (or `uv run python scripts/bootstrap_catalog.py --pack <pack>` for bootstrap baseline).
+   - **Schema** — align YAML with [catalog/schema.yaml](../../catalog/schema.yaml).
+   - **Roster** — every `skills/<n>/SKILL.md` must appear once under `contents.skills` or `contents.orchestration_skills` with `name == <n>`.
+   - **Banner** — `collection.yaml` must mention `create-collection` and `Golden sources` in the opening `#` block.
+   - **`collection.json` drift** — run `uv run python scripts/catalog_yaml_to_json.py --pack <pack>` or `make catalog-mirror-json`.
+   - **Fragment refs / length** — `deploy_and_use`, `documentation_section`, `mcp_section`, and `security_model` may be inline or a one-line `#fragment.md` under `.catalog/`. Refs must start with `#`. Inline monitored fields over **500** code points must move to a fragment on the **same** key.
+   - **Fragment provenance (`.catalog/*.md`)** — each referenced fragment must start with a leading HTML **`<!-- … -->`** block with the **same intent** as the `collection.yaml` banner: **create-collection** workflow and **Golden sources** (SKILL, README, CLAUDE, marketplace). See [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md) **Provenance banners** (CI does not yet assert this text; fix when reviewing fragments).
+   - **Thin `deploy_and_use` (manual review)** — if the pack has **`mcps.json`** MCP servers, **`deploy_and_use`** (inline or **`#deploy_and_use.md`**) should meet [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md) **install + env + MCP** (prerequisites, **`export`** for each **`${VAR}`** name, Lola **`path:`**, MCP notes, optional Claude/Cursor install). CI may not fail; fix via **create-collection** when reviewing PRs.
+
+3. **AI semantic alignment review (required)**
+   - Treat scripts as **structural guards only**; they do not fully verify semantic alignment.
+   - Compare each pack's catalog metadata and referenced fragments against golden sources:
+     - `skills/*/SKILL.md` (names, descriptions, scope, orchestration intent)
+     - `README.md` (installation, prerequisites, env variables, usage caveats)
+     - `CLAUDE.md` (persona, routing, global rules, MCP posture)
+     - `marketplace/rh-agentic-collection.yml` (module `path`, module name/description/tags)
+   - Fail review if any of these drift conditions are found:
+     - Installation steps differ in substance (for example Lola module IDs/paths mismatch)
+     - Required env vars in `mcps.json` are missing or inconsistent in `deploy_and_use`
+     - Skill inventory/routing intent in catalog contradicts `skills/` + `CLAUDE.md`
+     - Fragment prose overstates/understates capabilities versus README/skills
+   - Remediate via create-collection workflow and then regenerate JSON mirror.
+
+4. **Re-validate** — `make validate-collection-compliance`.
+
+## Dependencies
+
+- create-collection skill (sibling under `.cursor/skills/`)
+
+## Common Issues
+
+- **`skills_decision_guide` with no skills** — guide must be `[]` if the pack has no `skills/` tree.
+- **Orchestration miscount** — move skills that delegate end-to-end flows to `orchestration_skills` per COLLECTION_SPEC judgment rules.
+- **Install drift** — `README.md` and `.catalog/deploy_and_use(.md)` disagree on Lola commands/module IDs.
+- **Env drift** — `${VAR}` names in `mcps.json` are not fully represented in `deploy_and_use`.
+
+## Example usage
+
+```bash
+make validate-collection-compliance
+uv run python scripts/catalog_yaml_to_json.py --pack rh-developer
+make validate-collection-compliance
+```

.claude/skills/create-collection/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: create-collection
+description: |
+  Author or refresh `<pack>/.catalog/collection.yaml` and related `.catalog/` artifacts from golden sources (SKILL.md, README, CLAUDE.md, Lola marketplace). Use when:
+  - Adding a new pack or refreshing the collection catalog for GitHub Pages / tooling
+  - Aligning catalog narrative, sample workflows, and decision guide with skills on disk
+  - Preparing a PR after changing skills or marketplace metadata
+
+  Outputs only under `<pack>/.catalog/` (never overwrite README, SKILL, CLAUDE, or marketplace YAML).
+model: inherit
+color: blue
+allowed-tools: Read Glob Grep Bash
+---
+
+# Create collection catalog
+
+**Audience:** Maintainers and assistants updating per-pack `.catalog/` data.
+
+**Goal:** Produce a coherent `collection.yaml` that passes `make validate-collection-compliance`, using human judgment for synthesis—not a blind dump of frontmatter.
+
+## Prerequisites
+
+- Repository root as cwd.
+- Read [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md) and [catalog/schema.yaml](../../catalog/schema.yaml).
+- Optional: run `uv run python scripts/scaffold_catalog.py <pack>` for a stdout draft roster.
+
+## When to Use
+
+- New marketplace module or new pack directory needs `.catalog/`.
+- Skills were added/removed/renamed and roster parity must match disk.
+- Marketplace `description` / `version` changed and catalog should reflect it (still edit marketplace in git separately).
+
+## Workflow
+
+1. **Resolve pack** — directory name must appear in `union(marketplace/modules[].path, docs/plugins.json keys)` and exist on disk.
+
+2. **Read sources in order** (precedence):
+   - `skills/*/SKILL.md` (frontmatter + body for summaries and orchestration hints)
+   - `<pack>/README.md`
+   - `<pack>/CLAUDE.md` (intent routing → `skills_decision_guide` ideas)
+   - Matching row in `marketplace/rh-agentic-collection.yml` (`path` == pack)
+
+3. **Classify skills** — place each skill in `contents.skills` or `contents.orchestration_skills` using maintainer judgment. Optional hint: `metadata.collection.role: orchestration` in `SKILL.md` frontmatter. Names in YAML **must** match the `skills/<name>/` directory name.
+
+4. **Write `<pack>/.catalog/collection.yaml`** — start with the standard **# banner** (see COLLECTION_SPEC). Include every field required by [catalog/schema.yaml](../../catalog/schema.yaml). Keep inline strings under **500 Unicode code points** for monitored fields (`summary`, `documentation_section`, `mcp_section`, `security_model`, and inline **`deploy_and_use`**); otherwise move prose to a sibling **`.md`** and reference with **`#filename.md`** or **`deploy_and_use: #install.md`** (see COLLECTION_SPEC).
+
+   **`deploy_and_use` / install prose:** Follow [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md) **`deploy_and_use` content (install + env + MCP)**. If **`mcps.json`** defines MCP servers, document prerequisites, **`export`** lines for **every `${VAR}`** name used there, Lola + marketplace **`path:`**, optional Claude/Cursor install when those marketplaces are listed, and an MCP configuration subsection. Prefer **`deploy_and_use: '#deploy_and_use.md'`** plus **`deploy_and_use.md`** structured like **`rh-sre/.catalog/deploy_and_use.md`** (see **`rh-virt/.catalog/deploy_and_use.md`** for a kubeconfig-focused variant).
+
+   **YAML multiline style (`|` literal blocks):** For `contents.description`, every **`summary_markdown`** (regular and orchestration skills), and every **`sample_workflows[].workflow`**, use a **literal block scalar** (`field: |`) instead of a single-quoted string that continues across many YAML lines with spacer blanks. Indent each body line one level deeper than the key line. Inside the block, keep **consecutive lines without empty lines** between the intro, `**Use when:**`, list items, and `**What it does:**` (and similar headings) unless you intentionally want extra paragraph breaks in rendered markdown—reference **`rh-sre`** and **`rh-developer`** `.catalog/collection.yaml` for the house style. Prose with apostrophes (e.g. *What's*) stays readable in `|` without `''` escaping.
+
+5. **Mirror JSON** — from repo root: `uv run python scripts/catalog_yaml_to_json.py --pack <pack>` (or `make catalog-mirror-json`).
+
+6. **Self-review checklist**
+   - Every on-disk `skills/<n>/SKILL.md` appears exactly once in `skills` ∪ `orchestration_skills` (orchestration-only skills such as `/remediation` still live under `skills/<name>/`; list them **only** under `contents.orchestration_skills` when they orchestrate others).
+   - No `TODO:` / `TBD` in `sample_workflows.workflow`; each workflow includes `User:` and `-` bullets.
+   - `skills_decision_guide` empty if the pack has **no** skills; otherwise each `skill_to_use` matches a skill dir.
+   - `resources[].url` set; `embedded_doc` only if that path exists under the pack.
+   - **Install / deploy (`deploy_and_use`):** **inline** (≤ **500** code points) *or* one-line **`#deploy_and_use.md`** ref (see [COLLECTION_SPEC.md](../../COLLECTION_SPEC.md) **install + env + MCP**). If **`mcps.json`** has MCP servers: fragment (or inline) must include prerequisites, **`export`** examples for each **`${VAR}`** name from **`mcps.json`**, Lola/marketplace **`path:`**, and MCP configuration notes; add Claude Code / Cursor install when **`marketplaces`** lists them. Fragments use the HTML provenance banner. Use **`mcps.json`**, not `.mcp.json`.
+   - **Other long blocks:** use **`documentation_section`**, **`mcp_section`**, and **`security_model`** with either inline markdown (≤ **500** code points) or a one-line **`#fragment.md`** ref on that same key (same pattern as **`deploy_and_use`**).
+   - **Publication-style metadata (when useful):** `support_level`, `author`, `homepage`, `keywords`, `legal_resources` (URLs only).
+   - **`version` / listing fields:** Align `version` and core listing copy with the matching **`marketplace/rh-agentic-collection.yml`** row (`path` == pack); do not bump marketplace YAML from the catalog workflow.
+   - **Multiline fields:** `contents.description`, all **`summary_markdown`**, and all **`sample_workflows[].workflow`** use **`|`** block scalars (not long single-quoted multiline); content lines are compact unless extra blank lines are deliberate for markdown.
+
+7. **Validate** — `make validate-collection-compliance` before commit.
+
+## Dependencies
+
+- `make validate-collection-compliance`
+- `uv run python scripts/scaffold_catalog.py <pack>` (optional)
+
+## Common Issues
+
+- **CI: `collection.json` drift** — regenerate with `make catalog-mirror-json`.
+- **Roster errors** — YAML `name` must equal the skill folder name, not a display alias.
+- **Empty support pack** — if there are no `skills/`, use empty `skills`, `orchestration_skills`, and `skills_decision_guide: []`.
+- **Unreadable multiline YAML** — replace spanning `'`…`'` blocks with **`field: |`** and indented lines; see step 4 **YAML multiline style**.
+- **Thin `deploy_and_use`** — pack has **`mcps.json`** but catalog only says “see README”; add **Environment setup** (`export` for each **`${VAR}`**) and **MCP configuration** per COLLECTION_SPEC (use **`#deploy_and_use.md`** like **rh-sre** / **rh-virt**).
+
+## Example usage
+
+```bash
+uv run python scripts/scaffold_catalog.py rh-sre
+uv run python scripts/catalog_yaml_to_json.py --pack rh-sre
+make validate-collection-compliance
+```

.github/workflows/deploy-pages.yml

@@ -10,6 +10,11 @@ on:
       - 'ocp-admin/**'
       - 'rh-support-engineer/**'
       - 'rh-virt/**'
+      - 'rh-automation/**'
+      - 'rh-ai-engineer/**'
+      - 'marketplace/**'
+      - 'catalog/**'
+      - '**/.catalog/**'
       - 'scripts/**'
       - 'docs/**'
       - '.github/workflows/deploy-pages.yml'

.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# See README.md "Git hooks (pre-commit)" for install. Aligns with CI: make validate + changed skill design.
+default_install_hook_types: [pre-commit]
+
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      # Uses gitleaks on PATH (install: brew install gitleaks, or run scripts/install-hooks.sh)
+      - id: gitleaks-system
+
+  - repo: local
+    hooks:
+      - id: make-validate
+        name: make validate (structure + collection compliance)
+        entry: make validate
+        language: system
+        pass_filenames: false
+        files: |
+          (?x)^(
+            catalog/.*|
+            marketplace/.*|
+            scripts/(validate_structure|validate_collection_compliance|validate_collection_schema|collection_validate_lib|pack_registry|catalog_yaml_to_json)\.py|
+            (rh-[-a-z0-9]+|ocp-admin)/\.catalog/.*|
+            (rh-[-a-z0-9]+|ocp-admin)/skills/[^/]+/SKILL\.md|
+            (rh-[-a-z0-9]+|ocp-admin)/mcps\.json|
+            (rh-[-a-z0-9]+|ocp-admin)/CLAUDE\.md
+          )
+
+      - id: validate-skill-design-changed
+        name: make validate-skill-design-changed (Tier-2 skill design)
+        entry: make validate-skill-design-changed
+        language: system
+        pass_filenames: false
+        files: ^(rh-[-a-z0-9]+|ocp-admin)/skills/[^/]+/SKILL\.md$

CLAUDE.md

@@ -27,6 +27,7 @@ Each pack follows this structure:
 ├── CLAUDE.md            # Claude Code instruction routing (persona, skills, rules)
 ├── README.md            # Pack description, persona, target marketplaces
 ├── mcps.json            # MCP server configurations (uses env vars for credentials)
+├── .catalog/            # collection.yaml + collection.json (COLLECTION_SPEC.md, catalog/schema.yaml)
 ├── skills/              # Specialized task executors (including orchestration skills)
 │   └── <skill>/
 │       └── SKILL.md     # Skill definition with YAML frontmatter
@@ -51,6 +52,15 @@ Optional (not required for Lola): `.claude-plugin/plugin.json` — Claude Code p
 
 **Key Pattern**: Skills encapsulate tools; orchestration skills invoke other skills. Never call MCP tools directly - always go through skills. For end-to-end CVE remediation, use the `/remediation` skill which orchestrates 6 specialized skills.
 
+### Repository catalog skills (`.catalog/`)
+
+Packs listed in `union(marketplace/rh-agentic-collection.yml modules[].path, docs/plugins.json keys)` maintain **`<pack>/.catalog/collection.yaml`** (and a deterministic **`collection.json`** mirror). Golden sources remain `SKILL.md`, `README.md`, `CLAUDE.md`, and marketplace YAML—**never** generated from catalog back into those files.
+
+- **`create-collection`** (`.claude/skills/create-collection/`) — workflow to author or refresh catalog YAML under `.catalog/`.
+- **`collection-compliance`** (`.claude/skills/collection-compliance/`) — interpret `make validate-collection-compliance` failures and fix drift.
+
+Validation: `make validate` runs pack structure checks plus **collection compliance**. Human rules (inline vs fragment paths, optional `#` on paths): [COLLECTION_SPEC.md](COLLECTION_SPEC.md). Machine schema: [catalog/schema.yaml](catalog/schema.yaml). Pack list helper: [`scripts/pack_registry.py`](scripts/pack_registry.py).
+
 ## Skill and Agent Requirements
 
 **CRITICAL:** EVERY SKILL and AGENT must comply with: