Merge pull request #63 from RoddieKieley/001-collection-consistency-audit

001 collection consistency audit

Author: dmartinol

.gitignore

@@ -113,3 +113,4 @@ config.local.*
 
 # Generated Documentation
 docs/data.json
+reports/

CLAUDE.md

@@ -175,7 +175,7 @@ last_updated: YYYY-MM-DD
 1. Create `skills/<skill-name>/SKILL.md`
 2. Define YAML frontmatter with mandatory fields:
    - `name`, `description` (agentskills.io spec)
-   - `model` (inherit|sonnet|haiku), `color` (cyan|green|blue|yellow|red) - Repository requirement
+   - `model` (inherit|sonnet|haiku), `color` (cyan|green|blue|yellow|red|magenta) - Repository requirement
    - Optional: `metadata` for custom fields (author, priority, version)
 3. Follow [SKILL_DESIGN_PRINCIPLES.md](SKILL_DESIGN_PRINCIPLES.md) for:
    - Section structure and ordering
@@ -237,7 +237,7 @@ When creating new collection, use `rh-sre` as the architectural reference.
 
 The `rh-virt` pack demonstrates skill quality standardization:
 - Comprehensive skill templates (`SKILL_TEMPLATE.md`)
-- Risk-based color coding (cyan/green/blue/yellow/red)
+- Risk-based color coding (cyan/green/blue/yellow/red/magenta)
 - Mandatory Common Issues and Example Usage sections
 - Consistent section ordering and formatting
 

README.md

@@ -84,21 +84,18 @@ for m in ocp-admin rh-ai-engineer rh-automation rh-developer rh-sre rh-virt; do
 
 ## 📦 Available Plugins
 
-7 persona-focused plugins with **60+ production-ready skills**:
+6 persona-focused plugins with **62 production-ready skills**:
 
 | Plugin | Version | Skills | Description | Personas |
 |--------|---------|--------|-------------|----------|
 | **[rh-sre](rh-sre/README.md)** | 1.0.0 | 13 | CVE remediation, system compliance, RHEL automation | Site Reliability Engineers |
 | **[rh-developer](rh-developer/README.md)** | 1.0.0 | 14 | Application deployment, S2I builds, Helm charts | Application Developers |
 | **[openshift-virtualization](rh-virt/README.md)** | 1.0.0 | 10 | VM lifecycle, snapshots, migrations, cloning | Virtualization Admins |
 | **[ocp-admin](ocp-admin/README.md)** | 1.0.0 | 3 | Multi-cluster management, health reports, monitoring | OpenShift Administrators |
-| **[rh-ai-engineer](rh-ai-engineer/README.md)** | 1.0.0 | 12 | Model serving, vLLM, KServe, NVIDIA NIM | AI/ML Engineers |
+| **[rh-ai-engineer](rh-ai-engineer/README.md)** | 1.0.0 | 11 | Model serving, vLLM, KServe, NVIDIA NIM | AI/ML Engineers |
 | **[rh-automation](rh-automation/README.md)** | 1.0.0 | 11 | Ansible Automation Platform governance, safety checks | Automation Leads |
-| **[rh-support-engineer](rh-support-engineer/README.md)** | 1.0.0 | 0* | Technical support and troubleshooting | Support Engineers |
 
-**Total:** 63 skills across 7 plugins | **License:** Apache 2.0 | **Status:** Production Ready
-
-<sub>* Coming soon</sub>
+**Total:** 62 skills across 6 plugins | **Standalone Agents:** 0 | **Orchestration:** Delivered through orchestration skills where applicable | **License:** Apache 2.0 | **Status:** Production Ready
 
 ---
 
@@ -222,6 +219,7 @@ Use the `validate-skill-design` and `validate-skill-design-changed` targets to c
 - Human-in-the-loop requirements for critical operations (DP5)
 - Mandatory sections (Prerequisites, When to Use, Workflow) (DP6)
 - Credential security (no `echo $VAR` exposure) (DP7)
