gcx
AGENTS.md819 starsChanged 18 days agoApache-2.0View on GitHub
Lightweight map for autonomous coding agents. Read this first, then navigate to specific docs on demand. gcx is a unified CLI for managing Grafana resources. It operates in two tiers: (1) a K8s resource tier that uses Grafana 12+'s Kubernetes-compatible API via k8s.io/client-go for dashboards, folders, and other K8s-native resources, and (2) a Cloud provider tier with pluggable providers for Grafana Cloud products (SLO, Synthetic Monitoring, IRM, Fleet Management, etc.) that use product-specific REST APIs. Built in Go, it uses…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- contributeSkill
- create-rfcSkill
- generate-slideSkill
- propose-featureSkill
- releaseSkill
- review-prSkill
- review-rfcSkill
- update-rfcSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 31
Options pattern: Every command uses opts struct + setup(flags) + Validate() + constructor
- Very specific: line 37
PromQL via promql-builder: Use github.com/grafana/promql-builder/go/promql for PromQL construction, not string formatting (see Pattern 14 …
- Very specific: line 39
Explore links are required on query commands: Every query-class datasource leaf command must build a Grafana Explore URL in …
- Very specific: line 62
Prefer table-driven tests.
- Very specific: line 66
Start with project structure for module boundaries.
- Distinctive: line 87
Check work against these docs during planning, design, and implementation — in order of strictness.
- Distinctive: line 97
Planning/design: Check VISION (2) and CONSTITUTION (1) — are we building the right thing, and can we build it within the rules?
- Distinctive: line 98
Implementation: Check DESIGN (3) and ARCHITECTURE (4) — does the code follow UX rules and structural patterns?
- Distinctive: line 128
Run this checklist before every commit (not only before PR/push):
- Very specific: line 149
Test generator changes with go test ./scripts/....
- Distinctive: line 161
When creating or commenting on GitHub issues, always anonymize system-specific details.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
gcx — Agent & Developer Entry Point
Lightweight map for autonomous coding agents. Read this first, then navigate to specific docs on demand.
Quick Start
gcx is a unified CLI for managing Grafana resources. It operates in two tiers: (1) a K8s resource tier that uses Grafana 12+'s Kubernetes-compatible API via k8s.io/client-go for dashboards, folders, and other K8s-native resources, and (2) a Cloud provider tier with pluggable providers for Grafana Cloud products (SLO, Synthetic Monitoring, IRM, Fleet Management, etc.) that use product-specific REST APIs. Built in Go, it uses Cobra for CLI structure.
Documentation Map
| File | Purpose |
| VISION.md | Goals, product surface, roadmap themes, release timeline |
| CONSTITUTION.md | Invariants — things that cannot change without explicit human approval |
| ARCHITECTURE.md | System boundaries, extension points, and pipeline diagrams |
| DESIGN.md | CLI UX design: command grammar, output model, exit codes |
| CONTRIBUTING.md | Dev setup, testing environment, contribution workflow |
| docs/architecture/ | Deep-dive architecture docs (patterns, resource model, CLI layer, data flows, …) |
| docs/design/ | Prescriptive UX implementation rules (output, errors, agent mode, naming, …) |
| docs/rfcs/ | Engineering proposals, design tradeoffs, and open questions |
| docs/reference/ | Handwritten provider guides and contributor references |
Architecture at a Glance
Two tiers: K8s resource tier (dashboards, folders via /apis) and Cloud provider tier (SLO, SM, IRM, etc. via product REST APIs). See ARCHITECTURE.md for pipeline diagrams and extension pipelines.
Key Conventions
Authoritative source: CONSTITUTION.md (invariants) and DESIGN.md (UX rules). This is the quick-reference summary.
- Options pattern: Every command uses
opts struct+setup(flags)+Validate()+ constructor - Processor pipeline:
Processor.Process(*Resource) error— composable transformations for push/pull - errgroup concurrency: Bounded parallelism (default 10) for all batch I/O operations
- Folder-before-dashboard: Push pipeline does topological sort — folders pushed level-by-level before other resources
- Config = kubectl kubeconfig: Named contexts with server/auth/namespace, env var overrides
- Format-agnostic data fetching: Commands fetch all data regardless of
--outputformat; codecs control display, not data acquisition (see Pattern 13 indocs/architecture/patterns.md) - PromQL via promql-builder: Use
github.com/grafana/promql-builder/go/promqlfor PromQL construction, not string formatting (see Pattern 14 indocs/architecture/patterns.md) - Datasource query reuse: Datasource clients that call Grafana's unified datasource query API (
/apis/query.grafana.app/.../query, with/api/ds/queryfallback) should reuseinternal/query/grafanaqueryfor HTTP transport andinternal/query/dataframefor Grafana data frame wire types. Do not duplicate POST/fallback/response-limit logic orGrafanaQueryResponse/DataFramestructs in each datasource package. - Explore links are required on query commands: Every query-class datasource leaf command must build a Grafana Explore URL in
internal/datasources/{kind}/explore.goand expose it via--share-link/--openthroughdsquery.ExploreLinkOpts+dsquery.EncodeAndHandleExplore. See Step 1c: Explore link for the rules. - Agent skill placement follows its audience: Portable workflows for people using gcx live under
claude-plugin/skills/; repository-only contributor workflows live under.agents/skills/..claude/skillsis a relative symlink to that canonical tree; edit the source files rather than creating copies. Distributable gcx skills belong in the embeddedclaude-plugin/skills/bundle.mise run validate-skillschecks that Git tracks.claude/skillsas a symlink to exactly../.agents/skills. Both skill trees are gated:TestSkillsGcxInvocationsMatchCommandTree(cmd/gcx/root/skillsdrift_test.go) validates everygcxinvocation inclaude-plugin/skills/and repo-local.agents/skills/against the real command tree, failing CI on unknown commands or flags, andmise run validate-skillsparses the front matter of both. - Skill lifecycle metadata lives in
claude-plugin/skills-catalog.yaml: Register every bundled skill as active or deprecated and append its name tointernal/skills/testdata/shipped_skills.txt. This snapshot is append-only. When removing content, retain the catalog entry as retired indefinitely so old installations remain removable;TestBundledCatalogchecks retention against the snapshot. See skill lifecycle. - wasip1 variants: gcx is also built for
GOOS=wasip1to run embedded in a WebAssembly sandbox. A*_wasip1.gofile paired with a//go:build !wasip1file replaces a host-only piece: there are no outbound sockets (HTTP goes to the host viahttputils.WireTransport), no terminal UIs, andgcx devandinstrumentation check/explain/list-explanationsare left out. When you change a function with a wasip1 variant, change both;mise run vet:wasip1(part ofgate) compiles the packages that build without third-party stubs. The full wasip1 build lives inexperimental/sandbox(build.sh, checked by the Sandbox CI job): when a dependency change breaks it, fix the stubs inexperimental/sandbox/patches/.
Essential Commands
mise run build # Build to bin/gcx
mise run tests # Run all tests with race detection
mise run lint # Run golangci-lint
mise run gate # lint + tests + build (no docs) — fast pre-push gate for code changes
mise run all # lint + tests + build + docker:build + docs
mise run docs # Build Grafana website docs (requires Docker)Without mise: replace with direct Go commands — go build -buildvcs=false -o bin/gcx ./cmd/gcx/ and go test ./.... Always build to bin/gcx. Lint runs in Go module mode (golangci-lint's modules-download-mode: readonly), so no vendor/ directory is needed locally — the module cache (go mod download, run automatically on worktree entry) is sufficient.
Agent environments: the test tasks and release-reference generator pin
GCX_AGENT_MODE=falsethemselves. Normal docs builds validatedocs/sourceswithout regenerating the released CLI reference.
Testing
Prefer table-driven tests. See existing _test.go files for patterns.
Source navigation
Start with project structure for module boundaries. Browse cmd/gcx/ for command wiring and internal/ for implementation; use bin/gcx help-tree for the current command surface.
What to Read Before You Start
| Task | Read first | Then |
| Adding a new command | docs/design/command-naming.md (verb + placement), DESIGN.md (grammar, output model) | docs/design/ for implementation rules, ARCHITECTURE.md § CLI layer |
| Adding a new provider | ARCHITECTURE.md § Provider System | docs/reference/provider-guide.md, docs/design/provider-checklist.md |
| Adding a signal provider command | ARCHITECTURE.md § Signal Providers | Existing signal provider code for the SharedOpts pattern |
| Modifying resource handling | ARCHITECTURE.md § Resources Pipeline | docs/architecture/resource-model.md, docs/architecture/data-flows.md |
| Changing config or auth | ARCHITECTURE.md § Configuration + § Auth | docs/architecture/config-system.md, docs/architecture/client-api-layer.md |
| Fixing a bug | ARCHITECTURE.md for the relevant subsystem | Jump directly to the deep-dive doc for that domain |
| Creating or revising an RFC | RFC conventions, repo-local create-rfc | Use update-rfc when explicitly asked to reconcile verified implementation evidence |
| Reviewing an RFC | Repo-local review-rfc, the originating request and RFC conventions | Check claims, scope, repository rules, consistency and unresolved questions before sharing or acceptance |
| Planning work before implementation | Repo-local contribute and the contribution workflow | Load the proposal or RFC specialist only when the selected route needs it; keep restricted research outside the checkout |
| Planning a new feature | VISION.md (does it belong?), CONSTITUTION.md (can we build it within the rules?) | DESIGN.md for UX, ARCHITECTURE.md for structure |
| Adding, extending, or reviewing a gcx capability (domain teams) | Repo-local contribute — necessity, placement, readiness, contract, implementation references, and self-review | docs/design/command-naming.md, docs/reference/provider-guide.md |
| Reviewing someone else's PR | The repo-local review-pr skill — report shape, over-engineering rubric, lock-in ranking | Compliance Hierarchy below — check all 4 levels in order |
Compliance Hierarchy
Check work against these docs during planning, design, and implementation — in order of strictness.
| # | Doc | Strictness | What to check | If violated |
| 1 | CONSTITUTION.md | Hard invariant — violation is a bug | Architecture invariants, dependency rules, provider registration, CLI grammar, typed resource requirements | Stop. Fix before proceeding. Violation requires explicit human approval to waive. |
| 2 | VISION.md | Strategic alignment — violation is wasted work | Does this belong in gcx? Does it align with dual-purpose design, core beliefs, product surface? | Pause. Confirm direction with a human before investing more effort. |
| 3 | DESIGN.md | UX rules — violation is a UX defect | Output model, exit codes, safety patterns, taste rules in docs/design/ | Fix. New code must comply. |
| 4 | ARCHITECTURE.md | Structural guidance — violation is tech debt | Pipeline placement, package boundaries, patterns in docs/architecture/ | Prefer compliance. Deviation is acceptable with rationale (document in commit or RFC). |
When to check:
- Planning/design: Check VISION (2) and CONSTITUTION (1) — are we building the right thing, and can we build it within the rules?
- Implementation: Check DESIGN (3) and ARCHITECTURE (4) — does the code follow UX rules and structural patterns?
- Pre-flight (below): Final sweep across all four before pushing.
Releasing
Release steps live in the release skill (.agents/skills/release/SKILL.md) — invoke it when tagging a release.
Mandatory Pull Request Checklist
You MUST run this checklist when creating a PR or updating an existing PR with new work (addressing PR reviews or fixing bugs). This is distinct from the Mandatory Pre-Commit Checklist below — mise run all in step 3 subsumes the individual pre-commit steps; do not substitute the pre-commit checklist here.
- Compliance check — verify changes against the compliance hierarchy above. CONSTITUTION and DESIGN violations must be fixed. VISION misalignment must be flagged. ARCHITECTURE deviations must be documented.
- Sync with base branch
git fetch origin main && git rebase origin/main - Quality gates pass (Docker is required for the Grafana docs build):
GCX_AGENT_MODE=false mise run all - Doc maintenance gate — follow documentation maintenance. Update guidance affected by changed behavior, architectural boundaries, or contributor workflows; do not mirror package lists or proposal inventories.
- Push
Work is not done until push succeeds. If it fails, resolve and retry.git push git status # must show "up to date with origin"
Mandatory Pre-Commit Checklist
Run this checklist before every commit (not only before PR/push):
- Format touched files
gofmt -w <touched-go-files> - Lint passes
mise run lint - Targeted tests pass for changed packages
go test ./path/to/changed/package/... - Full test suite passes
go test ./... - Released reference stays separate — do not regenerate
docs/sources/cli-reference.mdin command PRs.mise run tagrefreshes references in the release changelog PR; usemise run docs:refreshfor standalone updates to the latest stable release. Test generator changes withgo test ./scripts/.... - Docs build succeeds (Docker required; CI preserves the
Documentationcheck)mise run docs - No unstaged surprises
git status
GitHub Issues
When creating or commenting on GitHub issues, always anonymize system-specific details. Replace real values with placeholders:
- Stack names / context names →
<my-context>,<stack> - URLs with stack or region identifiers →
https://example-<region>.grafana.net - Hosted IDs, stack IDs, org IDs →
12345,99999 - Datasource names with stack slugs →
grafanacloud-<stack>-prom - API tokens, credentials → never include, even partially
This applies to issue bodies, comments, and code snippets embedded in issues.
Security
Report security vulnerabilities through Grafana's security issue reporting page. Keep vulnerability reports private; do not file them as GitHub issues in this repository. Ordinary security-related engineering work, such as hardening and dependency maintenance, follows the normal issue workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

