Grafana Dashboard Architecture AGENTS.md Template

Overview

Direct answer: The Grafana dashboard architecture AGENTS.md Template codifies the operating manual for building and governing Grafana dashboards with AI coding agents. It supports both single-agent execution and multi-agent orchestration for dashboards, data sources, alerts, provisioning, and governance.

This template establishes roles, rules, and handoffs that keep dashboard projects aligned with architecture goals, data governance, and security constraints while enabling scalable collaboration across agent teams.

When to Use This AGENTS.md Template

• When you are designing and provisioning Grafana dashboards at scale across multiple data sources and teams.
• When you require consistent governance, versioning, and handoff protocols between agents (planner, implementer, reviewer, tester, researcher, domain expert).
• When tool governance, access controls, and secure deployment processes must be explicit and auditable.
• When dashboards, data sources, and alert rules need automated validation and rollback procedures.

Copyable AGENTS.md Template

Copy the block below into your Grafana projects to bootstrap your agent-driven workflow. It defines project roles, roster, orchestrator behavior, handoffs, context management, and policy rules for Grafana dashboards.

# AGENTS.md
# Grafana Dashboard Architecture AGENTS.md Template

Project role: Grafana Architect, Dashboard Owner, Data Source Owner

Agent roster and responsibilities:
- Planner: defines dashboard goals, data sources, and layout constraints; creates initial design sketch and acceptance criteria.
- Implementer: builds dashboards, configures data sources, and applies provisioning rules; implements alert rules and panel compositions.
- Reviewer: checks dashboard configuration, data source integrity, and security compliance; approves or requests changes.
- Tester: validates dashboard rendering, data accuracy, and performance under load; executes test scenarios.
- Researcher: investigates data sources, metrics definitions, and anomaly detection patterns; documents provenance.
- Domain Specialist: provides subject-matter guidance on KPIs, SLAs, and governance constraints for the domain.

Supervisor or orchestrator behavior:
- The orchestrator coordinates tasks, tracks memory of decisions, and enforces handoffs between agents according to the workflow state.
- It validates inputs, routes work, and surfaces blockers to the human reviewer when necessary.

Handoff rules between agents:
- Planner -> Implementer: hand off design specs, data source mappings, and provisioning plan.
- Implementer -> Reviewer: hand off built dashboards for quality and security review.
- Reviewer -> Tester: pass dashboards for functional and performance testing.
- Tester -> Planner: report defects; planner updates acceptance criteria and re-plans.
- Researcher -> Domain Specialist: share domain findings and KPI definitions for validation.

Context, memory, and source-of-truth rules:
- All decisions are captured in the AGENTS.md context, with links to the Grafana provisioning repo and data dictionary.
- Source of truth is the Grafana provisioning JSON and associated dashboards in the version-controlled repository.
- The memory store (short-term) tracks current design state; the long-term memory stores architecture decisions and rationale.

Tool access and permission rules:
- Agents may call Grafana HTTP API, read dashboards, and write only with explicit approval.
- Secrets are stored in a secure vault; credentials are never embedded in code blocks.
- Production changes require a staged promotion and human approval gate.

Architecture rules:
- Dashboards must be provisioned from JSON definitions, not manual edits in the UI.
- Data sources must be versioned and referenced in provisioning files.
- Alerts and notification channels must be governed by domain policies.

File structure rules:
- Use a single repository for Grafana dashboards, data sources, and provisioning scripts.
- Each dashboard has a JSON file; folders reflect data domains.
- Documentation lives under docs/ with a glossary and design decisions.

Data, API, or integration rules:
- All data connections use securely stored credentials; tokens rotate regularly.
- Grafana API calls must be rate-limited and logged.

Validation rules:
- Dashboards must validate against the Grafana JSON schema; missing fields fail the build.
- Tests must cover rendering, data source connectivity, and alert conditions.

Security rules:
- Do not expose secrets in code; enforce least-privilege access to Grafana resources.
- Enforce role-based access controls on dashboards and data sources.

Testing rules:
- Include unit tests for data mappings and panel configurations.
- Run integration tests against a staging Grafana instance.

Deployment rules:
- Promote changes through a CI/CD pipeline; require approval for production deployments.
- Maintain an audit trail of changes and roll back if issues are detected.

Human review and escalation rules:
- Escalate architectural decisions and high-risk changes to a domain lead or architect.
- Request human review for any breaking changes to data sources or alert pipelines.

Failure handling and rollback rules:
- If an alert or dashboard fails validation, automatically revert to the last known-good JSON and notify the team.

