agentleFS
grafanagrafana/gcx/AGENTS.md

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.

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
  1. Very specific:

    Options pattern: Every command uses opts struct + setup(flags) + Validate() + constructor

    line 31
  2. Very specific:

    PromQL via promql-builder: Use github.com/grafana/promql-builder/go/promql for PromQL construction, not string formatting (see Pattern 14 …

    line 37
  3. Very specific:

    Explore links are required on query commands: Every query-class datasource leaf command must build a Grafana Explore URL in …

    line 39
  4. Very specific:

    Prefer table-driven tests.

    line 62
  5. Very specific:

    Start with project structure for module boundaries.

    line 66
  6. Distinctive:

    Check work against these docs during planning, design, and implementation — in order of strictness.

    line 87
  7. Distinctive:

    Planning/design: Check VISION (2) and CONSTITUTION (1) — are we building the right thing, and can we build it within the rules?

    line 97
  8. Distinctive:

    Implementation: Check DESIGN (3) and ARCHITECTURE (4) — does the code follow UX rules and structural patterns?

    line 98
  9. Distinctive:

    Run this checklist before every commit (not only before PR/push):

    line 128
  10. Very specific:

    Test generator changes with go test ./scripts/....

    line 149
  11. Distinctive:

    When creating or commenting on GitHub issues, always anonymize system-specific details.

    line 161

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

FilePurpose
VISION.mdGoals, product surface, roadmap themes, release timeline
CONSTITUTION.mdInvariants — things that cannot change without explicit human approval
ARCHITECTURE.mdSystem boundaries, extension points, and pipeline diagrams
DESIGN.mdCLI UX design: command grammar, output model, exit codes
CONTRIBUTING.mdDev 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 --output format; codecs control display, not data acquisition (see Pattern 13 in docs/architecture/patterns.md)
  • PromQL via promql-builder: Use github.com/grafana/promql-builder/go/promql for PromQL construction, not string formatting (see Pattern 14 in docs/architecture/patterns.md)
  • Datasource query reuse: Datasource clients that call Grafana's unified datasource query API (/apis/query.grafana.app/.../query, with /api/ds/query fallback) should reuse internal/query/grafanaquery for HTTP transport and internal/query/dataframe for Grafana data frame wire types. Do not duplicate POST/fallback/response-limit logic or GrafanaQueryResponse/DataFrame structs 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.go and expose it via --share-link/--open through dsquery.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/skills is a relative symlink to that canonical tree; edit the source files rather than creating copies. Distributable gcx skills belong in the embedded claude-plugin/skills/ bundle. mise run validate-skills checks that Git tracks .claude/skills as a symlink to exactly ../.agents/skills. Both skill trees are gated: TestSkillsGcxInvocationsMatchCommandTree (cmd/gcx/root/skillsdrift_test.go) validates every gcx invocation in claude-plugin/skills/ and repo-local .agents/skills/ against the real command tree, failing CI on unknown commands or flags, and mise run validate-skills parses 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 to internal/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; TestBundledCatalog checks retention against the snapshot. See skill lifecycle.
  • wasip1 variants: gcx is also built for GOOS=wasip1 to run embedded in a WebAssembly sandbox. A *_wasip1.go file paired with a //go:build !wasip1 file replaces a host-only piece: there are no outbound sockets (HTTP goes to the host via httputils.WireTransport), no terminal UIs, and gcx dev and instrumentation check/explain/list-explanations are left out. When you change a function with a wasip1 variant, change both; mise run vet:wasip1 (part of gate) compiles the packages that build without third-party stubs. The full wasip1 build lives in experimental/sandbox (build.sh, checked by the Sandbox CI job): when a dependency change breaks it, fix the stubs in experimental/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=false themselves. Normal docs builds validate docs/sources without 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

TaskRead firstThen
Adding a new commanddocs/design/command-naming.md (verb + placement), DESIGN.md (grammar, output model)docs/design/ for implementation rules, ARCHITECTURE.md § CLI layer
Adding a new providerARCHITECTURE.md § Provider Systemdocs/reference/provider-guide.md, docs/design/provider-checklist.md
Adding a signal provider commandARCHITECTURE.md § Signal ProvidersExisting signal provider code for the SharedOpts pattern
Modifying resource handlingARCHITECTURE.md § Resources Pipelinedocs/architecture/resource-model.md, docs/architecture/data-flows.md
Changing config or authARCHITECTURE.md § Configuration + § Authdocs/architecture/config-system.md, docs/architecture/client-api-layer.md
Fixing a bugARCHITECTURE.md for the relevant subsystemJump directly to the deep-dive doc for that domain
Creating or revising an RFCRFC conventions, repo-local create-rfcUse update-rfc when explicitly asked to reconcile verified implementation evidence
Reviewing an RFCRepo-local review-rfc, the originating request and RFC conventionsCheck claims, scope, repository rules, consistency and unresolved questions before sharing or acceptance
Planning work before implementationRepo-local contribute and the contribution workflowLoad the proposal or RFC specialist only when the selected route needs it; keep restricted research outside the checkout
Planning a new featureVISION.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-reviewdocs/design/command-naming.md, docs/reference/provider-guide.md
Reviewing someone else's PRThe repo-local review-pr skill — report shape, over-engineering rubric, lock-in rankingCompliance Hierarchy below — check all 4 levels in order

Compliance Hierarchy

Check work against these docs during planning, design, and implementation — in order of strictness.

#DocStrictnessWhat to checkIf violated
1CONSTITUTION.mdHard invariant — violation is a bugArchitecture invariants, dependency rules, provider registration, CLI grammar, typed resource requirementsStop. Fix before proceeding. Violation requires explicit human approval to waive.
2VISION.mdStrategic alignment — violation is wasted workDoes 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.
3DESIGN.mdUX rules — violation is a UX defectOutput model, exit codes, safety patterns, taste rules in docs/design/Fix. New code must comply.
4ARCHITECTURE.mdStructural guidance — violation is tech debtPipeline 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.

  1. 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.
  2. Sync with base branch
    git fetch origin main && git rebase origin/main
  3. Quality gates pass (Docker is required for the Grafana docs build):
    GCX_AGENT_MODE=false mise run all
  4. 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.
  5. Push
    git push
    git status   # must show "up to date with origin"
    Work is not done until push succeeds. If it fails, resolve and retry.

Mandatory Pre-Commit Checklist

Run this checklist before every commit (not only before PR/push):

  1. Format touched files
    gofmt -w <touched-go-files>
  2. Lint passes
    mise run lint
  3. Targeted tests pass for changed packages
    go test ./path/to/changed/package/...
  4. Full test suite passes
    go test ./...
  5. Released reference stays separate — do not regenerate docs/sources/cli-reference.md in command PRs. mise run tag refreshes references in the release changelog PR; use mise run docs:refresh for standalone updates to the latest stable release. Test generator changes with go test ./scripts/....
  6. Docs build succeeds (Docker required; CI preserves the Documentation check)
    mise run docs
  7. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.