@nockdev/awf 6.2.0

package/.agent/skills/cross-cutting/web-perf/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: web-perf
+detect: ["lighthouse.json", "web-vitals.*", ".lighthouserc.js"]
+version: "6.1.2"
+category: support
+tier: 1
+---
+
+# Web Performance Audit — DOMYH Awesome Code
+
+> **Source**: Cloudflare Web-Perf Best Practices
+> **Focus**: Core Web Vitals, Network Optimization, Accessibility
+
+---
+
+## 🎯 When to Use This Skill
+
+Use for: Performance audits, Lighthouse optimization, page speed improvement.
+**NOT for**: Functional testing (→ testing), code quality (→ coding-rules).
+
+---
+
+## 📊 Core Web Vitals Thresholds
+
+| Metric          | Good    | Needs Improvement | Poor    |
+| --------------- | ------- | ----------------- | ------- |
+| **TTFB**        | < 800ms | < 1.8s            | > 1.8s  |
+| **FCP**         | < 1.8s  | < 3s              | > 3s    |
+| **LCP**         | < 2.5s  | < 4s              | > 4s    |
+| **INP**         | < 200ms | < 500ms           | > 500ms |
+| **TBT**         | < 200ms | < 600ms           | > 600ms |
+| **CLS**         | < 0.1   | < 0.25            | > 0.25  |
+| **Speed Index** | < 3.4s  | < 5.8s            | > 5.8s  |
+
+---
+
+## 🔄 5-PHASE AUDIT WORKFLOW
+
+```
+Performance Audit:
+- [ ] Phase 1: Performance trace (navigate + record)
+- [ ] Phase 2: Core Web Vitals analysis (LCP, CLS, TBT)
+- [ ] Phase 3: Network analysis (render-blocking, chains)
+- [ ] Phase 4: Accessibility snapshot
+- [ ] Phase 5: Codebase analysis (if applicable)
+```
+
+---
+
+## 📋 Phase 1: Performance Trace
+
+```bash
+# Using Chrome DevTools MCP
+navigate_page(url: "<target-url>")
+performance_start_trace(autoStop: true, reload: true)
+```
+
+## 📋 Phase 2: Core Web Vitals
+
+| Metric | Insight Name     | What to Look For                      |
+| ------ | ---------------- | ------------------------------------- |
+| LCP    | `LCPBreakdown`   | TTFB, resource load, render delay     |
+| CLS    | `CLSCulprits`    | Images without dimensions, font swaps |
+| TBT    | `RenderBlocking` | CSS/JS blocking first paint           |
+
+## 📋 Phase 3: Network Analysis
+
+**Look for:**
+
+1. **Render-blocking resources** — JS/CSS without `async`/`defer`
+2. **Network chains** — Resources discovered late
+3. **Missing preloads** — Critical fonts, hero images
+4. **Caching issues** — Missing `Cache-Control`
+5. **Large payloads** — Uncompressed bundles
+
+## 📋 Phase 4: Accessibility
+
+```bash
+take_snapshot(verbose: true)
+```
+
+**Flag:**
+
+- Missing ARIA IDs
+- Poor contrast ratios (< 4.5:1)
+- Focus traps
+- Interactive elements without names
+
+## 📋 Phase 5: Codebase (if access)
+
+| Framework | Config Files        |
+| --------- | ------------------- |
+| Next.js   | `next.config.js`    |
+| Vite      | `vite.config.ts`    |
+| Webpack   | `webpack.config.js` |
+
+---
+
+## ⚡ Quick Wins Checklist
+
+```yaml
+critical:
+  - "Use <link rel=preload> for LCP image/font"
+  - "Add async/defer to non-critical JS"
+  - "Set explicit width/height on images"
+  - "Enable gzip/brotli compression"
+
+high:
+  - "Lazy load below-fold images"
+  - "Use next/image or WebP format"
+  - "Reduce main thread blocking"
+  - "Implement font-display: swap"
+
+medium:
+  - "Add Cache-Control headers"
+  - "Use CDN for static assets"
+  - "Preconnect to third-party origins"
+```
+
+---
+
+## 📊 Output Format
+
+```markdown
+## Core Web Vitals Summary
+
+| Metric | Value | Rating               |
+| ------ | ----- | -------------------- |
+| LCP    | 2.1s  | 🟢 Good              |
+| CLS    | 0.05  | 🟢 Good              |
+| TBT    | 450ms | 🟡 Needs Improvement |
+
+## Top Issues
+
+1. **Render-blocking CSS** (HIGH) — main.css blocks FCP
+2. **Missing image dimensions** (MEDIUM) — hero.jpg causes CLS
+
+## Recommendations
+
+1. Add `media="print"` to non-critical CSS
+2. Add `width` and `height` to all images
+```
+
+---
+
+## 🔧 Commands
+
+| Command         | Description            |
+| --------------- | ---------------------- |
+| `/perf [url]`   | Full performance audit |
+| `/perf vitals`  | Core Web Vitals only   |
+| `/perf network` | Network analysis       |
+| `/perf bundle`  | Bundle size analysis   |
+
+---
+
+## 🔌 HSA Integration
+
+This skill is powered by HSA adapter for semantic search across 4 performance domains:
+
+```python
+from .agent.scripts.hsa.adapters import (
+    search_webperf_patterns,
+    get_cwv_thresholds,
+    get_optimization_for,
+    get_framework_config,
+)
+
+# Get Core Web Vitals thresholds
+thresholds = get_cwv_thresholds()
+# → {"LCP": {"good": "< 2.5s", "poor": "> 4.0s"}, ...}
+
+# Get optimizations for specific metric
+optimizations = get_optimization_for("LCP")
+```
+
+**Available Functions**: `search_webperf_patterns`, `get_cwv_thresholds`, `get_optimization_for`, `get_framework_config`, `get_audit_checklist`
+
+---
+
+_DOMYH Awesome Code • Web-Perf • Core Web Vitals • HSA-Powered_