+- Required frontmatter policy (`model` required: `inherit|sonnet|haiku`; `color` required: `cyan|green|blue|yellow|red|magenta`)
 
 ```bash
 # Validate only changed skills (staged + unstaged) - recommended for local dev
@@ -296,6 +294,22 @@ gitleaks protect --staged
 
 See [SECURITY.md](SECURITY.md) for details.
 
+## Consistency Audit Severity Guide
+
+Use the consistency audit outputs to prioritize fixes:
+
+- **blocking**: must be fixed before merge; CI fails.
+- **high**: warning in initial rollout; prioritize in same PR when practical.
+- **medium**: warning; schedule near-term cleanup.
+- **informational**: track for hygiene improvements.
+
+Recommended remediation workflow:
+
+1. Run `make validate-consistency-audit`.
+2. Review `reports/consistency-audit.json` and `reports/consistency-audit.md`.
+3. Fix all blocking findings first, then high findings related to changed files.
+4. Re-run `make validate-consistency-audit-ci` before opening or updating a PR.
+
 ## Adding a New MCP Server
 
 To add a new MCP server to an agentic pack and display it on the documentation site:

SKILL_DESIGN_PRINCIPLES.md

@@ -125,7 +125,6 @@ Every skill MUST include complete Dependencies section.
 | green | Success, deployment |
 | yellow | Caution, validation |
 | red | Critical, security, remediation |
-| magenta | Creative, generation |
 
 ## 4. Skill-to-Skill Invocation Standard
 
@@ -241,7 +240,7 @@ name: skill-name                # MANDATORY - kebab-case, matches directory
 description: |                  # MANDATORY - <500 tokens, includes use cases
   [With "Use when" and "NOT for"]
 model: inherit                  # MANDATORY - inherit | sonnet | haiku
-color: green                    # MANDATORY - cyan|green|blue|yellow|red
+color: green                    # MANDATORY - cyan|green|blue|yellow|red|magenta
 ---
 ```
 
@@ -250,12 +249,17 @@ color: green                    # MANDATORY - cyan|green|blue|yellow|red
 - `sonnet` - Complex reasoning
 - `haiku` - Simple, fast operations
 
+**Validation Enforcement:**
+- `scripts/validate_skill_design.py` and `scripts/validate-skills.sh` MUST both enforce required `model` presence and valid model values.
+- Any drift between validators is treated as a policy inconsistency and must be corrected before merge.
+
 **Color Values (Risk-Based):**
 - `cyan` - Read-only (list, view, get)
 - `green` - Additive (create, clone)
 - `blue` - Reversible (start, stop, restart)
 - `yellow` - Destructive but recoverable (snapshot-delete)
 - `red` - Irreversible (delete, restore)
+- `magenta` - Creative/generative workflows (content generation, templating)
 
 **B. Prerequisites Section Must Include:**
 - Required MCP Servers with setup links

docs/README.md

@@ -39,6 +39,20 @@ To manually update the site:
 4. Commit the updated `docs/data.json` and any `.catalog/` files.
 5. Push to trigger GitHub Pages deployment.
 
+## Consistency Audit for Docs Metadata
+
+When changing docs presentation metadata (`styles.css`, `app.js`, `icons.json`, `plugins.json`, `mcp.json`):
+
+1. Prefer canonical tokens from `styles.css` and `style-tokens.json` over hardcoded values.
+2. Ensure every in-scope pack has icon/title mappings in `icons.json` and `plugins.json`.
+3. Run the audit checks:
+
+```bash
+make validate-consistency-audit
+```
+
+4. Review style/icon findings in `reports/consistency-audit.md` before merge.
+
 ## Security
 
 All DOM manipulation in `app.js` uses `textContent` and `createElement` to prevent XSS vulnerabilities. No `innerHTML` is used with user-provided data.

docs/app.js

@@ -9,6 +9,12 @@ let data = null;
 let allPacks = [];
 let allMCPServers = [];
 let allCommunityMCPServers = [];
+const JS_STYLE_TOKENS = {
+    errorColor: 'var(--primary)',
+    mutedTextColor: 'var(--text-muted)',
+    subtleErrorBackground: 'var(--primary-light)',
+    softAccentBackground: 'var(--primary-light)'
+};
 
 /** Default LICENSE in upstream repo (collection legal_resources may override). */
 const UPSTREAM_REPO_LICENSE_URL = 'https://github.com/RHEcosystemAppEng/agentic-collections/blob/main/LICENSE';
