feat(boost): RHDHPLAN-1510 openspecs #3754
Conversation
…tions Create OpenSpec changes covering all 4 epics and 14 stories under RHDHPLAN-1510 (AI Catalog Connector Implementations): - mcp-registry-connector (RHIDP-15313): 3 stories, 3 specs, 7 files Mirror endpoint, TLS/auth hardening, annotation enrichment - rhoai-connector (RHIDP-15314): 4 stories, 3 specs, 7 files Model Registry source, MCP catalog source, deployment config - oci-skill-connector (RHIDP-15315): 5 stories, 3 specs, 7 files Registry discovery, skillcard parsing, incremental sync/scale - connector-shared-infrastructure (RHIDP-15316): 2 stories, 2 specs, 6 files CA bundle resolution, fault isolation and error logging Cross-references RHDHPLAN-1507 framework (entity model SDK, OCI ingestion framework, annotation scheme) and upstream RHDHPLAN-393 (MCP Registry). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
… closure - Add RHDHPLAN-1510 consolidation callouts to MCP Registry and RHOAI connector proposal.md and design.md (RHIDP-15315 closed, scope absorbed by RHIDP-15294 under RHDHPLAN-1507) - Add cross-connector dependency mapping to tasks.md for both connectors (RHIDP-15316 blockers: 15265 endpoint/creds, 15329 CA bundles) - Add cross-connector dependency notes to 6 spec files: mirror-endpoint, auth-tls-hardening, annotation-enrichment, model-registry-source, mcp-catalog-source, deployment-config - Close 5 orphaned RHIDP-15315 stories (15324-15328) with CONSOLIDATED descriptions pointing to absorbing stories under RHIDP-15294 - Create 7 Jira Blocks links for RHDHPLAN-1510 cross-connector deps Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ector openspecs RHDHPLAN-404 supersedes Model Registry (Kubeflow API) integration for the RHOAI connector. This connector now only handles MCP catalog ingestion. Model Registry integration is handled under RHDHPLAN-404. Changes: - Remove model-registry-source spec (entire Kubeflow scope) - Rewrite design.md: MCP-catalog-only decisions, remove RHDHPLAN-1113 conditional (irrelevant without model entity kinds) - Rewrite proposal.md: remove Model Registry Source and Version Normalization sections - Rewrite tasks.md: remove 15 Model Registry tasks, simplify deployment config and testing sections - Rewrite deployment-config spec: remove Model Registry toggle/endpoint scenarios - Fix mcp-catalog-source spec: remove stray Model Registry reference - Preserve MCP Registry connector stakeholder alignment (Step 1) Stakeholder alignment (2026-07-13): MCP server entity kind correction (Resource -> API with spec.type: mcp-server), RHDHPLAN-393/404 dependency context, MCP resource mapping deferred for RHDH 2.1. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
- Fix OCI Skill connector entity mapping: Resource/ai-skill → AIResource/skill (design.md, proposal.md, tasks.md, skillcard-parsing/spec.md) - Add RHDHPLAN-1507 consolidation notes to OCI Skill connector files (RHIDP-15315 closed → scope under RHIDP-15294/RHDHPLAN-1507) - Fix connector-shared-infrastructure cross-reference: replace closed RHIDP-15315 with RHIDP-15294 (RHDHPLAN-1507) - Fix RHOAI tasks.md: RHIDP-15321 (version normalization) remains in scope per Jira; add task section with 7 tasks - Add RHIDP-15266 reference app-config openspec: new spec under connector-shared-infrastructure/specs/reference-app-config/ and 7 tasks in tasks.md - Renumber cross-references and connector-integration task sections Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
|
🤖 Finished Review · ✅ Success · Started 7:20 PM UTC · Completed 7:37 PM UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3754 +/- ##
=======================================
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
*This pull request uses carry forward flags. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
PR Summary by Qododocs(boost): Add OpenSpecs for AI catalog connectors and shared infrastructure
AI Description
Diagram
High-Level Assessment
Files changed (27)
|
Code Review by Qodo
Context used✅ Compliance rules (platform):
37 rules✅ Cross-repo context Not relevant to this PR:
redhat-developer/rhdh Not relevant to this PR:
redhat-developer/rhdh-chart Not relevant to this PR:
redhat-developer/rhdh-operator Not relevant to this PR:
redhat-developer/rhdh-local 1.
|
rhdh-qodo-merge
Bot
added
documentation
Review —
|
| Bundle | Config key | Source file |
|---|---|---|
| Shared infra design | tls.caFile / tls.caSecret |
connector-shared-infrastructure/design.md |
| Shared infra reference app-config | tls.ca (MCP), tls.caBundle (RHOAI), caBundlePath (OCI) |
connector-shared-infrastructure/specs/reference-app-config/spec.md |
| MCP Registry | tls.ca |
mcp-registry-connector/design.md, specs/auth-tls-hardening/spec.md |
| RHOAI | tls.caBundle |
rhoai-connector/design.md |
| OCI Skill | caBundlePath (not under tls: key) |
oci-skill-connector/specs/incremental-sync-scale/spec.md |
The shared infra design.md defines caFile/caSecret, but the reference-app-config/spec.md within the same bundle uses ca — this is a self-contradiction. If these connectors share a loadCaBundle() utility reading from a standard config path, the specs must agree on what that path is.
Remediation: Standardize on one naming convention for the CA bundle config key across all 4 bundles. Recommend tls.caFile (per the shared infra design.md canonical definition) for file-path-based CA and tls.caSecret for env-var-based CA. Update all connector specs and the reference app-config spec to use the same key names.
2. Pseudocode variable name mismatch in MCP Registry design
Severity: Low · Category: correctness
In mcp-registry-connector/design.md, Decision 3 (CA Bundle Loading), the code sample defines const caBundle = loadCaBundle(config, 'mcpRegistry') but then passes ca: caBundlePEM to https.Agent — caBundlePEM is undefined in this scope. Compare with connector-shared-infrastructure/design.md which correctly uses ca: caBundle in its equivalent example.
Remediation: Change ca: caBundlePEM to ca: caBundle in the MCP Registry design's Decision 3 code sample.
3. Fault isolation spec doesn't cover connect() phase
Severity: Low · Category: edge-case-gap
The createProviderWrapper() in connector-shared-infrastructure/design.md wraps provider.run() in try/catch for process-level isolation. However, EntityProvider.connect() failures are not addressed. If connect() throws during module initialization (e.g., invalid config, network failure on initial validation), the error propagates up to the module's init() and could affect other modules registered in the same backend.
Remediation: Document whether connect() failures should also be caught by the wrapper or handled at the module registration level in init(). Add a scenario in specs/fault-isolation/spec.md covering connect-phase errors.
4. Referenced openspec ai-catalog-entity-model does not exist
Severity: Low · Category: cross-reference
Multiple files reference workspaces/boost/openspec/changes/ai-catalog-entity-model/ for the annotation scheme and SDK validation (e.g., mcp-registry-connector/proposal.md, rhoai-connector/proposal.md). This directory does not exist in the repository. Presumably it is planned future work under RHDHPLAN-1507.
Remediation: This is expected for pre-implementation cross-references. No action required unless the referenced openspec is never created — in that case, these references become stale.
Previous run
Review — comment
This PR adds 27 new OpenSpec specification files across 4 directories under workspaces/boost/openspec/changes/ for the RHDHPLAN-1510 AI catalog connector work. The specifications cover connector shared infrastructure, MCP Registry connector, OCI Skill connector, and RHOAI connector. All files are new additions — no production code is modified.
The specifications are thorough and well-structured, covering design decisions, behavioral specs with WHEN/THEN/AND scenarios, and detailed task breakdowns. Several internal consistency issues and organizational concerns are worth addressing before implementation begins.
Findings
Medium: Shared utility package name inconsistency
Files: connector-shared-infrastructure/design.md, mcp-registry-connector/design.md
The shared utility package is named @boost/connector-utils with path plugins/boost-connector-utils/ in the connector-shared-infrastructure design document. However, mcp-registry-connector/design.md imports the shared utility as @boost/plugin-boost-backend-shared — a completely different package name. Implementers following the MCP Registry design would import from a package that doesn't match the shared infrastructure spec.
Remediation: Standardize the shared utility package name across all four spec areas. Pick one name (@boost/connector-utils or @boost/plugin-boost-backend-shared) and update all references.
Medium: loadCaBundle API signature mismatch between specs
Files: connector-shared-infrastructure/design.md, mcp-registry-connector/design.md
The connector-shared-infrastructure design defines the function signature as:
function loadCaBundle(config: Config, connectorId: string): Buffer | undefined;But the MCP Registry connector design shows a completely different usage pattern:
const caBundlePEM = caBundlePath ? await loadCaBundle(caBundlePath, logger) : undefined;These take different parameter types (Config + connectorId vs. path string + logger) and the second version is async while the first is not. An implementer building the shared utility from one spec would produce an API incompatible with the other spec's usage.
Remediation: Align the loadCaBundle function signature and usage across the shared infrastructure and consumer connector specs.
Medium: OCI Skill Connector spec placed under closed epic
Files: oci-skill-connector/ directory
The PR is titled "RHDHPLAN-1510 openspecs" but all four oci-skill-connector spec files acknowledge that RHIDP-15315 (OCI Skill Registry Connector) was closed on 2026-07-08 and absorbed into RHIDP-15294 under RHDHPLAN-1507. Including these specs under a RHDHPLAN-1510 PR creates organizational confusion about Jira ownership. The existing feasibility report at specifications/JIRA-analysis/RHDHPLAN-1510-feasibility-report.md also documents this consolidation.
Remediation: Either move the oci-skill-connector openspec to a separate PR under RHDHPLAN-1507, or update the PR scope description to clarify that this includes specs for work that migrated from RHDHPLAN-1510 to RHDHPLAN-1507.
Medium: Per-connector directory granularity departs from established convention
Files: All 4 new directories under openspec/changes/
The existing openspec structure documented in AGENTS.md says "One directory per capability area" and lists 5 broad capability directories (e.g., security-safety-governance, agent-creation-discovery). The 4 new directories represent individual connectors — a finer-grained unit than capability areas. The existing pattern would place all connector specs under a single directory (e.g., ai-catalog-connectors) with specs/ subdirectories per connector.
Remediation: Consider whether these 4 directories should be consolidated into one or two capability-area directories matching the established pattern, or document the expanded organizational convention in AGENTS.md.
Low: Broken cross-reference directory name
Files: mcp-registry-connector/proposal.md, rhoai-connector/proposal.md
Both files reference workspaces/boost/openspec/changes/cross-connector-shared-infrastructure/ in their cross-references section, but the actual directory name in this PR is connector-shared-infrastructure/ (without the "cross-" prefix). These are broken internal links.
Low: Missing "Verify" section in all tasks.md files
Files: All 4 tasks.md files
All existing openspec tasks.md files end with a ## N. Verify section containing verification tasks (e.g., "Verify catalog entities appear...", "Verify config write → immediate invalidation..."). None of the 4 new tasks.md files include this section, breaking the established pattern.
Low: AGENTS.md not updated with new directories
File: workspaces/boost/AGENTS.md
AGENTS.md explicitly lists the openspec directory structure with 5 entries. This PR adds 4 new directories without updating AGENTS.md, widening the gap between documentation and actual content. (Note: the existing ai-catalog-frontend directory is also missing from the AGENTS.md listing.)
Summary
The specifications are comprehensive draft documents covering design decisions, behavioral specs, and implementation tasks for the RHDHPLAN-1510 connector work. The main concerns are internal consistency (package name and API signature mismatches between the shared infrastructure spec and its consumers) and organizational conventions (directory granularity, missing verify sections, unlinked cross-references). These should be resolved before implementation begins to prevent confusion, but they don't block merging specification documents.
Labels: PR adds OpenSpec documentation files for the boost (augment) workspace AI catalog connectors.
fullsend-ai-review
Bot
added
requires-manual-review
|
Thanks for the review. Here's our disposition on each finding: Finding 1 (medium — shared utility package name inconsistency): ✅ Agree — fixing. The canonical name is Finding 2 (medium — Finding 3 (medium — OCI Skill Connector under closed epic): ⏭️ Skipping — organizational concern, not a content issue. The consolidation notes in every OCI spec file already document the migration from RHDHPLAN-1510 to RHDHPLAN-1507. The specs live here because this is where the connector work originated. Cross-references are clear. Finding 4 (medium — per-connector directory granularity): ⏭️ Skipping — organizational preference. Per-connector directories are more navigable during implementation than one monolithic directory. Convention can be revisited later. Finding 5 (low — broken cross-reference directory name): ✅ Agree — fixing. Two files reference Finding 6 (low — missing "Verify" sections in tasks.md): ⏭️ Skipping. The tasks.md files already contain verification tasks inline throughout (e.g., "Verify entities appear in Backstage catalog after sync", "Verify peak memory usage stays below 500 MB"). They just don't have a dedicated Finding 7 (low — AGENTS.md not updated): ⏭️ Skipping — the AGENTS.md directory listing is already out of date (missing |
… package - Replace @boost/plugin-boost-backend-shared with @boost/connector-utils (4 locations) - Align loadCaBundle() call signature to canonical loadCaBundle(config, connectorId) pattern - Fix cross-reference directory name: cross-connector-shared-infrastructure → connector-shared-infrastructure (2 locations) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: gabemontero <gmontero@redhat.com>
|
|
🤖 Finished Review · ✅ Success · Started 8:30 PM UTC · Completed 8:41 PM UTC |
fullsend-ai-review
Bot
added
requires-manual-review
1 participant
Hey, I just made a Pull Request!
These are the openspec markdowns through tasks.md for all the RHIDP epics / stories under RHDHPLAN-1510
✔️ Checklist