feat: add Compass catalog manifests for all agentic packs by r2dedios · Pull Request #133 · RHEcosystemAppEng/agentic-plugins

r2dedios · 2026-07-03T13:50:06Z

Summary

Register the entire agentic-plugins repository in Red Hat Compass (Backstage) with a complete hierarchy of catalog manifests covering all 7 agentic packs, 75 skills, and 7 MCP servers — with fully bidirectional semantic relationships.

Architecture

System (agentic-plugins)
│  hasPart ↔ partOf
├── AiResource(plugin) ocp-admin          ── hasPart ↔ partOf ── 7 skills
├── AiResource(plugin) rh-sre             ── hasPart ↔ partOf ── 13 skills
├── AiResource(plugin) rh-virt            ── hasPart ↔ partOf ── 10 skills
├── AiResource(plugin) rh-developer       ── hasPart ↔ partOf ── 17 skills
├── AiResource(plugin) rh-basic           ── hasPart ↔ partOf ── 6 skills
├── AiResource(plugin) rh-ai-engineer     ── hasPart ↔ partOf ── 11 skills
├── AiResource(plugin) rh-automation      ── hasPart ↔ partOf ── 11 skills
│
├── MCPServer openshift-mcp-server        ── dependencyOf ↔ dependsOn ── consumers
├── MCPServer assisted-installer          ── dependencyOf ↔ dependsOn ── consumers
├── MCPServer ansible-automation-platform ── dependencyOf ↔ dependsOn ── consumers
├── MCPServer podman                      ── dependencyOf ↔ dependsOn ── consumers
├── MCPServer github                      ── dependencyOf ↔ dependsOn ── consumers
├── MCPServer ai-observability            ── dependencyOf ↔ dependsOn ── consumers
└── MCPServer rhoai                       ── dependencyOf ↔ dependsOn ── consumers

Orchestration skills (e.g., remediation, forensic-troubleshooter, containerize-deploy) also declare dependsOn → child skills, with the inverse dependencyOf on each consumed skill.

Entity inventory

Kind	spec.type	Count	Description
Location	—	9	1 root + 7 packs + 1 mcps
System	—	1	`agentic-plugins` (repo-level grouping)
AiResource	`plugin`	7	One per agentic pack
AiResource	`skill`	75	Individual skills across all packs
MCPServer	`local`	7	Owned MCP servers
Total		99

Relationship model

Every relationship is declared bidirectionally as a workaround for COMPASS-1288 (inverse relations not auto-generated for custom kinds).

Relationship	Origin → Target	Inverse on Target
Composition	skill `partOf` plugin	plugin `hasPart` skill
Composition	plugin `partOf` system	system `hasPart` plugin
Composition	MCP `partOf` system	system `hasPart` MCP
Technical dep	skill `dependsOn` MCP	MCP `dependencyOf` skill
Technical dep	plugin `dependsOn` MCP	MCP `dependencyOf` plugin
Technical dep	skill `dependsOn` skill	skill `dependencyOf` skill

Canonical MCP server reuse

Two MCP servers already registered in Compass by their upstream teams are not duplicated — skills reference the canonical entities directly:

Canonical entity	Namespace	Owner
`red-hat-lightspeed-mcp-server`	`redhat`	`rh-lightspeed-mcp`
`security-mcp-server`	`redhat`	`lightforge-mcp-dev`

Key design decisions

Semantic relations: partOf/hasPart for composition (skill belongs to plugin), dependsOn/dependencyOf for technical dependency (skill uses MCP or other skill)
Bidirectional declaration: Both sides of every relationship are explicit in manifests (COMPASS-1288 workaround)
AiResource over System for packs: Packs are AiResource(type: plugin), supporting many-to-many skill↔MCP dependencies
Location delegation: Root Location only references child Locations; each child indexes its own entities
Namespace per pack: Each pack uses its own namespace. MCP servers use agentic-plugins namespace
Reuse canonical MCPs: Existing MCP servers are referenced rather than re-registered

Test plan