package/.agent/skills/cross-cutting/web-perf/data/cls_optimization.yaml

@@ -0,0 +1,189 @@
+# =============================================================================
+# CLS Optimization Patterns (Feb 2026)
+# =============================================================================
+# Cumulative Layout Shift prevention techniques
+
+metadata:
+  skill: web-perf
+  domain: cls-optimization
+  version: "2025.1"
+  updated: "2026-02-05"
+  patterns_count: 6
+
+patterns:
+  - id: cls001
+    name: Set Image Dimensions
+    category: CLS
+    impact: CRITICAL
+    description: Always specify width/height on images and video
+    text: image width height dimension aspect ratio cls shift
+    example: |
+      <!-- Always set dimensions -->
+      <img 
+        src="product.webp"
+        width="300"
+        height="200"
+        alt="Product"
+      >
+
+      <!-- Or use aspect-ratio CSS -->
+      <style>
+        .image-container {
+          aspect-ratio: 16 / 9;
+          width: 100%;
+        }
+        .image-container img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+      </style>
+    severity: CRITICAL
+    docs_url: https://web.dev/optimize-cls/
+
+  - id: cls002
+    name: Reserve Space for Ads
+    category: CLS
+    impact: HIGH
+    description: Set min-height for ad containers before loading
+    text: ad slot placeholder reserve space container dynamic content
+    example: |
+      <!-- Reserve space for common ad sizes -->
+      <style>
+        .ad-banner {
+          min-height: 90px; /* Leaderboard */
+          width: 728px;
+          background: #f1f1f1;
+        }
+        .ad-sidebar {
+          min-height: 250px; /* Medium rectangle */
+          width: 300px;
+        }
+      </style>
+
+      <div class="ad-banner">
+        <!-- Ad loads here -->
+      </div>
+    severity: HIGH
+    docs_url: https://web.dev/optimize-cls/#ads-embeds-and-iframes-without-dimensions
+
+  - id: cls003
+    name: Web Font Loading Strategy
+    category: CLS
+    impact: HIGH
+    description: Use font-display:swap and size-adjust for minimal shift
+    text: font display swap size adjust fallback loading foit fout
+    example: |
+      @font-face {
+        font-family: 'Inter';
+        font-display: swap;
+        src: url('/fonts/inter.woff2') format('woff2');
+        /* Size-adjust to match fallback metrics */
+        size-adjust: 106%;
+        ascent-override: 90%;
+        descent-override: 22%;
+      }
+
+      body {
+        font-family: 'Inter', -apple-system, sans-serif;
+      }
+
+      <!-- Preload critical fonts -->
+      <link 
+        rel="preload" 
+        href="/fonts/inter.woff2" 
+        as="font" 
+        type="font/woff2" 
+        crossorigin
+      >
+    severity: HIGH
+    docs_url: https://web.dev/optimize-cls/#web-fonts-causing-foutfoit
+
+  - id: cls004
+    name: Avoid Injecting Content Above
+    category: CLS
+    impact: HIGH
+    description: Don't dynamically insert content above existing content
+    text: inject content above insert shift notification banner toast
+    example: |
+      <!-- BAD: Banner pushes content down -->
+      <body>
+        <div id="banner"></div> <!-- Inserted later -->
+        <main>Content</main>
+      </body>
+
+      <!-- GOOD: Fixed position overlay -->
+      <style>
+        .notification {
+          position: fixed;
+          top: 0;
+          left: 0;
+          right: 0;
+          z-index: 1000;
+        }
+      </style>
+
+      <!-- Or reserve space from start -->
+      <div class="banner-slot" style="min-height: 50px;">
+        <!-- Banner loads here -->
+      </div>
+    severity: HIGH
+    docs_url: https://web.dev/optimize-cls/#dynamically-injected-content
+
+  - id: cls005
+    name: Transform for Animations
+    category: CLS
+    impact: MEDIUM
+    description: Use transform/opacity instead of properties that cause layout
+    text: animation transform opacity layout shift css transition
+    example: |
+      /* BAD: Animating layout properties */
+      .card:hover {
+        width: 110%;    /* Triggers layout */
+        height: 110%;   /* Triggers layout */
+      }
+
+      /* GOOD: Use transform (GPU accelerated) */
+      .card:hover {
+        transform: scale(1.1);
+      }
+
+      /* Smooth transitions without layout shift */
+      .modal-enter {
+        opacity: 0;
+        transform: translateY(-20px);
+      }
+      .modal-enter-active {
+        opacity: 1;
+        transform: translateY(0);
+        transition: all 0.3s ease-out;
+      }
+    severity: MEDIUM
+    docs_url: https://web.dev/animations-guide/
+
+  - id: cls006
+    name: BFCache Eligibility
+    category: CLS
+    impact: MEDIUM
+    description: Ensure pages qualify for back/forward cache
+    text: bfcache back forward cache eligibility navigation restore
+    example: |
+      // Avoid patterns that break BFCache:
+
+      // ❌ Unload event listener
+      window.addEventListener('unload', () => {});
+
+      // ✅ Use pagehide instead  
+      window.addEventListener('pagehide', (e) => {
+        if (e.persisted) {
+          // Page is going to BFCache
+        }
+      });
+
+      // ❌ Cache-Control: no-store
+      // ✅ Cache-Control: max-age=0, must-revalidate
+
+      // Test BFCache eligibility:
+      // Chrome DevTools → Application → Back/forward cache
+    severity: MEDIUM
+    docs_url: https://web.dev/bfcache/

