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.

1. Provider directory exists — create internal/providers/{name} before

starting the port.

1. 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]

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 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:

• Plugin APIs (standard Grafana SA token) → slo
• gRPC-style POST APIs behind a plugin proxy → fleet
• gRPC-style POST APIs → incidents
• Cloud APIs on a separate URL, with token exchange → k6
• Multi-resource providers → oncall
• Plugin proxy APIs → kg

0.4: Produce Context Bundle

The context bundle contains:

1. Source summary — every legacy CLI subcommand mapped to its 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 lookup requirements.

Present to user: config key table, env var names, auth flow diagram.

Gate: User approves Stage 1C before proceeding.

Stage 1D: Architecture

Specify package layout, client construction pattern, shared helpers, and the auth subpackage structure (if the provider uses multiple subpackages).

Present to user: package tree, client pattern, helper inventory.

Gate: User approves Stage 1D before proceeding.

Small-provider shortcut: For providers with 3 or fewer subcommands,
collapse stages 1B–1D into a single combined proposal. All content must
still be present — only the number of approval rounds is reduced.

Phase 1 Output: ADR

Write an ADR documenting all design decisions from stages 1A–1D to docs/adrs/{provider}/. The ADR MUST be approved by the user before proceeding to Phase 2.

Phase 1 Gate

STOP. Do not begin Phase 2 until:

1. All four stages (1A–1D) have received explicit user approval
2. The ADR exists in docs/adrs/{provider}/ and is approved by the user

If the user has NOT approved a stage, block and re-present it for feedback.

Phase 2: Spec Planning

Phase 2 produces three documents in spec format:

1. spec.md — functional requirements + acceptance criteria (Given/When/Then)
2. plan.md — architecture decisions + HTTP client reference section
3. tasks.md — dependency graph + waves + per-task deliverables

plan.md: HTTP Client Reference (MANDATORY)

plan.md MUST include the HTTP client reference section from commands-reference.md. This section contains:

• Endpoint table (method, path, purpose, notes)
• Auth helper signature
• Client construction pattern with exact field names

This prevents response envelope hallucination — the most impactful bug class discovered during provider migrations.

tasks.md: Verification Tasks (MANDATORY)

tasks.md MUST include smoke test design as explicit verification tasks. Each show/list command MUST have a smoke test task entry specifying all four output formats (json, table, wide, yaml).

Optional: /plan-spec Integration

When /plan-spec is available, Phase 2 SHOULD use it. When /plan-spec is not available, Phase 2 MUST produce the same document format manually. /plan-spec is an optional accelerator, not a dependency.

Phase 2 Gate

STOP. Do not begin Phase 3 until:

1. All three documents (spec.md, plan.md, tasks.md) exist with YAML
frontmatter, FR-NNN numbering, and Given/When/Then acceptance criteria
2. plan.md contains the HTTP client reference section
3. tasks.md contains smoke test verification tasks for all output formats
4. The user has explicitly approved the spec package

Phase 3: Build

Phase 3 executes tasks.md waves in order, with mise run lint as a checkpoint between each task.

Builder Agent Rules

Builder spawn prompts (see templates/builder-prompts.md) MUST include:

"Do NOT infer response envelope shapes. Copy deserialization code verbatim
from the grafana-cloud-cli source. If the source does
json.Unmarshal(body, &slice), the new client MUST do the same — never
wrap in a struct unless the source does."

Builder spawn prompts MUST NOT include verification task details — no smoke commands, no expected comparison outputs, no pass/fail criteria from the comparison report template.

Agent Team Orchestration

The Build phase uses an agent team with two teammates:

• Build-Core — owns types, client, adapter, resource_adapter files.

Must complete before Build-Commands begins.

• Build-Commands — owns provider registration and CLI command files.

Starts only after Build-Core signals completion.

File Ownership Table

Teammates MUST NOT modify files outside their ownership boundary.

Integration/Wiring Task

The integration task MUST explicitly include:

1. Wire Commands() and TypedRegistrations()
2. Add blank import in cmd/gcx/root/command.go
3. Fix import cycles introduced by subpackage references
4. Fix variable name collisions from package aliasing
5. Run mise run lint and fix all new issues

Optional: /build-spec Integration

When /build-spec is available, Phase 3 SHOULD use it. When /build-spec is not available, Phase 3 MUST use the agent team orchestration described above. /build-spec is an optional accelerator, not a dependency.

Phase 3 Gate

STOP. Do not begin Phase 4 until:

GCXAGENTMODE=false mise run all exits 0 with no lint errors and all tests
passing.

Run this command after both Build teammates complete. If it fails, fix the
root cause before proceeding — do not proceed with a failing build.

Phase 4: Verification (4A–4E)

Phase 4 MUST execute in this exact order. No step may be skipped.

Step 4A: Build Gate

Run GCXAGENTMODE=false mise run all and confirm exit 0.

Step 4B: Smoke Tests (MANDATORY)

Smoke tests are MANDATORY for every show/list command. Each command MUST be tested with ALL FOUR output formats: -o json, -o table, -o wide, -o yaml.

Smoke tests MUST NOT be silently skipped or quietly downgraded. If no live instance is available, report every smoke test as UNVERIFIED with that reason and do NOT assert parity with the legacy CLI — an unverified port is an honest state, a claimed-but-untested one is not. Report the blocker to the user.

CTX={context-name}

for fmt in json table wide yaml; do
  GCX_AGENT_MODE=false bin/gcx --context=$CTX {resource} list -o $fmt > /dev/null 2>&1 \
    && echo "list $fmt: OK" || echo "list $fmt: FAIL"
done

Step 4C: Adapter Smoke (MANDATORY)

Every TypedCRUD resource MUST be verified via the adapter path:

• resources list-types — registration visible
• resources get {alias} — envelope + deserialization working

Step 4D: Spec Compliance

Check every acceptance criterion from spec.md. Report SATISFIED or UNSATISFIED with file:line evidence.

Step 4E: Recipe Update (MANDATORY)

Update gcx-provider-recipe.md with:

1. Status tracker entry — a new row for the ported provider
2. Gotchas section — problems discovered during smoke tests (or explicit

"No new gotchas" if none)

1. Pattern corrections — if any recipe step was unclear or incorrect

Comparison Report

Produce a structured comparison report using templates/comparison-report.md. Present it to the user for review.

Phase 4 Gate

STOP. Do not declare the migration complete until:

1. The comparison report has been produced and presented to the user
2. Every discrepancy is either justified with written rationale or fixed
3. The recipe update (Step 4E) is complete
4. The user has explicitly approved the comparison report

Red Flags — STOP and Check

When you notice any of these during execution, stop and take the corrective action before continuing.