MCP use and Rules

.agents/README.md

@@ -0,0 +1,54 @@
+# PMM-QA Agent Workflows & Configuration
+
+- This repo has a `.agents` folder which contains workflows and context rules for the LLM to work better with in `pmm-qa` repository.
+- The folder contains:
+    - `workflows/`: Contains workflows for the agent to use.
+    - `mcp.json`: Contains MCP server configurations for the agent.
+    - `README.md`: Contains information about the agent workflows, MCP configurations and how to use them.
+
+## Supported Workflows and How to Use Them
+
+- There are 7 workflows in the `workflows/` folder.
+- Each workflow gives LLM a specific set of instructions for a specific task.
+- You can call them directly into the chat using the following commands:
+    - `/` + `workflow name` in antigravity chat (e.g. `/apiIndex`)
+    - `#` + `workflow name` in vscode chat (e.g. `#apiIndex`)
+
+### List of available workflows
+
+- `/apiIndex`: A subset of pmmApi.json, has list of common APIs used across PMM
+- `/bugReport`: Use this workflow to generate a bug report out of failing tests or unexpected behavior.
+- `/mcpRules`: Defines execution rules for the LLM when using Playwright MCP.
+- `/pmmLogin`: Use this workflow to login to PMM using basic Auth headers via MCP instead of the UI.
+- `/pomRules`: Use this to create a new Page Object Model (POM) or update an existing POM.
+- `/report`: Rules for the LLM to generate a handoff report that summarizes actions performed and findings.
+- `/workflowIndex`: This is the entry point for LLM. It guides the agent on which workflow to pick based on your current task.
+
+---
+
+## MCP Integration
+
+- Use the following configuration file or pass necessary arguments to the Playwright MCP server:
+- This config is used to save tokens.
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "args": [
+        "-y",
+        "@playwright/mcp@latest",
+        "--ignore-https-errors",
+        "--snapshot-mode",
+        "none",
+        "--image-responses",
+        "omit"
+      ],
+      "command": "npx"
+    }
+  }
+}
+```
+## Suggestions
+- Use the workflows defined in the `workflows/` folder.
+- Either call individual workflows or use `/workflowIndex` to let the agent pick the right workflow.

.agents/workflows/apiIndex.md

@@ -0,0 +1,61 @@
+---
+description: Common API's to avoid reading the whole pmmApi.json
+---
+
+# API Usage Strategy
+- Check this file before opening `pmmApi.json`.
+- Open `pmmApi.json` ONLY for exact schema/field needs.
+
+# Common Paths
+
+## Users/Auth
+- `GET /v1/users/me`
+- `GET /v1/users`
+- `POST /graph/login` (ONLY for auth flow debugging)
+
+## Inventory & Management
+- `GET /v1/inventory/services`
+- `GET /v1/management/services`
+- `POST /v1/management/services` (Add database/service)
+- `DELETE /v1/management/services/{service_id}`
+- `GET /v1/management/nodes`
+- `DELETE /v1/management/nodes/{node_id}`
+- `GET /v1/management/agents`
+
+## QAN and Realtime Analytics
+- `GET /v1/qan/health`
+- `POST /v1/qan/query:getExample`
+- `POST /v1/qan/query:getSchema`
+- `POST /v1/qan/metrics:getNames`
+- `GET /v1/qan/query/{queryid}/plan`
+- `GET /v1/realtimeanalytics/services`
+- `GET /v1/realtimeanalytics/sessions`
+- `POST /v1/realtimeanalytics/sessions:start`
+- `POST /v1/realtimeanalytics/sessions:stop`
+- `POST /v1/realtimeanalytics/queries:search`
+
+## Advisors
+- `GET /v1/advisors`
+- `GET /v1/advisors/checks/failed`
+- `POST /v1/advisors/checks:start`
+- `GET /v1/advisors/failedServices`
+
+## Alerting
+- `POST /v1/alerting/rules`
+- `GET /v1/alerting/templates`
+
+## Backup
+- `GET /v1/backups/artifacts`
+- `POST /v1/backups:start`
+- `GET /v1/backups/locations`
+- `DELETE /v1/backups/locations/{location_id}`
+
+## Server / Settings
+- `GET /v1/server/version`
+- `GET /v1/server/settings`
+- `GET /v1/server/updates:getStatus`
+- `POST /v1/server/updates:start`
+
+## HA
+- `GET /v1/ha/status`
+- `GET /v1/ha/nodes`

.agents/workflows/bugReport.md

@@ -0,0 +1,120 @@
+---
+description: Evidence-first workflow for turning logs, screenshots, and brief context into a concise Jira-ready bug report
+---
+
+# Purpose
+
+Use this workflow to convert bug evidence into a compact report.
+
+Allowed input:
+- user context
+- screenshots
+- logs
+- trace snippets
+- console errors
+- network errors
+- directly relevant code references
+
+Reporting only:
+- Do not propose fixes or a test plan.
+- Do not invent root cause, environment, or steps.
+
+# Core Rules
+
+- Report only confirmed facts from prompt, screenshots, logs, CLI, MCP, or code.
+- Put anything likely but unproven in `Unverified`.
+- Prefer concrete evidence over interpretation.
+- Summarize noisy logs to the smallest useful line.
+- Separate `Actual` from `Expected`.
+- If details are missing, still write the report and note the gap in `Repro Notes`.
+- Ask follow-up questions only if the report would otherwise be misleading.
+
+# Analysis Order
+
+1. Identify the affected feature, page, API, or component.
+2. Classify the issue: UI, functional, backend/API, performance/stability, access, or install/upgrade/config.
+3. Extract only proof: visible error text, broken UI state, timestamp, failed request, stack line, or log line.
+4. State user impact.
+5. Infer the shortest credible repro steps from provided evidence only.
+6. State expected behavior from context and normal product behavior.
+7. Set severity conservatively.
+
+# Input Rules
+
+## Screenshots
+
+- Capture visible page names, URLs, controls, and exact error text.
+- Describe only what is visible.
+- Mark an element as missing only when the intended element is clear.
+- Reference the screenshot in `Evidence`.
+
+## Logs
+
+- Keep only the smallest lines that prove failure.
+- Prefer explicit errors, status codes, timeouts, connection failures, and service names.
+- Do not paste large log blocks.
+- Move suspected root cause to `Unverified`.
+
+## Minimal Context
+
+- Do not block on missing details.
+- Provide a constrained title, minimal steps, explicit evidence, and note gaps in `Repro Notes`.
+
+# Severity
+
+Choose the lowest severity that matches confirmed impact.
+
+- `Critical`: data loss, security issue, complete outage, blocked install/upgrade, or unusable core workflow with no workaround
+- `Urgent`: primary workflow broken, repeated hard failure, or severe impact with impractical workaround
+- `High`: strong functional impact, incorrect results, partial workflow breakage, or major usability degradation
+- `Medium`: limited functional issue, secondary workflow problem, or contained UI/behavior issue
+- `Low`: cosmetic or low-impact polish issue
+
+Default to `Medium` if impact is unclear.
+
+# Title
+
+- Format: `[Component] Short factual description`
+- Do not include root-cause guesses.
+
+Examples:
+- `[Dashboards] Filter panel stays blank after reload`
+- `[Backup] Restore action returns 500`
+
+# Output Format
+
+Provide exactly these sections:
+
+- **Title**: `[Component] Short bug description`
+- **Summary**: 2-3 short lines covering the defect and impact
+- **Severity**: `Critical|Urgent|High|Medium|Low`
+- **Steps to Reproduce**:
+  1. Step one
+  2. Step two
+- **Actual**: Confirmed observed behavior
+- **Expected**: Intended user-visible behavior
+- **Evidence**: Short proof bullets
+- **Unverified**: Only if needed
+- **Repro Notes**: Missing details, consistency, timing, role, environment, or workaround notes
+
+# Evidence Rules
+
+Keep `Evidence` compact.
+
+Examples:
+- `Screenshot: settings-page-error.png shows "Failed to load user"`
+- `Log: pmm-managed timeout waiting for inventory sync`
+- `API: GET /v1/inventory/nodes returned 500`
+- `Console: TypeError on dashboard load`
+
+Avoid full stack traces, long logs, broad narratives, and unsupported root-cause claims.
+
+# Final Check
+
+- Title names the affected component.
+- Severity matches confirmed impact.
+- Steps are reproducible or clearly partial.
+- `Actual` is supported by evidence.
+- `Expected` describes behavior, not a fix.
+- Uncertain points appear only in `Unverified`.
+- Keep the report short enough to paste into Jira without cleanup.

.agents/workflows/mcpRules.md

@@ -0,0 +1,29 @@
+---
+description: Execution, browser, and locator strategy rules for PMM Playwright tasks
+---
+
+# Execution & Context
+- Execute directly; DO NOT output plans or reasoning unless blocked.
+- Search first, read smallest possible files second (prefer nearby tests, POMs, helpers).
+- NO broad repo scans.
+
+# API Setup
+- Use PMM REST API to build test state; use UI ONLY to verify behavior.
+- Check `apiIndex.md` first for routes. Open `pmmApi.json` ONLY for precise schema definitions.
+
+# Login
+- Follow `pmmLogin.md`.
+- Basic Auth headers ONLY.
+- NEVER use the UI login form or `/graph/login` (except when debugging auth).
+
+# Browser interactions
+- Batch multiple actions (fills, clicks, asserts) into one `mcp_playwright_browser_run_code` call.
+- Use `browser_wait_for` or Playwright assertions. NO manual sleeps.
+- Do not reload or re-authenticate unless state explicitly demands it.
+- If blocked, `browser_snapshot` once, stop, and reassess.
+
+# Locators & POM
+- Priority: `getByTestId` > `getByRole` > `getByLabel` > `getByPlaceholder`.
+- Reuse existing POM locators.
+- If missing: do EXACTLY ONE DOM discovery pass, then update the POM. NEVER re-evaluate the same page's DOM.
+- AVOID: `nth()`, `first()`, `last()`, dynamic XPath, and text-heavy selectors.