feat(boost): RHDHPLAN-1507 openspecs

[gabemontero]

Hey, I just made a Pull Request!

These are the openspec markdowns through tasks.md for all the RHIDP epics / stories under RHDHPLAN-1507

✔️ Checklist

• [n/a] A changeset describing the change and affected packages. (more info)
• [/] Added or Updated documentation
• [n/a] Tests for new functionality and regression tests for bug fixes
• [/] Screenshots attached (for UI changes)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:01 PM UTC · Completed 6:06 PM UTC
Commit: a04cf01 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.65%. Comparing base (a04cf01) to head (8ce7e07).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3752   +/-   ##
=======================================
  Coverage   54.65%   54.65%           
=======================================
  Files        2360     2360           
  Lines       90140    90140           
  Branches    25214    25207    -7     
=======================================
  Hits        49270    49270           
- Misses      40598    40651   +53     
+ Partials      272      219   -53     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	83.70% <ø> (ø)		Carriedforward from 98d6df5
ai-integrations	67.53% <ø> (ø)		Carriedforward from 98d6df5
app-defaults	69.79% <ø> (ø)		Carriedforward from 98d6df5
augment	46.39% <ø> (ø)		Carriedforward from 98d6df5
boost	73.13% <ø> (ø)
bulk-import	72.46% <ø> (ø)		Carriedforward from 98d6df5
cost-management	14.10% <ø> (ø)		Carriedforward from 98d6df5
dcm	61.81% <ø> (ø)		Carriedforward from 98d6df5
extensions	61.53% <ø> (ø)		Carriedforward from 98d6df5
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from 98d6df5
global-header	59.71% <ø> (ø)		Carriedforward from 98d6df5
homepage	50.23% <ø> (ø)		Carriedforward from 98d6df5
install-dynamic-plugins	56.77% <ø> (ø)		Carriedforward from 98d6df5
konflux	91.49% <ø> (ø)		Carriedforward from 98d6df5
lightspeed	69.02% <ø> (ø)		Carriedforward from 98d6df5
mcp-integrations	85.46% <ø> (ø)		Carriedforward from 98d6df5
orchestrator	43.74% <ø> (ø)		Carriedforward from 98d6df5
quickstart	65.63% <ø> (ø)		Carriedforward from 98d6df5
sandbox	79.56% <ø> (ø)		Carriedforward from 98d6df5
scorecard	82.93% <ø> (ø)		Carriedforward from 98d6df5
theme	61.26% <ø> (ø)		Carriedforward from 98d6df5
translations	7.25% <ø> (ø)		Carriedforward from 98d6df5
x2a	78.68% <ø> (ø)		Carriedforward from 98d6df5

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a04cf01...8ce7e07. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[rhdh-qodo-merge]

PR Summary by Qodo

Add RHDHPLAN-1507 OpenSpec change sets for entity model, OCI registry, and Neo4j graph

📝 Documentation ✨ Enhancement 🕐 40+ Minutes

AI Description

• Add OpenSpec change sets for AI entity model/SDK, OCI skill registry, and Neo4j sync.
• Document post-consolidation epic ownership and cross-connector dependency mapping.
• Provide detailed specs and task plans for annotations, incremental sync, and graph relationships.

Diagram