Things Agents must not do:
- Do not bypass approval gates or modify production dashboards without consent.
- Do not store credentials in code or logs.
- Do not drift from the versioned provisioning files.

Recommended Agent Operating Model

The operating model assigns clear roles and decision boundaries to ensure Grafana dashboards are built with governance. Planner defines goals; Implementer builds; Reviewer checks; Tester validates; Researcher informs; Domain Specialist approves constraints. Escalation paths route issues to human review as needed.

Recommended Project Structure

grafana-dashboard-architecture/
├─ agents/                  # agent implementations and orchestration logic
│  ├─ planner/              # design and goal planning
│  ├─ implementer/          # build dashboards and data sources
│  ├─ reviewer/             # quality and security checks
│  ├─ tester/               # tests and validation
│  ├─ researcher/           # data sources and KPI research
│  └─ domain-specialist/    # domain guidance and governance rules
├─ dashboards/              # Grafana dashboard JSON definitions
├─ data_sources/            # data source provisioning definitions
├─ provisioning/            # provisioning scripts and config
├─ alerts/                  # alert rules and channels
├─ docs/                    # docs and design decisions
├─ tests/                   # unit and integration tests
└─ repo-readme.md           # context and governance notes

Core Operating Principles

• Keep dashboards consistent with the architecture; avoid feature-creep drift.
• Handoff rules are explicit; never skip steps in the workflow.
• Secrets and credentials are never committed; use a vault and environment isolation.
• All changes are traceable via version control and CI/CD gates.
• Content and code must be self-documenting and versioned.

Agent Handoff and Collaboration Rules

• Planner communicates goals and acceptance criteria to Implementer with explicit success metrics.
• Implementer reports back to Reviewer with a ready-to-test branch or PR.
• Reviewer approves only after security, data integrity, and governance checks pass.
• Tester executes test plans and logs results; any failures are escalated back to Planner.
• Researcher provides data source nuances to Domain Specialist for validation.
• Domain Specialist weighs domain constraints and signs off before production.

Tool Governance and Permission Rules

• Grafana API calls require scoped tokens with least-privilege access.
• Dashboard edits must occur in a versioned branch and be approved before merge.
• Secrets must be retrieved from a secure vault; never embedded in code.
• Production changes require an approval gate and a rollback plan.
• External services and data sources must have documented SLAs and health checks.

Code Construction Rules

• Use JSON definitions for dashboards and data sources; avoid manual UI edits in production.
• Naming conventions: dashboards named by domain.section.metric, data sources by type and environment.
• Leverage provisioning snapshots and versioned templates to avoid drift.
• All changes are committed with descriptive messages and linked to design decisions.
• Do not duplicate dashboards; reuse templates and shared panels when appropriate.

Security and Production Rules

• Enforce role-based access control across dashboards and data sources.
• Rotate credentials regularly and rotate tokens on a schedule.
• Audit logs must capture who changed what and when.
• Limit production changes to approved CI/CD pipelines with test gates.

Testing Checklist

• Unit tests for data mappings and panel configurations.
• Integration tests against a staging Grafana instance for provisioning and data source connectivity.
• End-to-end tests for dashboard rendering, data refresh, and alert triggering.
• Security and permission tests for access control and secret handling.
• Regression tests to ensure no drift after updates.

Common Mistakes to Avoid

• Skipping the Planner -> Implementer handoff and skipping acceptance criteria.
• Storing credentials in code or logs; failing to use a vault.
• Overlooking data source changes during dashboard updates.
• Implementing dashboards that drift from governance and design decisions.
• Ignoring rollback plans and post-deployment monitoring.

Related implementation resources: AI Use Case for Construction Firms Using Procore To Extract and Categorize Safety Violation Patterns Across Job Sites and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the Grafana dashboard architecture AGENTS.md Template used for?

It codifies roles, rules, and handoffs for building and governing Grafana dashboards using AI coding agents in a multi-agent orchestration.

Can I use this AGENTS.md Template for single-agent projects?

Yes. It supports single-agent operations and also defines multi-agent orchestration patterns for complex dashboards.

What should be included in the AGENTS.md template for Grafana?

Roles, handoffs, context and memory rules, tool permissions, architecture constraints, file structure, validation, security, testing, deployment, and escalation rules.

How do agents handle security and production deployments?

The template prescribes secrets handling, restricted tool access, approvals, and rollback procedures for safe production changes.

Where should I place this AGENTS.md Template in my repo?

Place it at ai-skills/agents-md-templates/{slug} to serve as project-level operating context.