Lighthouse Budget Enforcer

What this skill does

Generates a Lighthouse CI configuration with performance budgets tuned to a project's current performance baseline, then wires the config into a CI step that fails on regressions. Includes per-page-type starter budgets.

Inputs

• urls: array of URLs to audit (must be reachable from the runner).
• repo_dir: project root for placing the config.
• Optional target_p75_lcp: explicit budget for LCP (default 2500ms).
• Optional target_total_byte_weight_kb: default 1500.

Steps

1. Run npx lhci collect --url=<each url> --numberOfRuns=3 --settings.preset=desktop and capture median scores per audit.
2. Categorize each URL by path heuristics: / -> landing, /products/ -> product, /checkout/ -> checkout. Assign a starter budget tier per category.
3. For each URL, set the budget's maxNumericValue for the four hero metrics (LCP, INP, CLS, TBT) to 1.1 * current_p75. This locks in the current state without immediate failure.
4. Set total-byte-weight budget to min(current * 1.05, target_total_byte_weight_kb * 1024).
5. Add resource-count budgets: script-count, image-count, stylesheet-count based on observed counts plus 10%.
6. Generate .lighthouserc.json at <repo_dir>/.lighthouserc.json with assertions referencing the above budgets and assertMatrix per URL.
7. Add a GitHub Actions workflow .github/workflows/lighthouse.yml running on pull_request: install lhci, run lhci autorun, and upload results to a temporary public storage.
8. For new pages with no baseline, default to web.dev's recommended thresholds (LCP < 2500ms, CLS < 0.1, INP < 200ms).
9. Document the budget rationale in docs/perf-budget.md.

Output

Three files: .lighthouserc.json, .github/workflows/lighthouse.yml, docs/perf-budget.md. Stdout prints the per-URL p75 baseline used and the resulting budget value.

Verification

Run npx lhci autorun --config=.lighthouserc.json on the current main branch; expected outcome is zero assertion failures (the budget is set to current state plus a slack). Intentionally regress one metric (load a 100KB unused JS file) and rerun; the assertion must fail. If lhci can't reach the URL (auth wall), require a LHCI_BASIC_AUTH env var rather than skip the audit silently.

Edge cases

• Single-page apps with auth-gated pages: configure lhci collect --headful with login script.
• Pages that need cookies (e.g., consent banner): pass --puppeteerScript to set them.
• Pages with significant variance run-to-run: increase numberOfRuns to 5 and use the median; flag the URL as "high-variance".
• Pages newly added with no traffic data: skip the slack-multiplier and use raw web.dev thresholds.