Plan/chart reviewers miss ArgoCD HTTPS Helm subchart pitfall when copying OCI umbrella patterns

[ashwinimanoj]

Problem

When a plan introduces an upstream Helm chart dependency for an ArgoCD-managed deployment, and the reviewer has an existing OCI-based umbrella chart in the same GitOps repo as a reference pattern, the plan can silently inherit a broken assumption: that "follow the existing pattern" will work for HTTPS upstream charts too.

It doesn't. OCI chart deps resolve without helm repo add; HTTPS chart deps require explicit repo registration in both CI and ArgoCD's repo-server. The failure mode surfaces only when helm dependency build actually executes — typically in CI mid-PR or at ArgoCD sync time — after the plan is approved and code is merged.

Failure mode

Umbrella wrapper chart is authored by analogy to an existing OCI-based wrapper. CI helm-lint runs helm dependency build and fails with:

Error: no repository definition for https://<upstream>/charts, ...
Please add the missing repos via 'helm repo add'

ArgoCD's repo-server would fail identically at sync time: its built-in helm dependency build cannot resolve HTTPS chart repos that were never registered via argocd-cm or a Repository Secret.

The plan review, executed before any helm tool actually ran against the chart, never exercised this path and passed clean.

Proposed fix

Add an ArgoCD + Helm transport compatibility check across the reviewer/skill surface.

1. shield/agents/architecture-reviewer.md

When a plan adds a new upstream Helm chart, detect its transport (oci:// vs https://). If HTTPS and the plan references an existing chart as an analogy, verify the analog's transport. Flag the mismatch explicitly rather than letting "follow the pattern" carry an invisible assumption.

2. shield/skills/kubernetes/helm-review/check-tables.md

Add: "If chart has HTTPS subchart deps and will be rendered by ArgoCD, require either the multi-source Application pattern (one Application per upstream chart with spec.source.chart + repoURL: https://…) or declarative repo registration (Repository Secret / argocd-cm)."

3. dev-workflow/skills/plan-docs

Prompt for transport when a plan introduces a new upstream Helm chart, and surface the 2025-canonical pattern (per-chart multi-source Application) as the default recommendation for public HTTPS charts. Reserve the umbrella-wrapper pattern for cases that genuinely bundle many charts into one sync unit and are prepared to declaratively register Helm repos in ArgoCD.

Acceptance criteria

• architecture-reviewer has an explicit ArgoCD-Helm-transport check and flags OCI↔HTTPS mismatches on analogical plans.
• kubernetes-helm-review check-tables includes the HTTPS-subchart ArgoCD-compatibility check.
• plan-docs asks about transport when a new upstream chart is introduced and proposes multi-source over umbrella for HTTPS by default.
• README / docs note the OCI-vs-HTTPS distinction as a first-class consideration for future plans.

References

• ArgoCD multi-source Applications: https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/
• Helm chart repository types (OCI and HTTP): https://helm.sh/docs/topics/registries/