/migrate-provider

name: migrate-provider
description: Use when porting a Grafana Cloud product from grafana-cloud-cli (gcx) to gcx, when a bead task references gcx provider migration, or when user says "migrate provider", "port from gcx", "port oncall", "port k6". Not for building providers from scratch — use /add-provider for that.

Migrate Provider from gcx

Port an existing gcx resource client into a gcx provider — core adapter, schema/example registration, CRUD redirect commands, and ancillary subcommands.

**Before starting:** Read `gcx-provider-recipe.md` front to back. The recipe is the source of truth for mechanical steps. This skill wraps it with workflow discipline and orchestration.

**Canonical reference:** `internal/providers/incidents/` — the first full port (adapter + schema + commands + ancillary). Start there for patterns.

When to Use

• Porting a gcx resource client to gcx
• A bead task references gcx provider migration
• User says "migrate provider", "port from gcx", "port oncall", "port k6"

**When NOT to use**: Building a provider from scratch for a product without a gcx client — use `/add-provider` instead.

Prerequisites

Before invoking this skill, ensure:

1. **gcx binary available** — `gcx --version` must succeed. 2. **Grafana context configured** — `gcx config view` must show a working context with server URL and token. 3. **Provider directory exists** — create `internal/providers/{name}` before starting the port. 4. **Live API access** — smoke tests (Phase 4) require a real Grafana instance. Verify connectivity: `gcx --context=<ctx> resources list-types`.

Pipeline Overview

Phase 0: Requirements Gathering (autonomous)
  → context bundle (source + compliance + pattern ref)
      ↓ [no gate — feeds Phase 1]
Phase 1: Design Discovery (interactive, 1A–1D)
  → ADR in docs/adrs/{provider}/
      ↓ [user approval gate]
Phase 2: Spec Planning
  → spec.md + plan.md + tasks.md
      ↓ [user approval gate]
Phase 3: Build
  → agent team (Core + Commands)
  → code files
      ↓ [mise run all gate]
Phase 4: Verification (4A–4E)
  → mise run all + smoke tests + adapter smoke
  → comparison report + recipe update
      ↓ [user approval gate]

| Phase | Agent Strategy | Receives | Produces | Gate | |-------|---------------|----------|----------|------| | 0: Requirements | Lead (autonomous) | gcx source + compliance docs | Context bundle | None (feeds Phase 1) | | 1: Design | Lead (interactive) | Context bundle | ADR | User approves ADR | | 2: Spec Planning | Lead (or `/plan-spec`) | ADR + context bundle | spec.md, plan.md, tasks.md | User approves spec package | | 3: Build | Agent team (Core + Commands) or `/build-spec` | Spec package | Provider code | `GCX_AGENT_MODE=false mise run all` passes | | 4: Verify | Subagent | Comparison report template + spec ACs | Comparison report + recipe update | User approves report |

Phases are **strictly sequential**. Each phase is separated by a gate that **must pass** before the next phase begins. Gates are not optional.

> **Small-provider shortcut:** For providers with 3 or fewer subcommands, > Phase 1 stages 1B–1D may be collapsed into a single proposal. Document > this choice in the ADR.

---

Phase 0: Requirements Gathering (Autonomous)

Phase 0 is fully autonomous — no user interaction required. The output is a context bundle, not a design proposal.

0.1: Read gcx Source

Read the grafana-cloud-cli source for the target provider. Identify every subcommand, API endpoint, type definition, and auth mechanism.

0.2: Check Compliance Documents

Read the following project compliance documents and record which rules apply to the target provider. Use the lint compliance checklist from `conventions.md` as the recording template.

• `CONSTITUTION.md` — CLI grammar, output conventions
• `docs/design/naming.md` — resource, file, config, and flag naming conventions
• `docs/design/command-naming.md` — canonical command verbs and placement
• `docs/design/output.md` — output formats
• `docs/design/exit-codes.md` — exit codes
• `docs/reference/provider-guide.md` — provider interface, adapter wiring
• `docs/reference/provider-discovery-guide.md` — API discovery, design decisions

0.3: Identify Pattern Reference

Identify and read the closest existing gcx provider as a pattern reference:

• **Cloud APIs with separate URLs** → `fleet`
• **Plugin APIs (standard Grafana SA token)** → `slo`
• **gRPC-style POST APIs** → `incidents`
• **Token exchange auth** → `k6`
• **Multi-resource providers** → `oncall`
• **Plugin proxy APIs** → `kg`

0.4: Produce Context Bundle

The context bundle contains: 1. **Source summary** — every gcx subcommand mapped with proposed gcx equivalent or "Deferred" with rationale 2. **Compliance notes** — applicable rules per document with section references (filled checklist from 0.2) 3. **Pattern reference** — which existing provider to follow and why

Phase 0 Gate

> None. Phase 0 feeds directly into Phase 1. The context bundle is an > internal artifact — it does not require user approval.

---

Phase 1: Design Discovery (Interactive)

Phase 1 uses progressive disclosure with four stages. Each stage MUST receive explicit user approval before the next stage begins.

Stage 1A: CLI UX

Propose a command tree with naming and grammar compliance validated against CONSTITUTION.md's CLI Grammar section.

Present to user: command tree, verb choices, alias conventions, naming rationale.

**Gate:** User approves Stage 1A before proceeding.

Stage 1B: Resource Adapters

Specify which resources get TypedCRUD adapters, which remain provider-only commands, the GVK mapping for each adapter resource, and the verb choice rationale (list vs show).

Present to user: adapter classification table, GVK mapping, verb rationale.

**Gate:** User approves Stage 1B before proceeding.

Stage 1C: Auth & Config

Specify ConfigKeys, ConfigLoader usage, environment variable names, and any GCOM/instance looku