/migrate-provider

name: migrate-provider
description: >-
  Reference for porting a Grafana Cloud product from the legacy
  grafana-cloud-cli into a gcx provider — adapter, schema/example registration,
  CRUD redirect commands. HUMAN-DRIVEN — this skill is outside the
  integrate-with-gcx v1 autonomous workflow and must not be run end to end
  unattended because its non-registration steps have not been fully audited.
  Use when a human is deliberately driving a port and says "migrate provider",
  "port from gcx", "port oncall", "port k6". Not for building providers from
  scratch — use /add-provider. Recheck present-day placement before porting.

Migrate a Provider from the Legacy CLI

Port an existing `grafana-cloud-cli` resource client into this repository's gcx provider system — core adapter, schema/example registration, CRUD redirect commands, and ancillary subcommands.

> **Read this before the recipe. A human drives this skill; it is not covered by > the integrate-with-gcx v1 workflow.** In these instructions, "legacy CLI" > means `grafana-cloud-cli`, whose binary was also named `gcx`; "gcx" means this > repository's `bin/gcx`. Use `bin/gcx` for the build under review, and name the > legacy binary's own path explicitly. > > Of the recipe's mechanical steps, only the registration flow > (`providers.Register()` + `TypedRegistrations()`, and the `TypedCRUD` > `Descriptor`/`Aliases` fields) has been checked against current code. Treat the > rest as unaudited and verify as you go.

**Before starting:** read `gcx-provider-recipe.md` front to back for the mechanical steps, subject to the caveat above. This skill wraps it with workflow discipline and orchestration.

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

When to Use

• Porting a legacy `grafana-cloud-cli` resource client into current gcx
• A bead task references legacy 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 legacy CLI client — use `/add-provider` instead.

Relationship to integrate-with-gcx

One-directional, so the two skills cannot bounce a port back and forth:

• **Recheck placement before porting.** A legacy client proves that an API

existed; it does not prove that the provider tier is still the right home. Check current `/apis` CRUD coverage and inventory the non-CRUD operations. A human confirms provider-tier placement before Phases 0-4 continue.

• **`integrate-with-gcx` does not route work here**, because of the status note

above: it tells the user a port needs a human to drive and stops. Reach this skill by invoking it deliberately.

• **Call back into two sections only**, not the whole skill: the naming pass on

the ported command surface (`self-review.md` T7 — released names are frozen, and a port is where a legacy name most often gets carried in), and the diff-triggered review before requesting human review (`self-review.md`). Contract worksheets and the general readiness workflow do not apply to a port; the placement recheck above is still required.

• Read from the checkout at

`.claude/skills/integrate-with-gcx/references/self-review.md`, which carries T7 and the trigger table.

Prerequisites

Before invoking this skill, ensure:

1. **Current gcx binary built** — `bin/gcx --version` must succeed. 2. **Grafana context configured** — `bin/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: `bin/gcx --context=<ctx> resources list-types`.

Pipeline Overview

Phase 0: Requirements Gathering (autonomous)
  → context bundle (legacy 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
      ↓ [GCX_AGENT_MODE=false mise run all gate]
Phase 4: Verification (4A–4E)
  → GCX_AGENT_MODE=false mise run all + smoke tests + adapter smoke
  → comparison report + recipe update
      ↓ [user approval gate]

| Phase | Agent Strategy | Receives | Produces | Gate | |-------|---------------|----------|----------|------| | 0: Requirements | Lead (autonomous) | legacy 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 the Legacy CLI 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 pro