All manifests validated against Compass validate-entity API
Automated bidirectional relationship consistency check (90 entities, 0 errors)
Entities registered and visible in Compass catalog (90 entities)
Entity relationships verified (partOf/hasPart, dependsOn/dependencyOf, ownedBy)
Canonical MCP server references resolve correctly
System page shows contained plugins and MCP servers via hasPart

Add catalog-info.yaml manifests to register the repository and ocp-admin agentic pack in Red Hat Compass (Backstage). Includes: - Root Location pointing to all agentic packs - ocp-admin pack Location aggregating skills and MCP servers - 7 AiResource entities for skills (cluster-creator, cluster-inventory, cluster-report, container-cve-validator, coreos-cve-validator, cve-recon, image-inspect) - 3 MCPServer entities (openshift-self-managed, openshift-ocm-managed, openshift-administration) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add 19 centralized MCP server manifests in ./mcps/ (flat structure) with deduplication by functional variant for shared images - Add 68 skill (AiResource) manifests across 6 new packs: rh-sre (13), rh-virt (10), rh-developer (17), rh-basic (6), rh-ai-engineer (11), rh-automation (11) - Add pack Location manifests for rh-sre, rh-virt, rh-developer, rh-basic, rh-ai-engineer, rh-automation - Update root Location to reference all 7 packs + 19 MCPs - Update ocp-admin Location: remove MCP targets, add labels - Update ocp-admin skill dependsOn refs to use default namespace - Remove old ocp-admin/mcps/ catalog-info.yaml files - Add domain-prefixed labels on all Locations: agentic-plugins.redhat.com/version and agentic-plugins.redhat.com/repo

Create a Domain entity (agentic-plugins) as the top-level parent and 7 System entities (one per pack) to provide rich grouping pages in Compass. Skills already reference their pack System via spec.system, so Backstage will auto-generate hasPart relations once these exist.

Merge 19 MCP manifests into 9 by grouping variants that share the same container image or server technology: - 4 openshift-mcp-server variants → openshift-mcp-server - 2 assisted-service-mcp variants → assisted-installer - 2 lightspeed variants → red-hat-lightspeed - 6 AAP endpoint variants → ansible-automation-platform - 5 unique MCPs unchanged Update all 75 skill dependsOn references and deduplicate where a skill previously referenced multiple variants of the same MCP.

Domain kind is not allowed for GitHub-based Location registration in Compass. Remove domain.yaml target and domain references from all System manifests to unblock registration.

Add backstage.io/techdocs-ref annotation to each pack's system.yaml pointing to the pack README.md on GitHub main branch.

Add dedicated namespace to all 9 MCPServer manifests and update all 71 skill dependsOn references accordingly.

