/add-provider

name: add-provider
description: Use for the implementation workflow once a capability is already classified as a Grafana Cloud product provider (SLO, OnCall, Synthetic Monitoring, k6, ML, etc.) — provider package, commands, config keys, optional resource adapters. Trigger on "add provider", "new provider", "build the [product] provider". NOT for deciding whether something should be a provider at all, for integration contracts, or for pre-review self-checks — use the repo-local integrate-with-gcx contributor skill for those.

Add Provider

Orchestrates adding a new Grafana product provider — from API discovery through verified implementation. Four stages, worked autonomously: the stage boundaries are checkpoints you satisfy, not approvals you wait for.

When to Use

• User wants to add CLI support for a Grafana Cloud product
• User says "add provider", "new provider", "integrate [product]"
• A bead task references provider implementation

**When NOT to use**: if all you need is standard CRUD on a type that is externally accessible and discoverable on `/apis` — `gcx resources` already covers that through dynamic discovery.

That test is about CRUD, not about the whole command surface. `gcx dashboards` and `gcx alert` are dedicated command trees over products that *are* on `/apis`, because their real operations (restore a version, export a policy tree) are not CRUD verbs. So a K8s-backed product can still warrant commands; run the placement analysis rather than stopping at "it's on `/apis`".

If the answer is a commands-only provider calling the K8s dynamic client, note that `CONSTITUTION.md` § Architecture Invariants makes `internal/providers/dashboards/` the one documented exception (ADR 016) — a second requires explicit human approval and a CONSTITUTION change.

Entry paths

**Invoked from `integrate-with-gcx`** (the placement section already exists — necessity, command path, backend evidence, wiring, readiness). Then:

• Skip Stage 1 entirely if the placement section carries the API surface, auth

model and readiness verdict. Record those findings and move on; do not re-research or re-classify what is already settled, and do not ask for approval of decisions that were made with evidence.

• Skip the Stage 2 decisions it already answers (tier, command surface, and

whether the resource belongs in the `resources` pipeline). Answer only what is genuinely still open.

• The Stage 1 and Stage 2 **blocking approvals** do not apply on this path: you

do not wait for sign-off before implementing. Build autonomously. If something is genuinely unsettled, discover it, or ask one targeted question carrying the evidence and a recommendation — never fall back to a blanket approval gate.

• **Write documents only where they earn their keep.** The Stage 2 artifacts are

conditional on real architectural risk or a repository requirement, not mandatory paperwork:

• **ADR** — only for a decision that is contested, hard to reverse, or departs

from precedent: a new auth model, a client type the repo has not used, an adapter registration, a cross-cutting config change. "Reuse the stack token, hand-rolled HTTP client, commands-only" is the documented default across existing providers — record it in the PR body and move on.

• **Spec / per-stage documents** — only when the work is genuinely staged

across multiple PRs, which is what they exist to make resumable. A provider shipping in one change does not need them.

• **Smoke-test plan** — always, because Stage 4 executes it and the repo

requires real-instance verification. Keep it to the commands you actually implemented. This is a short command list in your working notes, not a standalone document and not a human gate.

• So: do Stage 2d (the smoke-command list) first, then Stage 3, then Stage 4

verification as written. Skipping straight to Stage 3 leaves Stage 4a with no plan to execute.

**Invoked directly** (no placement section): work through all four stages, and check `references/decision-tree.md` first to confirm a provider is the right approach. Autonomy is the same as above — the stage gates are **checkpoints you satisfy, not approvals you wait for**:

• Discover and decide from the repository, the product's API docs and a probe.

Present the research and design findings as you go; do not stop for sign-off.

• Ask only where an unresolved answer would materially change the implementation —

a missing auth model, an API shape you cannot verify, a frozen command name the naming guide and precedent record do not settle. Group those questions, carry the evidence and a recommendation.

• Documents follow the same risk test as above: ADR for contested or

precedent-departing decisions, spec only for genuinely staged work, smoke-test plan always.

• Stop only for a CONSTITUTION conflict with no compliant alternative, a needed

waiver, or a missing backend/auth prerequisite.

The flow, however you got here

contract (proportional)  →  implementation  →  Review

Both entry paths run all three, and none of them is a document or a gate:

• **Contract, before code** — `.claude/skills/integrate-with-gcx/references/contract-and-tests.md`,

sized to the change. If you arrived from `integrate-with-gcx` the contract already exists; use it, don't redo it.

• **Review, before calling it review-ready** —

`.claude/skills/integrate-with-gcx/references/self-review.md`, re-run after every fix push.

That is where the naming, typed-input, output-class, completeness, error, token-cost and test-quality guidance lives. Read those two rather than restating them here.

Workflow

Discover ───────> Design ───────> Implement ──gate──> Verify
   │                  │                  │                  │
   v                  v                  v                  v
research findings  decisions + plan   code per stage   smoke tests

| Stage | Deliverable | Gate | |-------|----