/add-provider

name: add-provider
description: Use when adding a new Grafana Cloud product provider to gcx (SLO, OnCall, Synthetic Monitoring, k6, ML, etc.), or when the user says "add provider", "new provider", or "integrate [product]".

Add Provider

Orchestrates adding a new Grafana product provider — from API discovery through verified implementation. Four stages with human approval gates.

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 the product exposes a K8s-compatible `/apis` endpoint, it already works with `gcx resources` — no provider needed.

**First**: Check `references/decision-tree.md` to confirm a provider is the right approach.

Workflow

Discover ──gate──> Design ──gate──> Implement ──gate──> Verify
   │                  │                  │                  │
   v                  v                  v                  v
research report    ADRs + spec       code per stage     smoke tests

| Stage | Deliverable | Gate | |-------|-------------|------| | 1. Discover | `docs/research/` report | User approves findings | | 2. Design | ADRs + spec + smoke test plan | User approves design | | 3. Implement | Code (one stage at a time) | `mise run all` passes per stage | | 4. Verify | Smoke tests + architecture doc updates | All checks green |

Prerequisites

Confirm with the user before starting:

• **Product name** — which Grafana product to integrate
• **Access** — do they have a running Grafana instance with the product enabled?
• **Scope** — full provider or single resource type first?

---

Stage 1: Discover

> **Guide**: `docs/reference/provider-discovery-guide.md` Sections 1.1–1.6

1a. Gather User Context

Before autonomous research, ask what the user already knows:

1. Source code access — which repo? 2. API documentation — OpenAPI specs, Grafana docs URLs? 3. Terraform resources — does the Terraform provider support this product? 4. Go SDK — existing Go client library? 5. Known quirks — non-standard auth, async ops, unusual pagination?

Use answers to skip known areas and focus research on gaps.

1b. Research

Follow `provider-discovery-guide.md` Sections 1.1–1.6:

• Map API surface (base path, auth, endpoints, pagination)
• Check existing tooling (Terraform schemas, Go SDK)
• Inspect source code (undocumented endpoints, enum values)
• Identify auth model
• Map resource relationships
• Test API behavior with real calls

1c. Write Research Report

Write findings to `docs/research/YYYY-MM-DD-{product}-provider.md` using the template at `docs/_templates/research.md`. Must include:

• API endpoints and response shapes discovered
• Auth model analysis
• Resource relationships
• At least one successful API call result
• Confidence assessment per finding

Gate: User Approves Research

Present the research report. Do not proceed to design until approved.

---

Stage 2: Design

> **Guide**: `docs/reference/provider-discovery-guide.md` Section 2

2a. Design Decisions

Answer each decision from the guide, grounded in research findings:

1. **Auth strategy** — reuse Grafana token or separate credentials? 2. **Client type** — plugin API, K8s API, or external service? 3. **Envelope mapping** — how do API objects map to K8s envelope? 4. **Command surface** — CRUD + which beyond-CRUD commands? 5. **Package layout** — flat or subpackaged? 6. **Staging** — how to break into shippable stages?

For beyond-CRUD commands: brainstorm based on real APIs found in research (status, timeline, validation, etc.). Present options to user — include "CRUD only for now" as an option.

2b. Write ADRs

For each significant decision, write an ADR in `docs/adrs/{product}-provider/NNN-{decision}.md` using the template at `docs/_templates/adr.md`. At minimum, create ADRs for:

• Auth strategy choice
• Client type choice (plugin API vs K8s vs external)

Other decisions can be captured in the spec if they're straightforward.

2c. Write Spec

Write the implementation plan in `docs/specs/{product}-provider/`:

• Top-level plan with all stages, file tree, and decisions summary
• Per-stage docs with scope, files to create, and acceptance criteria

Reference implementations for plan structure:

• SLO: `docs/specs/slo-provider/2026-03-04-slo-provider-plan.md`
• Synth: `docs/specs/synth-provider/2026-03-06-synth-provider-plan.md`

2d. Write Smoke Test Plan

**Every stage doc MUST include a Verification section** with concrete smoke test commands using real values (not placeholders). These are executed in Stage 4 after implementation.

Example pattern (replace with real product/resource names in actual spec):

# Provider appears in list
gcx providers | grep {name}

# Config secrets are redacted
gcx config view | grep {name}

# CRUD operations work
gcx {name} {resource} list
gcx {name} {resource} get <test-id>
gcx {name} {resource} push ./testdata/{resource}.yaml
gcx {name} {resource} pull -d ./tmp/
gcx {name} {resource} delete <test-id> --yes

# Unified resources path works
gcx resources get {alias}

Gate: User Approves Design

Present ADRs and spec. Do not proceed to implementation until approved.

---

Stage 3: Implement

> **Guide**: `docs/reference/provider-guide.md` (Steps 1–7) > **UX Guide**: `docs/design/`

Implement one stage at a time per the approved spec. Each stage's doc is self-contained enough to resume in a fresh session.

If `/build-spec` or `/build-task` skills are available, use them to drive implementation. Otherwise, follow `provider-guide.md` Steps 1–7 directly. Summary of the key steps:

1. Provider interface + `init()` + `configLoader` (copy from SLO reference) 2. Config keys + validation 3. Commands with UX compliance 4. Types + client + adapter per resource type 5. Register (blank import + ResourceAdapter) 6. Tests (interface compliance, adapter round-trip, client h