/integrate-with-gcx

name: integrate-with-gcx
description: >
  Guides a contributor and their coding agent through adding or extending a
  capability in the grafana/gcx codebase: deciding whether a new command is
  needed and where it belongs (provider, datasource kind, resource adapter,
  cloud command, or bundled skill), designing the command's agent-facing
  contract (naming, typed inputs, output protocol class, completeness,
  errors, token cost), implementing with shared-infrastructure reuse, and
  catching the defect classes that recur in gcx review before a human looks.
  Use when working inside a grafana/gcx checkout to add, extend, or review a
  gcx capability. Trigger on phrases like "integrate with gcx", "add my
  product to gcx", "new gcx command", "expose this API through gcx", or "get
  my gcx PR ready for review". NOT for operating a Grafana instance with gcx
  — use the gcx skill or a product skill (slo-manage, synth-manage-checks,
  create-dashboard). NOT for installing or configuring gcx — use setup-gcx.

Integrate a Capability with gcx

**Work autonomously.** Inspect the repo, decide, show the decision, keep going. This skill has no approval gates. Ask only when repository evidence genuinely cannot settle something ([Asking](#asking)).

The premise everything follows from: **the commands you add are tools other agents route on.** `Use`/`Short`/`Long`/`Example`, flag help, token cost and hints are surfaced verbatim through `gcx commands` and `gcx help-tree` — that metadata is an operational contract, not decoration. Names are frozen within a major version, so the path you pick is the path forever.

| Mode | You are here when | |---|---| | [**Place**](#mode-place) | where this belongs is undecided | | [**Build**](#mode-build) | placement is known — you decided it, the user stated it, or a sibling skill sent you | | [**Review**](#mode-review) | there is already a branch or PR to get review-ready |

Start with `mise run build`, then `bin/gcx commands >/dev/null && echo ok`. Read `AGENTS.md` — the entry point for the governing docs; paths cited below are cited directly, including `docs/plans/` and `docs/research/`, which its map does not list. Use `bin/gcx` for your own shell checks (exercise the binary you just built, not a stale installed one); everything *user-facing* you author — `Example:` fields, help text, docs — says `gcx`.

Mode: Place

> Detail: [references/placement-and-readiness.md](references/placement-and-readiness.md)

Inventory the tree first — a new leaf competes for every agent's attention:

bin/gcx help-tree
bin/gcx commands --flat -o json
bin/gcx resources list-types
bin/gcx providers list

Settle four things and show them as a short **placement section** (bullets, not a document):

• **Necessity** — reuse / extend / consolidate with a sibling / new leaf / not

gcx. For a new leaf, name the nearest existing sibling and the one sentence an agent would use to choose between them. If a person who knows the tree can't say which command applies, an agent can't either.

• **Path** — from `docs/design/command-naming.md` plus precedent in the real tree

and `docs/plans/list-subject-verdicts.md`.

• **Backend + wiring** — what serves the data, verified by a probe rather than

assumed, and which wiring carries it. A probe that is unavailable, inconclusive or outside the target you were placed in scope for is reported `UNVERIFIED` — never run, and never read as a negative result. `gcx api` is a diagnostic fallback, never the integration target.

• **Readiness** — ready / backend prerequisite (named owner) / bounded bootstrap

/ not gcx. Unknowns block by **material risk**, not by category: an unknown bearing on API ownership or stability, auth/RBAC, security, mutation safety, correctness (including an unseen route or payload) or bounded completeness means **backend prerequisite**, and for those there is no "ready, pending verification". Any other unknown is recorded `UNVERIFIED` with its probe and the work continues. Full list in [references/placement-and-readiness.md](references/placement-and-readiness.md). Product teams own their API shape, auth, limits and domain data reduction; gcx wraps APIs, it does not fix them.

Missing information does not stop you: discover it, or ask one targeted question.

**What happens next depends on the readiness outcome.** Two of the four are terminal — Place is the whole deliverable and there is nothing to implement:

| Readiness outcome | Next | |---|---| | **ready** | continue | | **bounded bootstrap** | continue, within the ceiling the outcome requires | | **backend prerequisite** *with an explicitly viable read-only slice* | continue, on that slice only | | **backend prerequisite** *without a viable slice* | **stop.** Report the boundary, the missing prerequisite and its named owner | | **not gcx** | **stop.** Report the boundary and the owner; write no contract and no code |

Do not invent a contract or an implementation for a terminal outcome. Concluding "not gcx" and then building anyway is the expensive version of getting placement wrong.

For the outcomes that continue, the flow is the same four steps whether you implement in Build or hand the work to a sibling skill:

Place  →  contract (Build, sized to the change)  →  implementation  →  Review

Handing off after Place and skipping straight to a sibling's Stage 3 means the naming, typed-input, output-class, completeness, error and test-quality guidance never runs — which is most of what this skill is for. Cover the contract first, pass it forward with the placement section, and come back for Review before the work is called review-ready. None of those steps is a human gate.

Mode: Build

> Detail: [references/contract-and-tests.md](references/contract-and-tests.md)

Cover the contract before writing code — purpose, stability, use signals and when-NOT-to-use, routing metadata, every input typed with constraints and a defaulted