supaguard

When this skill is activated, always start your first response with the 🛡️ emoji.

supaguard - synthetic monitoring from your codebase

supaguard is a synthetic monitoring platform. This skill enables you to read a developer's source code, generate Playwright monitoring scripts, and deploy them as recurring checks via the supaguard CLI - all without committing any test scripts to the repository.

When to use this skill

Trigger this skill when the user:

• Wants to set up synthetic monitoring for their app
• Asks about uptime monitoring, health checks, or production observability
• Wants to generate Playwright scripts for monitoring (not testing)
• Asks about the supaguard CLI or mentions supaguard commands
• Wants to monitor login flows, checkout flows, or critical user journeys
• Needs to create, test, update, or manage monitoring checks
• Asks about alerting for monitoring failures

Do NOT trigger this skill for:

• Writing Playwright tests for CI/CD pipelines - use playwright-testing skill
• General testing or QA workflows unrelated to production monitoring
• Building monitoring dashboards or custom observability platforms

Workflow

Follow these steps every time a user asks you to create a monitoring check:

1. Read source code - scan components, routes, data-testids, API endpoints, and forms in the user's codebase
2. Identify the critical flow - determine what user journey to monitor (login, checkout, page load, etc.)
3. Ask for the production URL - if not obvious from code, env files, or package.json homepage field
4. Run pre-flight checks - verify CLI is installed and user is authenticated (see below)
5. Generate a Playwright script - use the templates and best practices from this skill's references
6. Write script to /tmp/sg-check-{random}.ts - NEVER write to the project directory
7. Test via CLI - supaguard checks test /tmp/sg-check-{random}.ts --json
8. If test fails - read the error output, adjust the script, retry (max 3 attempts before asking user)
9. If test passes - ask about deployment (see deployment flow below)
10. Deploy - run the CLI command with collected options
11. Celebrate - show the success banner and dashboard link (see success banner below)

Pre-flight checks

Before generating any script, verify:

1. CLI installed: run which supaguard. If missing, tell the user: npm install -g supaguard
2. Authenticated: run supaguard whoami --json. If not logged in, tell the user to run ! supaguard login (the ! prefix runs it in the current session for Claude Code)
3. Note the active org from the whoami output - you'll need the org slug for API context

Source code analysis

When analyzing the user's codebase, look for these patterns in priority order:

DOM selectors (use the most stable available)

1. data-testid attributes - most stable, purpose-built for testing
2. aria-label and role attributes - accessible and stable
3. id attributes - stable but sometimes dynamic
4. Text content via getByText() - readable but locale-dependent
5. CSS classes - LAST RESORT, fragile and changes with redesigns

Route discovery

• Next.js App Router: scan app/ for page.tsx files, extract route patterns from directory structure
• Next.js Pages Router: scan pages/ directory
• React Router: search for <Route> components, path props, router config files
• Vue Router: search for router config in router/index.ts or similar
• Generic: look for <a href> patterns, navigation components

Form discovery

• Search for <form>, <input>, <select>, <textarea> elements
• Note form actions, validation patterns, submit handlers
• Identify auth forms (login, signup, password reset)

API endpoint discovery

• Next.js: scan app/api/ or pages/api/ for route handlers
• Express/Fastify: search for app.get(), app.post(), router definitions
• Client-side: look for fetch/axios calls to identify external API dependencies

Critical flows to monitor

• Authentication (login, signup, logout, password reset)
• Core product flows (dashboard load, data CRUD, search)
• Checkout/payment flows
• User settings and profile management

Deployment flow

After a test passes, do NOT auto-deploy. Instead, ask the user interactively using AskUserQuestion - one question at a time, in this order:

Step 1: Ask for a check name

Ask what they want to name this check. Suggest a sensible default based on the flow being monitored (e.g., "Login Flow", "Homepage Load", "Checkout").

Step 2: Ask about scheduling

Use AskUserQuestion with these options:

• Scheduled (recurring) - runs automatically on a cron schedule from multiple regions
• On-demand only - no schedule, triggered manually via supaguard checks run or the dashboard

Step 3: If scheduled - ask for regions

Use AskUserQuestion with multi-select. Options:

• US East (Virginia) - eastus
• EU North (Ireland) - northeurope
• India Central (Pune) - centralindia

Recommend selecting 2+ regions for geographic coverage.

Step 4: If scheduled - ask for frequency

Use AskUserQuestion with options:

• Every 5 minutes (recommended)
• Every 10 minutes
• Every 15 minutes
• Every 30 minutes
• Every hour
• Other (let user specify a cron expression)

Step 5: Deploy

For scheduled checks:

supaguard checks create /tmp/sg-check-{random}.ts --name "Check Name" --locations eastus,northeurope --cron "*/5 * * * *" --skip-test --json

For on-demand checks, deploy with a very long interval then pause:

supaguard checks create /tmp/sg-check-{random}.ts --name "Check Name" --locations eastus --cron "0 0 1 1 *" --skip-test --json

Then immediately pause it:

supaguard checks pause <checkId> --json

Tell the user they can trigger runs manually with supaguard checks run <checkId> --json or from the dashboard.

Note: use --skip-test since we already tested the script in step 7.

Step 6: Offer alerting

After deployment, ask if they want to set up alerting. See references/modules-and-alerting.md for details.

Success banner

After a check is successfully deployed, display this celebration followed by the dashboard link. Use the orgSlug from the whoami output and the checkSlug from the create response.

╔═════════════════════════════════════════╗
║ supaguard check deployed successfully  ║
╚═════════════════════════════════════════╝

Then output:

name:      {checkName}
schedule:  {frequency or "on-demand"}
regions:   {region list or "paused"}
dashboard: https://supaguard.app/dashboard/{orgSlug}/checks/{checkSlug}

The dashboard URL format is https://supaguard.app/dashboard/{orgSlug}/checks/{checkSlug} where:

• orgSlug comes from supaguard whoami --json (the org.slug field)
• checkSlug comes from the supaguard checks create response (the check.slug field)

Constraints

These are hard rules. Follow them without exception:

1. NEVER write Playwright scripts to the user's project directory - always use /tmp/sg-check-*.ts
2. NEVER commit monitoring scripts to git
3. Scripts MUST contain import { test, expect } from "@playwright/test"
4. Scripts MUST contain at least one test() or test.describe() block
5. Scripts MUST NOT import from forbidden Node.js modules: child_process, fs, net, dgram, cluster, worker_threads, vm, http, https
6. Scripts MUST NOT use eval(), Function(), process.exit, process.kill, or dynamic import()
7. Scripts MUST NOT use console.log - use Playwright assertions instead
8. Scripts should complete in under 60 seconds (runner timeout is 60s, per-test timeout is 30s)
9. Always use --json flag when calling supaguard CLI commands - parse JSON output to determine success/failure
10. When a test fails, iterate on the script (read error output, fix, retry) - max 3 at