absolutelyskilled/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 attempts before asking the user for help
11. Always include the production URL in scripts - ask the user if not obvious from code or environment configs
12. DO NOT use React Testing Library APIs (getByDisplayValue, queryByText, findByRole, etc.) - use Playwright's native page.getBy*() methods

---

Anti-patterns / common mistakes

| Mistake | Why it is wrong | What to do instead | |---|---|---| | Writing scripts to project directory | Pollutes the codebase with monitoring artifacts | Always write to /tmp/sg-check-*.ts | | Using page.waitForTimeout() | Makes checks flaky and wastes runner time | Use waitForSelector(), waitForResponse(), or Playwright assertions | | Asserting on CSS classes | Breaks on redesigns, not meaningful for monitoring | Assert on text content, roles, testids, or visibility | | Using React Testing Library APIs | Not available in Playwright runner | Use page.getBy*() methods: getByTestId, getByRole, getByText | | Monitoring too many flows in one check | Hard to diagnose failures, exceeds timeout | Keep one logical flow per check | | Hardcoding credentials in scripts | Security risk, scripts are stored in the cloud | Use test accounts or environment variables | | Skipping pre-flight checks | Leads to confusing errors mid-workflow | Always verify CLI install and auth first | | Auto-deploying without asking | User should control scheduling and regions | Always ask before deploying | | Omitting --json flag | Human-readable output is hard to parse programmatically | Always use --json for structured output |

---

Gotchas

1. Forbidden module imports - The supaguard runner sandboxes scripts and blocks fs, child_process, net, http, https, vm, and other Node.js built-ins. Scripts that import these will fail at runtime with a cryptic error. Stick to @playwright/test and the allowed npm packages listed in references/playwright-guide.md.

2. Runner timeout is 60 seconds - Scripts that navigate through too many pages or wait on slow third-party resources will time out. Keep checks focused on a single flow and set individual test timeouts to 30 seconds.

3. React Testing Library confusion - Methods like getByDisplayValue, queryByText, and findByRole are NOT Playwright APIs. Playwright has similarly named but different methods: page.getByTestId(), page.getByRole(), page.getByText(). Mixing these up causes runtime errors.

4. On-demand checks still need a cron - The CLI requires --cron even for on-demand checks. Use a far-future cron ("0 0 1 1 *") and immediately pause the check after creation.

5. Cookie consent banners - Production sites often have cookie banners that block interaction. Always handle these before proceeding with the main flow. Look for common patterns: [data-testid="cookie-accept"], buttons with text "Accept", or known cookie consent libraries.

---

References

For detailed guidance, load these reference files as needed:

• references/cli-reference.md - full CLI command reference with flags and --json output shapes
• references/playwright-guide.md - monitoring best practices, anti-patterns, and script templates
• references/framework-patterns.md - framework-specific code analysis patterns
• references/modules-and-alerting.md - shared modules, alerting, regions, and scheduling

Only load a references file if the current task requires it - they are long and will consume context.

---

Companion check

On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:

npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>

Skip entirely if recommended_skills is empty or all companions are already installed.