# web-performance-skill-cascade

Cascaded web performance skills and Lighthouse tooling for AI agents: Core Web Vitals, budgets, JavaScript, images, fonts, caching, and CI checks.

This is Mirogate's open-source performance contribution for AI-assisted frontend engineering. It ships a real Codex skill, portable Markdown modules, report analysis, budget generation, scenarios, and before/after performance demos.

## Why Cascaded Performance Skills

Performance work fails when every issue is treated as "make the Lighthouse score green." A slow page can be limited by LCP discovery, main-thread JavaScript, image weight, font shifts, cache headers, third-party scripts, or verification gaps.

This project keeps a small root skill and loads focused modules only when the task needs them.

![web-performance-skill-cascade architecture](docs/architecture.png)

```mermaid
flowchart TD
  A["Page, PR, or Lighthouse report"] --> B["web-performance root skill"]
  B --> C{"Relevant performance surface?"}
  C --> D["Lighthouse / Core Web Vitals"]
  C --> E["LCP / images / fonts"]
  C --> F["INP / JavaScript / third-party"]
  C --> G["CLS / caching / delivery"]
  D --> H["Patch + verify + residual risk"]
  E --> H
  F --> H
  G --> H
```

## Quick Start

```bash
npm install
npm test
node scripts/compose.mjs --scenario landing-page-lcp
node scripts/analyze.mjs --report examples/lighthouse/mirogate-uae-mobile.json
node scripts/budget.mjs --init --target green --stdout
```

Run a local Lighthouse audit when Chrome is available:

```bash
node scripts/audit.mjs --url https://example.com --device mobile --runs 3 --timeout 120000 --out reports/
```

Use PageSpeed only when API quota and an API key are available:

```bash
node scripts/audit.mjs --url https://example.com --source pagespeed --api-key "$PAGESPEED_API_KEY"
```

## What Is Included

- `skills/web-performance/SKILL.md`: the Codex root skill.
- `skills/web-performance/references/`: focused performance modules.
- `portable/web-performance-cascade.md`: portable bundle for Claude Code, Cursor, or other agents.
- `scripts/audit.mjs`: local Lighthouse or PageSpeed report collection with timeouts.
- `scripts/analyze.mjs`: Lighthouse JSON to prioritized Markdown or JSON.
- `scripts/budget.mjs`: green-target Lighthouse CI-style budgets.
- `scripts/compose.mjs`: assembles root skill plus selected modules for a scenario.
- `scripts/validate.mjs`: checks module metadata, scenarios, fixtures, and demos.
- `examples/scenarios/`: task-to-module examples.
- `examples/performance-patches/`: before/after demos for common performance mistakes.

## Module Map

| Module | Use When |
| --- | --- |
| `lighthouse-scoring` | Interpreting Lighthouse scores, weights, run conditions, and variability. |
| `core-web-vitals` | LCP, INP, CLS, field data, PageSpeed/CrUX, and `web-vitals` attribution. |
| `lcp-critical-path` | Hero media, TTFB, preload, critical CSS, and render-blocking resources. |
| `inp-main-thread-js` | INP/TBT, long tasks, hydration, event handlers, and workers. |
| `cls-layout-stability` | Layout shifts from images, fonts, banners, embeds, and animations. |
| `images-media` | Responsive images, AVIF/WebP, lazy loading, video, and media byte weight. |
| `fonts-css-rendering` | Font loading, critical CSS, unused CSS, and render blocking. |
| `javascript-bundles` | Unused JS, code splitting, minification, and dependency weight. |
| `caching-delivery-edge` | Compression, cache headers, Cloudflare/CDN rules, immutable assets. |
| `third-party-scripts` | Analytics, chat widgets, embeds, tag managers, and consent-aware loading. |
| `accessibility-seo-guardrails` | Performance fixes that must preserve crawlability and accessibility. |
| `verification-budgets` | Lighthouse CI assertions, budgets, repeated runs, and residual risk. |

## Example Scenarios

```bash
node scripts/compose.mjs --scenario landing-page-lcp
node scripts/compose.mjs --scenario spa-inp
node scripts/compose.mjs --scenario cls-regression
node scripts/compose.mjs --scenario image-heavy-page
node scripts/compose.mjs --scenario third-party-scripts
node scripts/compose.mjs --scenario cloudflare-static-site
```

## Mirogate Dogfood Fixture

The first fixture is based on a local Lighthouse run against `https://mirogate.com/uae/`:

- Performance: `84`
- Accessibility: `92`
- Best practices: `96`
- SEO: `100`
- FCP/LCP: `2.7s`
- CLS: `0.074`
- TBT: `0ms`
- Main opportunity: unused/unminified JavaScript

The fixture is intentionally not treated as a public benchmark. It is a stable parser and documentation example.

## Limits

This is not a guarantee of perfect Lighthouse scores, SEO ranking improvement, Google affiliation, or real-user field success. Lighthouse is lab data. Core Web Vitals field health still requires field data such as CrUX, PageSpeed field data, or RUM.

Use official references for policy decisions:

- Lighthouse scoring: https://developer.chrome.com/docs/lighthouse/performance/performance-scoring
- Core Web Vitals: https://web.dev/articles/vitals
- Lighthouse CI: https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md
- PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/get-started
- web-vitals: https://github.com/GoogleChrome/web-vitals

## Security

Please report security issues to `security@mirogate.com`. See `SECURITY.md`.