diff --git a/.agent/scripts/commands/performance.md b/.agent/scripts/commands/performance.md new file mode 100644 index 000000000..5502dcb86 --- /dev/null +++ b/.agent/scripts/commands/performance.md @@ -0,0 +1,109 @@ +--- +description: Run comprehensive web performance analysis (Core Web Vitals, network, accessibility) +agent: Build+ +mode: subagent +--- + +Analyze web performance for the specified URL using Chrome DevTools MCP. + +URL/Target: $ARGUMENTS + +## Workflow + +### Step 1: Parse Arguments + +```text +Default: Full audit (performance + accessibility + network) +Options: + --categories=performance,accessibility,network Specific categories + --device=mobile|desktop Device emulation (default: mobile) + --iterations=N Number of runs for averaging (default: 3) + --compare=baseline.json Compare against baseline + --local Assume localhost URL +``` + +### Step 2: Check Prerequisites + +```bash +# Verify Chrome DevTools MCP is available +which npx && npx chrome-devtools-mcp@latest --version || echo "Install: npm i -g chrome-devtools-mcp" +``` + +### Step 3: Read Performance Subagent + +Read `~/.aidevops/agents/tools/performance/performance.md` for: +- Core Web Vitals thresholds +- Common issues and fixes +- Actionable output format + +### Step 4: Run Analysis + +Using Chrome DevTools MCP: + +1. **Lighthouse Audit** - Performance, accessibility, best practices, SEO scores +2. **Core Web Vitals** - FCP, LCP, CLS, FID, TTFB measurements +3. **Network Analysis** - Third-party scripts, request chains, bundle sizes +4. **Accessibility Check** - WCAG compliance issues + +### Step 5: Generate Report + +Output in actionable format: + +```markdown +## Performance Report: [URL] + +### Core Web Vitals +| Metric | Value | Status | Target | +|--------|-------|--------|--------| +| LCP | X.Xs | GOOD/NEEDS WORK/POOR | <2.5s | +| FID | Xms | GOOD/NEEDS WORK/POOR | <100ms | +| CLS | X.XX | GOOD/NEEDS WORK/POOR | <0.1 | +| TTFB | Xms | GOOD/NEEDS WORK/POOR | <800ms | + +### Top Issues (Priority Order) +1. **Issue** - Description + - File: `path/to/file:line` + - Fix: Specific recommendation + +### Network Dependencies +- X third-party scripts +- Longest chain: X requests +- Total blocking time: Xms + +### Accessibility +- Score: X/100 +- X issues found +``` + +### Step 6: Provide Fixes + +For each issue, provide: +1. **What**: The specific problem +2. **Where**: File path and line number (if in repo) +3. **How**: Code snippet or configuration change +4. **Impact**: Expected improvement + +## Examples + +```bash +# Full audit of production site +/performance https://example.com + +# Local dev server +/performance http://localhost:3000 --local + +# Mobile-specific audit +/performance https://example.com --device=mobile + +# Compare against baseline +/performance https://example.com --compare=baseline.json + +# Specific categories only +/performance https://example.com --categories=performance,accessibility +``` + +## Related + +- `tools/performance/performance.md` - Full performance subagent +- `tools/browser/pagespeed.md` - PageSpeed Insights integration +- `tools/browser/chrome-devtools.md` - Chrome DevTools MCP diff --git a/.agent/subagent-index.toon b/.agent/subagent-index.toon index 0253c1669..4e2a816fa 100644 --- a/.agent/subagent-index.toon +++ b/.agent/subagent-index.toon @@ -22,7 +22,7 @@ flash,gemini-2.5-flash,Fast cheap large context pro,gemini-2.5-pro,Capable large context --> - + +## Quick Reference + +- **Purpose**: Comprehensive web performance analysis from within your repo +- **Dependencies**: Chrome DevTools MCP (`npx chrome-devtools-mcp@latest`) +- **Core Metrics**: FCP (<1.8s), LCP (<2.5s), CLS (<0.1), FID (<100ms), TTFB (<800ms) +- **Categories**: Performance, Network Dependencies, Core Web Vitals, Accessibility +- **Related**: `tools/browser/pagespeed.md`, `tools/browser/chrome-devtools.md` + +**Quick commands**: + +```bash +# Full performance audit (Lighthouse + Core Web Vitals) +/performance https://example.com + +# Specific categories +/performance https://example.com --categories=performance,accessibility + +# Local dev server +/performance http://localhost:3000 + +# Compare before/after +/performance https://example.com --compare baseline.json +``` + + + +## Overview + +This subagent provides comprehensive web performance analysis inspired by [@elithrar's web-perf agent skill](https://x.com/elithrar/status/2006028034889887973). It uses Chrome DevTools MCP to assess: + +1. **Core Web Vitals** - FCP, LCP, CLS, FID, TTFB +2. **Performance** - Load times, render blocking, JavaScript execution +3. **Network Dependencies** - Third-party scripts, request chains, bundle sizes +4. **Accessibility** - WCAG compliance, keyboard navigation, screen reader support + +The key advantage: running from within your repo means the output becomes immediate context for making improvements. + +## Setup + +### Chrome DevTools MCP + +```bash +# Install globally (recommended) +npm install -g chrome-devtools-mcp + +# Or run via npx +npx chrome-devtools-mcp@latest --headless +``` + +### MCP Configuration + +Add to your MCP config (Claude Code, OpenCode, etc.): + +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["chrome-devtools-mcp@latest", "--headless"] + } + } +} +``` + +For connecting to an existing browser: + +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"] + } + } +} +``` + +## Usage Workflows + +### 1. Full Performance Audit + +Run a comprehensive Lighthouse audit with Core Web Vitals: + +```javascript +// Via Chrome DevTools MCP +await chromeDevTools.lighthouse({ + url: "https://your-site.com", + categories: ["performance", "accessibility", "best-practices", "seo"], + device: "mobile" // or "desktop" +}); + +// Get Core Web Vitals +await chromeDevTools.measureWebVitals({ + url: "https://your-site.com", + metrics: ["LCP", "FID", "CLS", "TTFB", "FCP"], + iterations: 3 // Average over multiple runs +}); +``` + +### 2. Network Dependency Analysis + +Identify third-party scripts and request chains impacting performance: + +```javascript +// Monitor network requests +await chromeDevTools.monitorNetwork({ + url: "https://your-site.com", + filters: ["script", "xhr", "fetch"], + captureHeaders: true, + captureBody: false +}); + +// Analyze third-party impact +// Look for: +// - Scripts from external domains +// - Long request chains (A -> B -> C) +// - Large bundle sizes (>100KB compressed) +// - Render-blocking resources +``` + +### 3. Local Development Testing + +Test your local dev server before deploying: + +```javascript +// Start your dev server first (e.g., npm run dev) +await chromeDevTools.lighthouse({ + url: "http://localhost:3000", + categories: ["performance"], + device: "desktop" +}); + +// Monitor for console errors during interaction +await chromeDevTools.captureConsole({ + url: "http://localhost:3000", + logLevel: "error", + duration: 30000 +}); +``` + +### 4. Before/After Comparison + +Compare performance before and after changes: + +```javascript +// Baseline (save results) +const baseline = await chromeDevTools.lighthouse({ + url: "https://your-site.com", + categories: ["performance"] +}); +// Save baseline.json + +// After changes +const after = await chromeDevTools.lighthouse({ + url: "https://your-site.com", + categories: ["performance"] +}); + +// Compare key metrics: +// - Performance score delta +// - LCP improvement +// - CLS reduction +// - Total blocking time change +``` + +### 5. Accessibility Audit + +Check WCAG compliance and accessibility issues: + +```javascript +await chromeDevTools.lighthouse({ + url: "https://your-site.com", + categories: ["accessibility"], + device: "desktop" +}); + +// Common issues to check: +// - Missing alt text on images +// - Low color contrast +// - Missing form labels +// - Keyboard navigation issues +// - ARIA attribute problems +``` + +## Core Web Vitals Thresholds + +| Metric | Good | Needs Improvement | Poor | +|--------|------|-------------------|------| +| **FCP** (First Contentful Paint) | <1.8s | 1.8s - 3.0s | >3.0s | +| **LCP** (Largest Contentful Paint) | <2.5s | 2.5s - 4.0s | >4.0s | +| **CLS** (Cumulative Layout Shift) | <0.1 | 0.1 - 0.25 | >0.25 | +| **FID** (First Input Delay) | <100ms | 100ms - 300ms | >300ms | +| **TTFB** (Time to First Byte) | <800ms | 800ms - 1800ms | >1800ms | +| **INP** (Interaction to Next Paint) | <200ms | 200ms - 500ms | >500ms | + +## Common Performance Issues & Fixes + +### Slow LCP + +**Causes**: +- Large hero images not optimized +- Render-blocking CSS/JS +- Slow server response (TTFB) +- Client-side rendering delays + +**Fixes**: +```html + + + + + + + + Hero + +``` + +### High CLS + +**Causes**: +- Images without dimensions +- Ads/embeds without reserved space +- Web fonts causing FOUT/FOIT +- Dynamic content injection + +**Fixes**: +```html + +Photo + + +
+ +
+ + +@font-face { + font-family: 'Custom'; + font-display: swap; + src: url('/font.woff2') format('woff2'); +} +``` + +### Poor FID/INP + +**Causes**: +- Long JavaScript tasks (>50ms) +- Heavy main thread work +- Large JavaScript bundles +- Synchronous third-party scripts + +**Fixes**: +```javascript +// Break up long tasks +function processItems(items) { + const chunk = items.splice(0, 100); + // Process chunk... + if (items.length > 0) { + requestIdleCallback(() => processItems(items)); + } +} + +// Defer non-critical JS + + +// Use web workers for heavy computation +const worker = new Worker('/heavy-task.js'); +``` + +### Slow TTFB + +**Causes**: +- Slow database queries +- No caching +- Geographic distance to server +- Cold starts (serverless) + +**Fixes**: +- Add CDN (Cloudflare, Fastly, Vercel Edge) +- Implement caching (Redis, Memcached) +- Optimize database queries +- Use edge functions for dynamic content + +## Network Dependency Best Practices + +### Third-Party Script Audit + +```javascript +// Identify third-party scripts +const thirdParty = requests.filter(r => + !r.url.includes(yourDomain) && + r.resourceType === 'script' +); + +// Check for: +// 1. Scripts blocking render +// 2. Large bundle sizes (>50KB) +// 3. Long chains (script A loads script B) +// 4. Scripts without async/defer +``` + +### Bundle Size Analysis + +```bash +# Analyze JavaScript bundles +npx source-map-explorer dist/main.js + +# Check compressed sizes +ls -la dist/*.js | awk '{print $5, $9}' +gzip -c dist/main.js | wc -c # Compressed size +``` + +### Request Chain Optimization + +```html + + + + + + + + +``` + +## Integration with Existing Tools + +### With PageSpeed Helper + +```bash +# Use pagespeed-helper.sh for quick audits +~/.aidevops/agents/scripts/pagespeed-helper.sh audit https://example.com + +# Use Chrome DevTools MCP for deeper analysis +npx chrome-devtools-mcp@latest --headless +``` + +### With Browser Automation + +```bash +# Start dev-browser for persistent testing +~/.aidevops/agents/scripts/dev-browser-helper.sh start + +# Connect Chrome DevTools MCP +npx chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222 +``` + +### With CI/CD + +```yaml +# GitHub Actions example +- name: Performance Audit + run: | + npx lighthouse https://staging.example.com \ + --output=json \ + --output-path=lighthouse.json \ + --chrome-flags="--headless" + + # Check performance score + SCORE=$(jq '.categories.performance.score * 100 | round' lighthouse.json) + if [ "$SCORE" -lt 90 ]; then + echo "Performance score $SCORE is below threshold (90)" + exit 1 + fi +``` + +## Actionable Output Format + +When running performance analysis, provide output in this format for immediate action: + +```markdown +## Performance Report: example.com + +### Core Web Vitals +| Metric | Value | Status | Target | +|--------|-------|--------|--------| +| LCP | 2.1s | GOOD | <2.5s | +| FID | 45ms | GOOD | <100ms | +| CLS | 0.15 | NEEDS WORK | <0.1 | +| TTFB | 650ms | GOOD | <800ms | + +### Top Issues (Priority Order) +1. **CLS: 0.15** - Images without dimensions + - File: `src/components/Hero.tsx:24` + - Fix: Add `width` and `height` attributes + +2. **Render-blocking CSS** - 2 stylesheets + - Files: `styles/fonts.css`, `styles/above-fold.css` + - Fix: Inline critical CSS, defer non-critical + +3. **Large JavaScript bundle** - 245KB (gzipped) + - File: `dist/main.js` + - Fix: Code split, lazy load routes + +### Network Dependencies +- 3 third-party scripts (analytics, chat, fonts) +- Longest chain: 3 requests (Google Fonts) +- Total blocking time: 120ms + +### Accessibility +- Score: 92/100 +- 2 issues: Missing alt text (2 images) +``` + +## Related Resources + +- [web.dev/vitals](https://web.dev/vitals/) - Core Web Vitals documentation +- [Chrome DevTools Performance](https://developer.chrome.com/docs/devtools/performance/) +- [Lighthouse Scoring](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/) +- [PageSpeed Insights](https://pagespeed.web.dev/) + +## Related Subagents + +- `tools/browser/pagespeed.md` - PageSpeed Insights & Lighthouse CLI +- `tools/browser/chrome-devtools.md` - Chrome DevTools MCP integration +- `tools/browser/browser-automation.md` - Browser tool selection guide