graph TD
  SDK["Entity Provider SDK"] --> OCI["OCI Skill Connector"] --> CAT["Backstage Catalog"]
  OCI --> REG{{"OCI Registries"}}
  SDK --> NEO["Neo4j Sync Adapter"]
  CAT --> NEO --> DB[("Neo4j")]

  subgraph Legend
    direction LR
    _svc["Service/Module"] ~~~ _db[("Database")] ~~~ _ext{{"External"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Split into 3 PRs (one per change set)

• ➕ Smaller review surface area per PR
• ➕ Can merge the least-controversial spec set first
• ➖ Harder to keep cross-references (SDK/air-gapped/dependencies) consistent
• ➖ More overhead for reviewers to re-context switch across PRs

2. Generate a single umbrella index document

• ➕ Gives reviewers one entry point for the whole initiative
• ➕ Reduces duplicated consolidation/dependency notes across files
• ➖ Adds another artifact to maintain alongside OpenSpec-required files
• ➖ Risk of the index diverging from per-spec sources of truth

Recommendation: Current approach (three explicit OpenSpec change sets with per-area proposals/design/specs/tasks) is appropriate for OpenSpec workflows and preserves clear ownership boundaries. If review bandwidth is constrained, consider adding a lightweight README/index inside workspaces/boost/openspec/changes/ summarizing links and dependency graph, but avoid splitting unless reviewers request it.

Files changed (24) +3421 / -0

Documentation (21) +3412 / -0

design.mdDesign decisions for annotation-based AI asset modeling +230/-0

Design decisions for annotation-based AI asset modeling

• Defines the core design for classifying AI assets via annotations independent of entity kind, with a documented migration path to upstream kinds. Records consolidation notes and stakeholder alignment constraints (notably the conditional dependency on RHDHPLAN-1113).

workspaces/boost/openspec/changes/ai-catalog-entity-model/design.md

proposal.mdProposal for AI catalog entity model + SDK scope +98/-0

Proposal for AI catalog entity model + SDK scope

• Introduces the motivation and scope for standardizing AI asset representation in the Backstage catalog. Captures post-consolidation epic ownership and calls out migration-readiness and operational requirements (air-gapped, delta sync, performance/resilience).

workspaces/boost/openspec/changes/ai-catalog-entity-model/proposal.md

spec.mdSpec: air-gapped deployment patterns (moved scope) +179/-0

Spec: air-gapped deployment patterns (moved scope)

• Defines requirements for custom CA bundles, Secret-only credentials, and configurable endpoints for disconnected environments. Notes that these concerns moved to cross-connector infrastructure epic RHIDP-15316 and references the split stories.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/air-gapped-deployment/spec.md

spec.mdSpec: AI asset annotation scheme requirements +113/-0

Spec: AI asset annotation scheme requirements

• Specifies required annotations for category/version/source and acceptance/rejection behavior during ingestion. Documents normalization rules and the expectation that the SDK exports constants and utilities backed by tests.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/annotation-scheme/spec.md

spec.mdSpec: cursor-based delta sync framework +78/-0

Spec: cursor-based delta sync framework

• Documents incremental sync requirements built on Backstage applyMutation({type:'delta'}) including cursor persistence, fallback-to-full-refresh behavior, and backward compatibility for full-refresh providers.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/delta-sync-framework/spec.md

spec.mdSpec: entity-provider SDK contract and exports +112/-0

Spec: entity-provider SDK contract and exports

• Defines the TypeScript provider interface contract, validation utilities, and required package exports for @boost/entity-provider-sdk. Captures consolidation-driven scope expansion and cross-connector dependencies for config/CA/error-isolation patterns.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/entity-provider-sdk/spec.md

spec.mdSpec: migration readiness to upstream Backstage kinds +110/-0

Spec: migration readiness to upstream Backstage kinds

• Defines the requirement for a migration design document mapping current kinds/spec.type/annotations to future upstream kinds (RFCs #32062/#33060). Captures conditional starting point depending on whether RHDHPLAN-1113 lands before implementation begins.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/spec.md

spec.mdSpec: load testing and error isolation expectations +77/-0

Spec: load testing and error isolation expectations

• Describes performance validation requirements at 5,000+ entities and documents per-entity error resilience guarantees. Notes distribution of responsibilities across RHIDP-15294 (load testing) and RHIDP-15316 (error isolation).

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/performance-resilience/spec.md

tasks.mdTask breakdown aligned to consolidated epics +111/-0

Task breakdown aligned to consolidated epics

• Adds an implementation task plan grouped by surviving epic ownership after RHDHPLAN-1507 consolidation. Includes planned SDK deliverables (interfaces, validation, delta sync manager), adapter contracts, provider updates, and verification steps.

workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md

design.mdDesign for catalog→Neo4j polling sync strategy +258/-0

Design for catalog→Neo4j polling sync strategy

• Details the rationale for scheduled catalog polling as the initial sync mechanism (clean separation from catalog internals) and explicitly evaluates/discards processor side effects and event-driven options for now. Establishes high-level sync behavior, relationship sources, and evolution path toward event-driven sync later.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/design.md

proposal.mdProposal for Neo4j-derived knowledge graph +64/-0

Proposal for Neo4j-derived knowledge graph

• Motivates adding relationship traversal and analytics capabilities not supported by the catalog API. Describes a derived Neo4j index kept in sync from catalog state, including relationship types and example query use cases.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/proposal.md

spec.mdSpec: relationship mapping and incremental polling sync +216/-0

Spec: relationship mapping and incremental polling sync

• Specifies how the adapter polls the catalog, tracks revisions, and creates/updates/deletes nodes and relationships. Defines required relationship derivation inputs (skillcard metadata, entity relations, tags/annotations) and full-sync rebuild behavior.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/specs/relationship-mapping/spec.md

spec.mdSpec: setup docs, schema reference, and example queries +344/-0

Spec: setup docs, schema reference, and example queries

• Specifies documentation deliverables for configuring the adapter (including Secret handling), graph schema reference, manual trigger API usage, and troubleshooting. Establishes expected content and example snippets for user-facing setup materials.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/specs/setup-documentation/spec.md

spec.mdSpec: SkillBundle nodes and INCLUDES relationships +153/-0

Spec: SkillBundle nodes and INCLUDES relationships

• Defines how SkillBundle entities map into graph nodes and how bundle-to-skill inclusion is represented and updated. Includes requirements for deferred relationship creation and bundle update/deletion semantics.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/specs/skill-bundles/spec.md

tasks.mdTask plan for Neo4j sync adapter implementation +89/-0

Task plan for Neo4j sync adapter implementation

• Adds a phased task list for implementing the backend module, incremental sync/revision tracking, node creation, relationship derivation, SkillBundle support, documentation, and testing/observability.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/tasks.md

design.mdDesign for OCI registry ingestion and connector approach +347/-0

Design for OCI registry ingestion and connector approach

• Documents goals/non-goals and key decisions for implementing an OCI Distribution Spec-based connector (e.g., using an oras-js-like client). Establishes expected API interactions (tags/manifests/blobs), auth handling, and integration points with the shared SDK contract.

workspaces/boost/openspec/changes/oci-skill-registry/design.md

proposal.mdProposal for OCI skill registry connector +55/-0

Proposal for OCI skill registry connector

• Explains the need to ingest OCI-packaged skills (skillcard.yaml) into the Backstage catalog. Outlines intended capabilities: multi-registry support, air-gapped-friendly config, and digest-based incremental sync.

workspaces/boost/openspec/changes/oci-skill-registry/proposal.md

spec.mdSpec: digest-based incremental sync via tag→digest cursor +219/-0

Spec: digest-based incremental sync via tag→digest cursor

• Describes change detection using persisted tag-to-digest cursors, including storage expectations (e.g., ConfigMap in Kubernetes). Defines scenarios for detecting new/changed/removed tags and skipping unchanged artifacts to reduce sync time.

workspaces/boost/openspec/changes/oci-skill-registry/specs/digest-based-sync/spec.md

spec.mdSpec: multi-registry + air-gapped configuration requirements +297/-0

Spec: multi-registry + air-gapped configuration requirements

• Defines configuration schema expectations for multiple registry instances and supported auth mechanisms (basic, bearer, docker token, service-account token). Includes requirements for configurable endpoints, Secret-based credentials, and custom CA handling.

workspaces/boost/openspec/changes/oci-skill-registry/specs/multi-registry-config/spec.md

spec.mdSpec: OCI artifact fetching and skillcard validation +175/-0

Spec: OCI artifact fetching and skillcard validation

• Specifies required registry interactions (list tags, fetch manifests, download blobs) and defines error-handling scenarios that continue syncing on per-artifact failures. Establishes extraction/validation behavior for skillcard.yaml across layered images.

workspaces/boost/openspec/changes/oci-skill-registry/specs/oci-artifact-ingestion/spec.md

tasks.mdTask plan for OCI connector implementation +87/-0

Task plan for OCI connector implementation

• Adds a detailed implementation checklist covering OCI client integration, skillcard extraction/validation, entity emission, multi-registry config, digest-based sync, packaging, and testing. Explicitly calls out cross-connector dependencies for endpoints/CA/error isolation.

workspaces/boost/openspec/changes/oci-skill-registry/tasks.md

Other (3) +9 / -0

.openspec.yamlRegister AI catalog entity model OpenSpec change +3/-0

Register AI catalog entity model OpenSpec change

• Adds OpenSpec metadata marking this change set as spec-driven, draft, and timestamped. Establishes the container for proposal/design/spec/task docs under this change.

workspaces/boost/openspec/changes/ai-catalog-entity-model/.openspec.yaml

.openspec.yamlRegister Neo4j knowledge graph OpenSpec change +3/-0

Register Neo4j knowledge graph OpenSpec change

• Adds OpenSpec metadata for the Neo4j knowledge graph sync adapter change set, marking it spec-driven and draft.

workspaces/boost/openspec/changes/neo4j-knowledge-graph/.openspec.yaml

.openspec.yamlRegister OCI skill registry OpenSpec change +3/-0

Register OCI skill registry OpenSpec change

• Adds OpenSpec metadata for the OCI skill registry connector change set, marking it spec-driven and in draft status.

workspaces/boost/openspec/changes/oci-skill-registry/.openspec.yaml

[fullsend-ai-review]

Review — approve

Scope: 24 new OpenSpec files across three feature areas under RHDHPLAN-1507 (ai-catalog-entity-model, neo4j-knowledge-graph, oci-skill-registry). Pure documentation — no code changes.

Assessment

This PR adds well-structured specification documents covering the AI Catalog entity model, Neo4j knowledge graph sync adapter, and OCI skill registry connector. All three feature areas follow the established OpenSpec conventions already in the repo (.openspec.yaml, design.md, proposal.md, specs/*/spec.md, tasks.md). All specs are marked status: draft, which is appropriate.

Strengths:

• Consistent structure — file naming, directory layout, and document formatting all match the patterns used by the existing OpenSpec changes (e.g., pluggable-ai-platform-architecture, ai-chat-interaction-experience).
• Well-documented decisions — each design.md includes numbered decisions with explicit rationale, alternatives considered, and risks. The RHDHPLAN-1507 consolidation notes clearly trace which epics absorbed which scope.
• Security-conscious patterns — the specs prescribe K8s Secret-only credentials with startup validation rejecting plaintext, custom CA bundle support, and configurable endpoints with no hardcoded SaaS URLs.
• Cross-reference integrity — cross-cutting concerns (air-gapped patterns → RHIDP-15316, annotations → RHIDP-15258) are consistently annotated with story IDs, and the 2026-07-13 stakeholder alignment updates are reflected across all three feature areas.
• Scenario-driven specs — all requirements use a structured WHEN/THEN/AND format with concrete examples, making them testable.

Minor observations (non-blocking):

• In oci-skill-registry/tasks.md, task 3.2 says "convert skillcard.yaml to Backstage Resource entity" while the corresponding spec (oci-artifact-ingestion/spec.md) and design.md Decision 4 specify AIResource entity kind. This is a minor wording inconsistency in the task description.
• The Neo4j adapter config examples use env var substitution (${NEO4J_PASSWORD}) rather than the $secret pattern prescribed by the air-gapped spec. This is reasonable since the neo4j adapter is a separate plugin with different security boundaries, but aligning the credential pattern would improve consistency across the Boost platform.

Neither observation affects the correctness of the specifications or blocks merging.

Verdict

✅ Approve — Clean documentation PR adding draft OpenSpec files that follow established repo conventions. No code changes, no security concerns, no blocking issues.

---

Labels: All 24 changed files are under workspaces/boost/openspec/

Previous run

Review — RHDHPLAN-1507 Openspecs

This PR adds 24 new openspec files across three feature areas under workspaces/boost/openspec/changes/: ai-catalog-entity-model, neo4j-knowledge-graph, and oci-skill-registry. The files include proposals, designs, specs, and task breakdowns for the RHDHPLAN-1507 plan.

The overall structure follows established openspec conventions in the repo (.openspec.yaml, proposal.md, design.md, specs/*/spec.md, tasks.md). The specs are thorough, well-organized, and demonstrate careful planning with proper cross-references to JIRA epics and dependency tracking.

Findings

1. rhdh.io/ai-asset-source annotation format inconsistency across specs

Severity: medium · workspaces/boost/openspec/changes/oci-skill-registry/design.md

The annotation scheme spec (annotation-scheme/spec.md) defines rhdh.io/ai-asset-source as connector-name/registry-instance-id (e.g., kagenti/prod-kagenti, oci-skill-registry/default). However, the OCI design doc Decision 4 and the OCI artifact-ingestion spec both show examples using a completely different format: rhdh.io/ai-asset-source: quay.io/myorg/skills — a registry URL path, not the connector-name/instance-id pattern.

These are incompatible formats. If the annotation scheme validator enforces the connector-name/registry-instance-id format, OCI entities using the URL pattern will be rejected. One format should be chosen and used consistently across all three spec areas.

Remediation: Align the OCI connector specs' rhdh.io/ai-asset-source examples to use the oci-skill-registry/<instance-id> format defined in the annotation scheme spec, or update the annotation scheme to allow both patterns.

2. Neo4j BELONGS_TO scenario uses invalid rhdh.io/ai-asset-category value

Severity: medium · workspaces/boost/openspec/changes/neo4j-knowledge-graph/specs/relationship-mapping/spec.md

In the "BELONGS_TO Relationship from Domain Tags and Annotations" section, one scenario states:

WHEN a skill entity has metadata.annotations['rhdh.io/ai-asset-category']: 'devops' THEN the adapter creates a BELONGS_TO relationship to Domain devops

But rhdh.io/ai-asset-category only allows five values: agent, skill, mcp-server, ai-model, model-server — as defined in the annotation scheme spec. devops is not a valid value. This scenario appears to confuse the asset category annotation with a domain/classification tag.

Remediation: The BELONGS_TO derivation from annotations should either reference a different annotation (e.g., a hypothetical domain annotation or metadata.tags with domain:* prefix, which is already covered by the preceding scenario) or this scenario should be removed as a duplicate of the tag-based BELONGS_TO rule.

3. Entity kind inconsistency in OCI connector specs

Severity: low · workspaces/boost/openspec/changes/oci-skill-registry/tasks.md

The OCI design document (Decision 4) and the proposal both specify kind: AIResource with spec.type: skill for emitted entities. However, tasks.md task 3.2 says "convert skillcard.yaml to Backstage Resource entity" (not AIResource), and the multi-registry spec's namespace collision scenario references resource:default/pdf-processor-* entity refs.

This is understandable given the conditional dependency on RHDHPLAN-1113 (which determines whether AIResource or Resource is used), but the internal inconsistency within the OCI spec set could cause confusion during implementation.

Remediation: Add a note to tasks.md task 3.2 clarifying the RHDHPLAN-1113 dependency (as done in the entity-provider-sdk spec), or consistently use AIResource with an inline note about the conditional fallback to Resource.

4. Broken markdown formatting in Neo4j setup documentation spec

Severity: low · workspaces/boost/openspec/changes/neo4j-knowledge-graph/specs/setup-documentation/spec.md

The "Sync failure troubleshooting documented" and "Schema migration documented" scenarios have malformed markdown. The troubleshooting content after the initial code block is rendered as plain text rather than within the scenario's expected output block, and there are stray empty code fence pairs (```) at the end of some scenarios. This will render incorrectly in GitHub's markdown preview.

Remediation: Restructure the nested code blocks using proper indentation or switch to using <details> blocks for the embedded documentation examples.

Summary

The openspecs are comprehensive and demonstrate solid architectural planning. The two medium-severity findings are cross-spec consistency issues that should be resolved before implementation begins to avoid ambiguity. The low-severity findings are minor housekeeping items.

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 37 rules

✅ Cross-repo context

  Explored: repo: redhat-developer/rhdh-chart (sha: 86e63d5d)

  Explored: repo: redhat-developer/rhdh-operator (sha: 3b5e5e5f)

  Explored: repo: redhat-developer/rhdh-local (sha: f22f2dfd)

  Explored: repo: redhat-developer/rhdh (sha: f8639c96)

1. Inconsistent SDK package name 🐞 Bug ⚙ Maintainability

Description

New OpenSpec docs and the air-gapped deployment Helm example instruct users to install or reference
@boost/* packages (e.g., @boost/entity-provider-sdk and
@boost/plugin-boost-backend-module-kagenti), but this repo’s Boost packages and dynamic plugin
artifacts follow the @red-hat-developer-hub/backstage-plugin-boost-* naming and reference
conventions and this PR adds no scaffolding/config for an @boost/* SDK. As written, the guidance
is internally inconsistent and likely to lead to failed installs or non-loadable dynamic plugin
deployments when users copy/paste the examples.

Code

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/entity-provider-sdk/spec.md[R54-61]

+- **WHEN** a developer runs `npm install @boost/entity-provider-sdk`
+- **THEN** the package installs successfully
+- **AND** the package exports: `AIAssetEntityProvider`, `AIAssetCategory`, annotation constants, `validateAIAssetEntity()`, `normalizeAIAssetVersion()`
+
+#### Scenario: Annotation constants exported (RHIDP-15260)
+
+- **WHEN** a developer imports from `@boost/entity-provider-sdk`
+- **THEN** they can use constants: `AI_ASSET_CATEGORY_ANNOTATION = 'rhdh.io/ai-asset-category'`, `AI_ASSET_VERSION_ANNOTATION = 'rhdh.io/ai-asset-version'`, `AI_ASSET_SOURCE_ANNOTATION = 'rhdh.io/ai-asset-source'`

Relevance

⭐⭐⭐ High

Team recently accepted replacing stale @boost/* doc package names with @red-hat-developer-hub scope
(PR #3726).

PR-#3726
PR-#3401

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The cited OpenSpec files explicitly direct users to npm install @boost/entity-provider-sdk and
show a Helm values.yaml example with package: '@boost/plugin-boost-backend-module-kagenti', yet
the workspace’s existing Boost packages are under the
@red-hat-developer-hub/backstage-plugin-boost-* scope and the repo’s own dynamic plugin reference
YAMLs demonstrate that package: entries are expected to be local
dynamic-plugins/dist/...-dynamic paths or OCI-style references containing
...!red-hat-developer-hub-backstage-plugin-...-dynamic identifiers. Together, these citations show
the new docs diverge from established package naming and dynamic-plugin referencing patterns, making
the provided @boost/* strings unlikely to install or load as written.

workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/entity-provider-sdk/spec.md[48-61]
workspaces/boost/openspec/changes/ai-catalog-entity-model/design.md[71-74]
workspaces/boost/plugins/boost-common/package.json[1-3]
workspaces/boost/plugins/boost-toolscope/package.json[1-3]
workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/air-gapped-deployment/spec.md[123-133]
workspaces/boost/dynamic-plugins-image-reference.yaml[14-44]
workspaces/boost/dynamic-plugins-filesystem-reference.yaml[8-21]
workspaces/boost/plugins/boost-backend-module-kagenti/package.json[1-3]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Several new OpenSpec documents (including the air-gapped deployment spec) instruct users to install/reference `@boost/*` packages (e.g., `@boost/entity-provider-sdk` and `@boost/plugin-boost-backend-module-kagenti`), but the repo’s established published package naming uses `@red-hat-developer-hub/backstage-plugin-boost-*` and dynamic plugins are referenced via local `dynamic-plugins/dist/...-dynamic` paths or OCI-style references with `...!red-hat-developer-hub-backstage-plugin-...-dynamic` identifiers. Update the docs so the installation and Helm examples align with the repo’s real package names and dynamic plugin reference formats, or clearly mark `@boost/*` as placeholders and add the necessary package scaffolding/configuration to make them real.

## Issue Context
- The new spec text currently tells readers to `npm install @boost/entity-provider-sdk`, but there is no in-repo evidence/config in this PR that an `@boost/*` SDK exists or will be published.
- The air-gapped deployment spec’s Helm `values.yaml` example uses `package: '@boost/plugin-boost-backend-module-kagenti'`, which does not match the repo’s canonical dynamic plugin configuration examples and is not loadable as written.
- The repo already provides canonical examples for dynamic plugin configuration in the dynamic plugin reference YAMLs; the OpenSpec docs should match those formats so copy/paste deployments work.

## Fix Focus Areas
- workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/entity-provider-sdk/spec.md[48-61]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/design.md[71-80]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/proposal.md[43-53]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md[18-28]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/annotation-scheme/spec.md[64-68]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/air-gapped-deployment/spec.md[123-147]
- workspaces/boost/dynamic-plugins-image-reference.yaml[14-44]
- workspaces/boost/dynamic-plugins-filesystem-reference.yaml[8-21]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[gabemontero]

Thanks for the review. Here's our disposition on each finding:

Finding 1 (medium — rhdh.io/ai-asset-source format inconsistency): ✅ Agree — fixing. The annotation-scheme spec defines connector-name/registry-instance-id as the canonical format. The OCI specs incorrectly use raw registry URLs. We'll align the 3 OCI locations to use oci-skill-registry/<instance-id> format.

Finding 2 (medium — BELONGS_TO with invalid ai-asset-category value): ✅ Agree — fixing. devops is not a valid rhdh.io/ai-asset-category value. This scenario confuses the asset category annotation with domain classification — the preceding tag-based BELONGS_TO scenario already covers domain:devops via metadata.tags. We'll remove the invalid scenario.

Finding 3 (low — Resource vs AIResource in OCI tasks.md): ⏭️ Skipping — intentional. Task 3.2 uses Resource because that's the current kind to implement. The AIResource mapping is pending RHDHPLAN-1113 and is already documented as a conditional dependency in the proposal and design docs. The design describes target state; tasks describe what to build now.

Finding 4 (low — broken markdown in setup-documentation spec): ✅ Agree — fixing. Stray empty code fence pairs and a prematurely truncated ```` block. We'll clean up the markdown formatting.

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 8:17 PM UTC · Ended 8:22 PM UTC
Commit: a04cf01 · View workflow run →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:17 PM UTC · Completed 8:22 PM UTC
Commit: a04cf01 · View workflow run →