…tions - Create System entity for shared MCPs (rh-agentic-plugins-mcps) - Add spec.system to all 9 MCPServer manifests - Add spec.dependsOn to 7 pack Systems linking to their MCPs - Add agentic.redhat.com/* annotations to all pack Locations and Systems - Fix repo label from "redhat-agentic-plugins" to "agentic-plugins" - Remove domain.yaml (Compass rejects Domain from GitHub Locations)

Point each MCPServer to its upstream repo README: - openshift-mcp-server → openshift/openshift-mcp-server - assisted-installer → openshift-assisted/assisted-service-mcp - red-hat-lightspeed → RedHatInsights/insights-mcp - ansible-automation-platform → ansible/aap-mcp-server - ai-observability → rh-ai-quickstart/ai-observability-summarizer - rhoai → opendatahub-io/rhoai-mcp - podman → manusa/podman-mcp-server - github → github/github-mcp-server red-hat-security skipped (no public repo, hosted service).

Add airesource dependsOn entries for orchestration skills that directly invoke other skills via the Skill tool. Covers 37 dependencies across 8 skills in rh-sre, rh-developer, rh-automation, and rh-ai-engineer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

TechDocs builder expects mkdocs.yml + docs/ in the target repo, but our techdocs-ref URLs pointed to bare README.md files causing ENOENT errors. Move upstream MCP repo URLs to metadata.links instead, where they render as navigable links without triggering the builder. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace kind: System with kind: AiResource (type: plugin) for all 7 agentic packs. Rename system.yaml to <pack>-plugin.yaml. Add disciplines, categories, agents, and lifecycle fields to each pack manifest.

Remove spec.system from all 75 skill catalog-info.yaml files and add airesource:<pack>/<pack> to spec.dependsOn instead. Also update MCP server references to use agentic-plugins namespace.

Add root System entity (agentic-plugins). Remove mcps/system.yaml and consolidate all entities under the single system. Create mcps Location, add plugin targets to pack Locations, and simplify root Location to delegate through pack and MCP Locations only.

Document entity kinds, Location hierarchy, entity relationships, namespaces, reference formats, and workflows for adding new skills and packs with their Compass manifests.

Backstage resolves unqualified spec.system references relative to the entity's own namespace. Since the System entity is in the default namespace but plugins and MCPs use their own namespaces, the partOf relation was not resolving. Use default/agentic-plugins to fix.

Compass does not auto-generate hasPart inverse relations for custom kinds (AiResource, MCPServer). Declare them explicitly so the System page shows its contained plugins and MCP servers.

Remove duplicate MCPServer entities for Red Hat Lightspeed and Red Hat Security, replacing dependsOn references with their canonical versions already registered in Compass by their respective teams: - mcpserver:agentic-plugins/red-hat-lightspeed → mcpserver:redhat/red-hat-lightspeed-mcp-server - mcpserver:agentic-plugins/red-hat-security → mcpserver:redhat/security-mcp-server Reduces our registered MCP servers from 9 to 7.

Update spec.owner across all 90 Compass manifests from group:redhat/ecosystem-appeng to group:redhat/ai5-marketplace.

…PServer remotes

Signed-off-by: r2dedios <alex.ansi.c@gmail.com>

Replace dependsOn for skill→plugin with partOf (composition), keep dependsOn for skill→skill and skill→MCP (technical dependency). Add explicit inverse relations: hasPart on plugins and system, partOf and dependencyOf on MCP servers, dependencyOf on skills consumed by orchestration skills. Workaround for COMPASS-1288 where dependsOn does not auto-generate dependencyOf.

r2dedios · 2026-07-28T15:10:47Z

  ┌─────────────────────────────────────────────────────────────────────┐
  │                    System: agentic-plugins                         │
  │                                                                     │
  │  hasPart ──┬── airesource:ocp-admin/ocp-admin                      │
  │            ├── airesource:rh-sre/rh-sre                             │
  │            ├── airesource:rh-virt/rh-virt                           │
  │            ├── airesource:rh-developer/rh-developer                 │
  │            ├── airesource:rh-basic/rh-basic                         │
  │            ├── airesource:rh-ai-engineer/rh-ai-engineer             │
  │            ├── airesource:rh-automation/rh-automation               │
  │            ├── mcpserver:agentic-plugins/openshift-mcp-server       │
  │            ├── mcpserver:agentic-plugins/assisted-installer         │
  │            ├── mcpserver:agentic-plugins/ansible-automation-platform │
  │            ├── mcpserver:agentic-plugins/podman                     │
  │            ├── mcpserver:agentic-plugins/github                     │
  │            ├── mcpserver:agentic-plugins/ai-observability           │
  │            └── mcpserver:agentic-plugins/rhoai                      │
  └─────────────────────────────────────────────────────────────────────┘
           ▲ partOf                              ▲ partOf
           │                                     │
  ┌────────┴──────────────────┐    ┌─────────────┴──────────────────┐
  │  AiResource (plugin)      │    │  MCPServer                     │
  │  e.g. rh-sre              │    │  e.g. openshift-mcp-server     │
  │                           │    │                                │
  │  partOf: system           │    │  partOf: system                │
  │  dependsOn: [MCPServers]──┼───►│  dependencyOf: [plugins,skills]│
  │  hasPart: [skills]        │    └────────────────────────────────┘
  └───────┬───────────────────┘                  ▲
          │ hasPart                              │ dependencyOf
          ▼ partOf                               │
  ┌───────────────────────────────┐              │
  │  AiResource (skill)           │              │
  │  e.g. remediation             │              │
  │                               │              │
  │  partOf: [plugin]             │              │
  │  dependsOn: [MCPServers] ─────┼──────────────┘
  │  dependsOn: [other skills] ───┼──┐
  │  dependencyOf: [orq. skills]  │  │
  └───────────────────────────────┘  │
          ▲ dependencyOf             │ dependsOn
          └──────────────────────────┘

  Ejemplo concreto (rh-sre):

    rh-sre (plugin)
      ├── hasPart ↔ partOf ── cve-impact
      ├── hasPart ↔ partOf ── cve-validation
      ├── hasPart ↔ partOf ── playbook-executor
      ├── hasPart ↔ partOf ── playbook-generator
      ├── hasPart ↔ partOf ── remediation
      ├── ...
      └── dependsOn ↔ dependencyOf ── lightspeed-mcp, aap-mcp

    remediation (skill de orquestación)
      ├── partOf ↔ hasPart ── rh-sre (plugin)
      ├── dependsOn ↔ dependencyOf ── cve-impact
      ├── dependsOn ↔ dependencyOf ── cve-validation
      ├── dependsOn ↔ dependencyOf ── playbook-generator
      ├── dependsOn ↔ dependencyOf ── playbook-executor
      ├── dependsOn ↔ dependencyOf ── remediation-verifier
      └── dependsOn ↔ dependencyOf ── lightspeed-mcp, aap-mcp

…nifests Compass only processes partOf/hasPart for standard Backstage kinds (Component, API, Resource). Custom kinds like AiResource and MCPServer store these fields in spec but they are not processed into the relation graph. All relationships now use dependsOn/dependencyOf which generates actual relations for any entity kind.

dmartinol

I think we need to rely on Mayur for a feedback about some modeling assumptions, and IMO we should simplify the resources definition to reduce the maintenance burden and clarify the relations.

dmartinol · 2026-08-04T12:26:50Z

+  owner: group:redhat/ai5-marketplace
+  system: default/agentic-plugins
+  primitives:
+    - type: tool


Why we don't specify the primitives for all the other MCPs as well?

dmartinol · 2026-08-04T12:41:41Z

+
+All relationships use `dependsOn` / `dependencyOf`:
+
+> **Why not `partOf`/`hasPart`?** Compass only processes `partOf`/`hasPart` for standard Backstage kinds (Component, API, Resource). Custom kinds like `AiResource` and `MCPServer` can store these fields in `spec`, but they are not processed into the relation graph. Only `dependsOn`/`dependencyOf` and `ownedBy`/`ownerOf` generate actual relations for custom kinds.


This seems a bug and we should instead try to fix it rather than finding a workaround. WDYT?

dmartinol · 2026-08-04T12:42:25Z

+- **Skill → Skill**: `dependsOn` / `dependencyOf` (orchestration skills invoke other skills)
+- **All entities → Group**: `spec.owner: group:redhat/ai5-marketplace`
+
+> **Bidirectional declaration policy:** Compass does not auto-generate inverse relations for custom entity kinds such as `AiResource` and `MCPServer` (tracked as COMPASS-1288). Until this is resolved upstream, we explicitly declare **both directions** of every relationship in our manifests. For example, if a skill declares `dependsOn: [airesource:rh-sre/rh-sre]`, the plugin must also declare `dependencyOf: [airesource:rh-sre/<skill>]`. When adding or modifying a relationship, always update both the source and target manifests.


Some of them are not needed and may require hard maintenance, please consider this to define your design.

dmartinol · 2026-08-04T12:44:58Z

+- Pack plugins: `airesource:<pack-namespace>/<pack-name>`
+- MCP servers: `mcpserver:agentic-plugins/<server-name>`
+
+#### Adding Compass Manifests for a New Skill


I think we need a skill to generate it, under .claude/skills

dmartinol · 2026-08-04T13:23:44Z

@@ -20,6 +22,7 @@ agentic-plugins/
 ├── rh-ai-engineer/      # AI Engineering pack
 ├── rh-automation/       # Automation pack
 ├── rh-support-engineer/ # Support engineering pack


pls remove this stale entry

dmartinol · 2026-08-04T13:40:01Z

+    - opencode
+    - cursor
+  dependsOn:
+    - system:default/agentic-plugins


these are redundant, just keep the spec.system field instead

r2dedios and others added 19 commits July 3, 2026 15:46

fix: remove Domain entity from Location targets

df03ed4

Domain kind is not allowed for GitHub-based Location registration in Compass. Remove domain.yaml target and domain references from all System manifests to unblock registration.

feat: add TechDocs annotation to all System manifests

3deefb1

Add backstage.io/techdocs-ref annotation to each pack's system.yaml pointing to the pack README.md on GitHub main branch.

feat: add rh-agentic-plugins-mcps namespace to MCP manifests

3bf6e63

Add dedicated namespace to all 9 MCPServer manifests and update all 71 skill dependsOn references accordingly.

refactor: convert pack System entities to AiResource plugins

7e301fc

Replace kind: System with kind: AiResource (type: plugin) for all 7 agentic packs. Rename system.yaml to <pack>-plugin.yaml. Add disciplines, categories, agents, and lifecycle fields to each pack manifest.

refactor: replace spec.system with dependsOn in skill manifests

b913638

Remove spec.system from all 75 skill catalog-info.yaml files and add airesource:<pack>/<pack> to spec.dependsOn instead. Also update MCP server references to use agentic-plugins namespace.

docs: add Compass manifest documentation to CLAUDE.md

b476511

Document entity kinds, Location hierarchy, entity relationships, namespaces, reference formats, and workflows for adding new skills and packs with their Compass manifests.

fix: add explicit hasPart relations to System entity

8c2289e

Compass does not auto-generate hasPart inverse relations for custom kinds (AiResource, MCPServer). Declare them explicitly so the System page shows its contained plugins and MCP servers.

revert: remove explicit hasPart relations (not supported by Compass)

77c4cb3

r2dedios changed the title ~~feat: add Compass catalog manifests for ocp-admin pack~~ feat: add Compass catalog manifests for all agentic packs Jul 10, 2026

r2dedios added 6 commits July 13, 2026 17:34

chore: change owner group to ai5-marketplace

ac06903

Update spec.owner across all 90 Compass manifests from group:redhat/ecosystem-appeng to group:redhat/ai5-marketplace.

feat: add distribution: external label to MCPServer manifests

4ca7656

fix: replace env var interpolation with static placeholder URLs in MC…

44e705a

…PServer remotes

fix: replaced link by the proper annotation

25c03b5

Signed-off-by: r2dedios <alex.ansi.c@gmail.com>

refactor: move agentic-plugins.redhat.com labels to annotations

6aa42bb

r2dedios marked this pull request as ready for review August 4, 2026 11:52

r2dedios requested a review from dmartinol as a code owner August 4, 2026 11:52

r2dedios requested review from ikrispin and nemerna as code owners August 4, 2026 11:52

dmartinol reviewed Aug 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add Compass catalog manifests for all agentic packs - #133

feat: add Compass catalog manifests for all agentic packs#133
r2dedios wants to merge 26 commits into
RHEcosystemAppEng:mainfrom
r2dedios:compass-skill-manifests

r2dedios commented Jul 3, 2026 •

edited

Loading

Uh oh!

r2dedios commented Jul 28, 2026

Uh oh!

dmartinol left a comment

Uh oh!

Uh oh!

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

Uh oh!

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

dmartinol Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		All relationships use `dependsOn` / `dependencyOf`:

		> Why not `partOf`/`hasPart`? Compass only processes `partOf`/`hasPart` for standard Backstage kinds (Component, API, Resource). Custom kinds like `AiResource` and `MCPServer` can store these fields in `spec`, but they are not processed into the relation graph. Only `dependsOn`/`dependencyOf` and `ownedBy`/`ownerOf` generate actual relations for custom kinds.

Uh oh!

Conversation

r2dedios commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

Entity inventory

Relationship model

Canonical MCP server reuse

Key design decisions

Test plan

Uh oh!

r2dedios commented Jul 28, 2026

Uh oh!

dmartinol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

dmartinol Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

r2dedios commented Jul 3, 2026 •

edited

Loading