@@ -105,7 +111,7 @@ async function init() {
 function showError(message) {
     const main = document.querySelector('main');
     const errorDiv = document.createElement('div');
-    errorDiv.style.color = '#ee0000';
+    errorDiv.style.color = JS_STYLE_TOKENS.errorColor;
     errorDiv.style.padding = '2rem';
     errorDiv.style.textAlign = 'center';
     errorDiv.textContent = `Error: ${message}`;
@@ -126,7 +132,7 @@ function renderPacks(packs) {
     if (packs.length === 0) {
         const noResults = document.createElement('p');
         noResults.textContent = 'No packs found matching your search.';
-        noResults.style.color = '#d2d2d2';
+        noResults.style.color = JS_STYLE_TOKENS.mutedTextColor;
         grid.appendChild(noResults);
         return;
     }
@@ -251,7 +257,7 @@ function renderMCPServers(servers) {
     if (servers.length === 0) {
         const noResults = document.createElement('p');
         noResults.textContent = 'No MCP servers found matching your search.';
-        noResults.style.color = '#d2d2d2';
+        noResults.style.color = JS_STYLE_TOKENS.mutedTextColor;
         grid.appendChild(noResults);
         return;
     }
@@ -276,7 +282,7 @@ function renderCommunityMCPServers(servers) {
     if (servers.length === 0) {
         const noResults = document.createElement('p');
         noResults.textContent = 'No community MCP servers found matching your search.';
-        noResults.style.color = '#d2d2d2';
+        noResults.style.color = JS_STYLE_TOKENS.mutedTextColor;
         grid.appendChild(noResults);
         return;
     }
@@ -594,7 +600,7 @@ function showPackDetails(packName) {
 
         const nameCode = document.createElement('code');
         nameCode.textContent = pack.plugin.name;
-        nameCode.style.backgroundColor = 'rgba(238, 0, 0, 0.1)';
+        nameCode.style.backgroundColor = JS_STYLE_TOKENS.subtleErrorBackground;
         nameCode.style.padding = '0.25rem 0.5rem';
         nameCode.style.borderRadius = '4px';
         nameCode.style.fontSize = '0.85rem';
@@ -934,7 +940,7 @@ lola install -f ${moduleName}`;
             // Hover effects
             mcpDef.onmouseenter = () => {
                 mcpDef.style.borderLeftColor = 'var(--primary)';
-                mcpDef.style.backgroundColor = 'rgba(238, 0, 0, 0.05)';
+                mcpDef.style.backgroundColor = JS_STYLE_TOKENS.softAccentBackground;
                 arrow.style.transform = 'translateX(4px)';
             };
 

docs/style-tokens.json

@@ -0,0 +1,21 @@
+{
+  "colors": {
+    "primary": "var(--primary)",
+    "primaryDark": "var(--primary-dark)",
+    "primaryLight": "var(--primary-light)",
+    "textPrimary": "var(--text-primary)",
+    "textSecondary": "var(--text-secondary)",
+    "textMuted": "var(--text-muted)"
+  },
+  "sizes": {
+    "cardIcon": "1.2rem",
+    "itemIcon": "1rem"
+  },
+  "usage": {
+    "stylesCss": "docs/styles.css",
+    "appJs": "docs/app.js",
+    "iconsJson": "docs/icons.json",
+    "pluginsJson": "docs/plugins.json",
+    "mcpJson": "docs/mcp.json"
+  }
+}

rh-sre/skills/cve-impact/SKILL.md

@@ -8,6 +8,8 @@ description: |
   NOT for remediation (use `/remediation`).
 
   System-level: FIRST reply = pagination prompt (Step -1). Parsing: references/01-cve-response-parser.py.
+model: inherit
+color: blue
 ---
 
 # CVE Impact Analysis Skill

rh-sre/skills/cve-validation/SKILL.md

@@ -17,6 +17,8 @@ description: |
   - "Remediate CVE-X" / "Patch CVE-X" → `/remediation` skill
 
   This skill orchestrates MCP tools (get_cve) for CVE validation. The `/remediation` skill invokes this skill as Step 2 of its workflow.
+model: inherit
+color: blue
 ---
 
 # CVE Validation Skill

rh-sre/skills/playbook-executor/SKILL.md

@@ -12,6 +12,8 @@ description: |
   - "Dry-run the playbook first"
 
   **Git Flow**: If template playbook path ≠ generated playbook, perform Git Flow (commit, push, sync) BEFORE launch.
+model: inherit
+color: red
 ---
 
 # AAP Playbook Executor Skill