package/.agent/skills/cross-cutting/web-perf/data/core_web_vitals.yaml

@@ -0,0 +1,282 @@
+# =============================================================================
+# Core Web Vitals 2026 Patterns (Feb 2026)
+# =============================================================================
+# LCP, INP, CLS thresholds and measurement
+
+metadata:
+  skill: web-perf
+  domain: core-web-vitals
+  version: "2026.1"
+  updated: "2026-02-05"
+  patterns_count: 10
+
+patterns:
+  - id: cwv001
+    name: LCP (Largest Contentful Paint)
+    category: loading
+    threshold_good: "< 2.5s"
+    threshold_poor: "> 4.0s"
+    description: Time until main content visible (largest image or text block)
+    text: lcp largest contentful paint loading performance main content
+    impact: User perceives page as loaded
+    example: |
+      <!-- Optimize LCP element -->
+      <img
+        src="hero.webp"
+        fetchpriority="high"
+        width="1200"
+        height="600"
+        alt="Hero"
+      >
+
+      <!-- Preload critical resources -->
+      <link rel="preload" href="hero.webp" as="image">
+    severity: CRITICAL
+    docs_url: https://web.dev/lcp/
+
+  - id: cwv002
+    name: INP (Interaction to Next Paint)
+    category: responsiveness
+    threshold_good: "< 200ms"
+    threshold_poor: "> 500ms"
+    description: Overall responsiveness to user interactions (replaced FID in 2024)
+    text: inp interaction next paint responsiveness click tap input latency
+    impact: User feels site is responsive
+    example: |
+      // Break up long tasks
+      async function heavyOperation() {
+        const chunks = splitIntoChunks(data);
+        for (const chunk of chunks) {
+          processChunk(chunk);
+          // Yield to main thread
+          await scheduler.yield();
+        }
+      }
+
+      // Use requestIdleCallback for non-urgent work
+      requestIdleCallback(() => {
+        analytics.track('page_view');
+      });
+    severity: CRITICAL
+    docs_url: https://web.dev/inp/
+
+  - id: cwv003
+    name: CLS (Cumulative Layout Shift)
+    category: stability
+    threshold_good: "< 0.1"
+    threshold_poor: "> 0.25"
+    description: Visual stability - do elements shift while loading?
+    text: cls cumulative layout shift stability visual jank movement
+    impact: User doesn't misclick or lose reading position
+    example: |
+      <!-- Always set dimensions -->
+      <img 
+        src="product.webp" 
+        width="300" 
+        height="200"
+        alt="Product"
+      >
+
+      <!-- Reserve space for dynamic content -->
+      <div class="ad-slot" style="min-height: 250px;">
+        <!-- Ad loads here -->
+      </div>
+
+      /* CSS for font loading */
+      @font-face {
+        font-family: 'Custom';
+        font-display: swap;
+        src: url('custom.woff2') format('woff2');
+      }
+    severity: CRITICAL
+    docs_url: https://web.dev/cls/
+
+  - id: cwv004
+    name: TTFB (Time to First Byte)
+    category: server
+    threshold_good: "< 800ms"
+    threshold_poor: "> 1800ms"
+    description: Server response time - affects all other metrics
+    text: ttfb time first byte server response latency backend
+    impact: Foundation for all loading metrics
+    example: |
+      # Server-side optimizations
+      - Use CDN with edge caching
+      - Optimize database queries
+      - Enable HTTP/2 or HTTP/3
+      - Add cache headers:
+        Cache-Control: public, max-age=31536000
+
+      # Preconnect to origins
+      <link rel="preconnect" href="https://api.example.com">
+    severity: HIGH
+    docs_url: https://web.dev/ttfb/
+
+  - id: cwv005
+    name: FCP (First Contentful Paint)
+    category: loading
+    threshold_good: "< 1.8s"
+    threshold_poor: "> 3.0s"
+    description: First content rendered - something is happening
+    text: fcp first contentful paint loading render start
+    impact: User sees progress, reducing abandonment
+    example: |
+      <!-- Inline critical CSS -->
+      <style>
+        .hero { background: #3b82f6; min-height: 100vh; }
+        .nav { height: 60px; background: #1e293b; }
+      </style>
+
+      <!-- Defer non-critical CSS -->
+      <link rel="preload" href="styles.css" as="style" onload="this.rel='stylesheet'">
+    severity: HIGH
+    docs_url: https://web.dev/fcp/
+
+  - id: cwv006
+    name: Mobile-First 2026
+    category: ranking
+    version: "2026"
+    description: Mobile Core Web Vitals carry more weight in 2026 rankings
+    text: mobile first ranking google seo performance scores mobile-centric
+    impact: Mobile scores increasingly important for SEO
+    example: |
+      <!-- Mobile-First Optimization Checklist -->
+
+      1. Test on real mobile devices, not just emulation
+      2. Use responsive images with srcset
+      3. Minimize JavaScript (target < 100KB gzipped)
+      4. Prioritize above-the-fold content
+      5. Use touch-appropriate interaction targets (48px+)
+
+      <!-- Lighthouse: Run mobile audit -->
+      lighthouse https://example.com --preset=desktop,mobile
+
+      <!-- Focus metrics for mobile -->
+      - LCP: Target < 2.0s (stricter than desktop)
+      - INP: Critical on touch devices
+      - CLS: Font loading crucial on slow connections
+    severity: CRITICAL
+    docs_url: https://web.dev/vitals/
+
+  - id: cwv007
+    name: Real User Monitoring (RUM)
+    category: measurement
+    version: "2025+"
+    description: Lab data + Field data = Complete picture (RUM increasingly important)
+    text: rum real user monitoring field data crux chrome ux report
+    impact: Google uses CrUX field data for rankings
+    example: |
+      // web-vitals library for field data
+      import { onLCP, onINP, onCLS } from 'web-vitals';
+
+      // Collect real user metrics
+      onLCP(metric => sendToAnalytics(metric));
+      onINP(metric => sendToAnalytics(metric));
+      onCLS(metric => sendToAnalytics(metric));
+
+      // Check CrUX data via PageSpeed Insights API
+      // or BigQuery for historical trends
+
+      // Key insight: Lab data (Lighthouse) != Field data (CrUX)
+      // Both are needed, but field data affects rankings
+    severity: HIGH
+    docs_url: https://web.dev/vitals-field-measurement-best-practices/
+
+  # ✅ NEW: 2026 INP Optimization & Trends
+  - id: cwv008
+    name: INP Optimization Strategies
+    category: responsiveness
+    version: "2026"
+    description: |
+      Deep INP optimization: Web Workers, DOM batching, input delay reduction.
+      INP stable since March 2024, now critical for rankings.
+    text: inp optimization web workers dom batching input delay main thread
+    example: |
+      // ✅ 1. Web Workers for CPU-intensive tasks
+      const worker = new Worker('processor.js');
+      worker.postMessage({ data: heavyData });
+      worker.onmessage = (e) => updateUI(e.data);
+
+      // ✅ 2. DOM Read/Write Batching (avoid layout thrashing)
+      // BAD: read-write interleaved
+      elements.forEach(el => {
+        const width = el.offsetWidth;  // Force layout
+        el.style.width = width + 10;   // Force layout again
+      });
+
+      // GOOD: batch reads, then writes
+      const widths = elements.map(el => el.offsetWidth);
+      elements.forEach((el, i) => el.style.width = widths[i] + 10);
+
+      // ✅ 3. Yield to main thread
+      await scheduler.yield();
+
+      // ✅ 4. Remove recurring timers that block interaction
+      // Avoid: setInterval(() => heavyWork(), 100);
+    severity: CRITICAL
+    docs_url: https://web.dev/optimize-inp/
+
+  - id: cwv009
+    name: Stricter 2026 Thresholds
+    category: ranking
+    version: "2026"
+    description: |
+      2026 trends: stricter thresholds expected, real user data > lab scores,
+      accessibility increasingly linked with performance.
+    text: thresholds 2026 stricter field data real user accessibility seo
+    example: |
+      // 2026 Performance Trends
+
+      // 1. Stricter thresholds coming
+      // - LCP: May tighten to < 2.0s for "good"
+      // - INP: < 200ms threshold now, may become < 150ms
+
+      // 2. Field data trumps lab data
+      // - Lighthouse 10.0 ≠ Real user experience
+      // - CrUX data directly affects rankings
+
+      // 3. Test on real devices
+      const isMobile = /Mobi|Android/i.test(navigator.userAgent);
+      if (isMobile) {
+        // Apply mobile-specific optimizations
+      }
+
+      // 4. Monitor with RUM
+      import { onINP } from 'web-vitals';
+      onINP(({ value, delta }) => {
+        if (value > 200) console.warn('Poor INP:', value);
+      });
+    severity: HIGH
+    docs_url: https://web.dev/vitals/
+
+  - id: cwv010
+    name: Accessibility-Performance Link
+    category: quality
+    version: "2026"
+    description: |
+      Cleaner content = faster + more accessible.
+      Heavy pop-ups, banners, animations hurt both.
+    text: accessibility a11y performance link clean content structure semantic
+    example: |
+      <!-- ✅ Clean structure = Fast + Accessible -->
+
+      <!-- 1. Reduce heavy pop-ups and banners -->
+      <!-- They hurt CLS and accessibility -->
+
+      <!-- 2. Prefer reduced motion -->
+      @media (prefers-reduced-motion: reduce) {
+        * { animation: none !important; }
+      }
+
+      <!-- 3. Semantic HTML = less JavaScript -->
+      <nav aria-label="Main">...</nav>
+      <main>...</main>
+      <footer>...</footer>
+
+      <!-- 4. Skip links for keyboard users -->
+      <a href="#main" class="skip-link">Skip to content</a>
+
+      <!-- 5. Focus visible for interactability -->
+      :focus-visible { outline: 2px solid #3b82f6; }
+    severity: HIGH
+    docs_url: https://web.dev/accessibility/