| name | performance-optimizer |
| description | Use when optimizing application or system performance — dispatches profiling-analyst, frontend-optimizer, backend-optimizer, infra-tuner, and performance-reviewer to identify bottlenecks, implement optimizations, and validate improvements with ROI estimation. Covers full-stack performance from Core Web Vitals through API latency, database queries, caching, and infrastructure tuning. Does NOT cover application security review (use security harness), load testing execution, or capacity planning for new systems. Also triggers on: speed up my app, fix slow page load, reduce API latency, optimize Core Web Vitals, tune Kubernetes scaling, reduce infrastructure costs. |
| metadata | {"category":"harness","harness":"29-performance-optimizer","agent_type":"general-purpose"} |
Performance Optimizer — Full-Stack Performance Pipeline
A 5-agent team profiles system bottlenecks, optimizes frontend and backend performance, tunes infrastructure, and produces a validated improvement report with ROI estimation.
Execution Mode
File-Bus Team — Agents communicate via _workspace/messages/, orchestrator sequences execution.
Agent Composition
| Agent | File | Role | Type |
|---|
| profiling-analyst | agents/profiling-analyst.md | Bottleneck identification, baseline metrics | general-purpose |
| frontend-optimizer | agents/frontend-optimizer.md | Core Web Vitals, bundles, images, CDN | general-purpose |
| backend-optimizer | agents/backend-optimizer.md | API latency, N+1, Redis caching, pools | general-purpose |
| infra-tuner | agents/infra-tuner.md | HPA, VPA, CDN config, PgBouncer | general-purpose |
| performance-reviewer | agents/performance-reviewer.md | Before/after, ROI, SLOs, budgets | general-purpose |
Workspace Layout
_workspace/
├── 00_input.md (system under review, performance targets, current metrics if known)
├── 01_profiling_report.md (profiling-analyst output: bottleneck map, baseline metrics)
├── 02_frontend_optimizations.md (frontend-optimizer output)
├── 03_backend_optimizations.md (backend-optimizer output)
├── 04_infra_tuning.md (infra-tuner output)
├── 05_performance_review.md (performance-reviewer output — TERMINAL)
└── messages/
├── profiling-analyst-to-frontend-optimizer.md
├── profiling-analyst-to-backend-optimizer.md
├── frontend-optimizer-to-infra-tuner.md
├── backend-optimizer-to-infra-tuner.md
└── infra-tuner-to-performance-reviewer.md
Pre-Flight Checks
Phase 1: Setup (Orchestrator)
task(agent_type="general-purpose",
description="Read the user's performance optimization request. Create _workspace/ and _workspace/messages/ directories. Extract: system_under_review (URL/service/application), performance_targets (LCP target, API latency target, Apdex target), current_metrics (if provided), tech_stack (frontend framework, backend language, database, infrastructure). Write organized input to _workspace/00_input.md with sections: SYSTEM, PERFORMANCE_TARGETS, CURRENT_METRICS, TECH_STACK, ADDITIONAL_CONTEXT.")
Phase 2: Profiling & Analysis
Step 2.1 — Profiling Analyst
task(agent_type="general-purpose",
description="You are the profiling-analyst agent in the performance-optimizer harness. Read agents/profiling-analyst.md for your full instructions. Read _workspace/00_input.md. Perform comprehensive performance profiling: identify bottlenecks using the USE method (Utilization, Saturation, Errors), establish baseline metrics (P50/P95/P99 latency, RPS, error rate, Apdex score), analyze flame graphs or profiling data if provided, quantify frontend vs backend split, and produce a prioritized bottleneck map. Write full report to _workspace/01_profiling_report.md. Write BOTH: _workspace/messages/profiling-analyst-to-frontend-optimizer.md (with FRONTEND_BOTTLENECKS) AND _workspace/messages/profiling-analyst-to-backend-optimizer.md (with BACKEND_BOTTLENECKS and DATABASE_HINTS). Both messages need STATUS: COMPLETE and BASELINE_METRICS.")
Phase 3: Parallel Optimization (run sequentially)
Step 3.1 — Frontend Optimizer (reads from 2.1)
task(agent_type="general-purpose",
description="You are the frontend-optimizer agent in the performance-optimizer harness. Read agents/frontend-optimizer.md for your full instructions. Read _workspace/00_input.md, _workspace/01_profiling_report.md, and _workspace/messages/profiling-analyst-to-frontend-optimizer.md. Optimize frontend performance: analyze and fix Core Web Vitals (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1), produce bundle analysis with code splitting plan, design image optimization strategy (WebP/AVIF, lazy loading, srcset), configure CDN caching headers, and define critical CSS strategy. Quantify expected improvement per change. Write to _workspace/02_frontend_optimizations.md. Write handoff to _workspace/messages/frontend-optimizer-to-infra-tuner.md with STATUS: COMPLETE, FINDINGS, CDN_REQUIREMENTS, INFRA_CHANGES. Also consult references/performance-checklist.md for the full frontend performance checklist.")
Step 3.2 — Backend Optimizer (reads from 2.1)
task(agent_type="general-purpose",
description="You are the backend-optimizer agent in the performance-optimizer harness. Read agents/backend-optimizer.md for your full instructions. Read _workspace/00_input.md, _workspace/01_profiling_report.md, and _workspace/messages/profiling-analyst-to-backend-optimizer.md. Optimize backend performance: analyze slow API endpoints, detect and fix N+1 queries (DataLoader/eager loading), design Redis caching strategy (cache-aside, write-through, TTL by data type), size connection pools (PgBouncer formula), and identify async optimization opportunities. Quantify expected latency improvement per change. Write to _workspace/03_backend_optimizations.md. Write handoff to _workspace/messages/backend-optimizer-to-infra-tuner.md with STATUS: COMPLETE, FINDINGS, INFRA_REQUIREMENTS, DATABASE_CHANGES, CACHE_REQUIREMENTS.")
Phase 4: Infrastructure Tuning
Step 4.1 — Infra Tuner (reads from 3.1 and 3.2)
task(agent_type="general-purpose",
description="You are the infra-tuner agent in the performance-optimizer harness. Read agents/infra-tuner.md for your full instructions. Read _workspace/00_input.md, _workspace/01_profiling_report.md, _workspace/02_frontend_optimizations.md, _workspace/03_backend_optimizations.md, _workspace/messages/frontend-optimizer-to-infra-tuner.md, and _workspace/messages/backend-optimizer-to-infra-tuner.md. Tune infrastructure: configure Kubernetes HPA (CPU/memory targets at 65%, stabilization windows: 60s scale-up, 300s scale-down), apply VPA recommendations for right-sizing, optimize CDN cache hit ratio (target > 90%, fix Vary headers, cache-control headers, enable origin shield), configure PgBouncer (transaction mode, size pools correctly), define auto-scaling warm-up strategy (preStop hooks, readiness probes). Write to _workspace/04_infra_tuning.md. Write handoff to _workspace/messages/infra-tuner-to-performance-reviewer.md with STATUS: COMPLETE, FINDINGS, SCALING_IMPROVEMENTS, CDN_IMPROVEMENTS, RISK_ITEMS, COST_IMPACT.")
Phase 5: Review & Validation
Step 5.1 — Performance Reviewer (Terminal)
task(agent_type="general-purpose",
description="You are the performance-reviewer agent in the performance-optimizer harness. Read agents/performance-reviewer.md for your full instructions. Read ALL workspace files: _workspace/00_input.md, _workspace/01_profiling_report.md, _workspace/02_frontend_optimizations.md, _workspace/03_backend_optimizations.md, _workspace/04_infra_tuning.md, and all 5 message files in _workspace/messages/. Validate performance improvements: produce before/after comparison table for all key metrics, calculate ROI (revenue impact using Amazon latency-revenue rule, infrastructure cost delta), define CI performance budgets (Lighthouse CI thresholds), define SLOs with error budgets for all critical services, recommend monitoring alert thresholds, and assess rollback risk for each change. Final verdict: APPROVED/CHANGES REQUIRED/BLOCKED. Write to _workspace/05_performance_review.md.")
Scale Modes
| Request Pattern | Mode | Agents Used |
|---|
| Full performance audit | Full Pipeline | All 5 |
| Frontend only | Frontend Mode | profiling-analyst + frontend-optimizer + performance-reviewer |
| Backend/DB only | Backend Mode | profiling-analyst + backend-optimizer + performance-reviewer |
| Infra tuning only | Infra Mode | profiling-analyst + infra-tuner + performance-reviewer |
| Quick assessment | Review Mode | performance-reviewer (direct analysis from provided metrics) |
Error Handling
| Error Type | Strategy |
|---|
| Agent output file missing | Re-run agent once; performance-reviewer notes unavailable for that domain |
| No profiling data provided | profiling-analyst documents assumptions from tech stack defaults |
| Ambiguous performance target | Default to Google Core Web Vitals Good thresholds; document in 00_input.md |
| Conflicting frontend vs infra requirements | infra-tuner resolves; escalate to user if unresolvable |
| Target not found | Ask user to clarify before proceeding |
Test Scenarios
- Normal case: "My React+Node.js app is slow, LCP is 4s and API p99 is 800ms" → full pipeline produces profiling + frontend + backend + infra + review report
- Existing profiling:
01_profiling_report.md already present → skip Phase 2, run optimization agents directly
- Error case: Frontend optimizer output missing → infra-tuner uses profiling data only, performance-reviewer notes partial data
Performance Standards
Optimization Workflow (Measure First)
Instruct the profiling-analyst to always follow this 5-step process:
1. MEASURE → Establish baseline with real data (not assumptions)
2. IDENTIFY → Find the actual bottleneck (not assumed bottleneck)
3. FIX → Address the specific bottleneck identified
4. VERIFY → Measure again, confirm the improvement with numbers
5. GUARD → Add monitoring or CI performance budgets to prevent regression
The GUARD step is mandatory. An optimization without regression protection will be undone by the next feature change. Every optimization must result in either a CI performance budget check or a monitoring alert threshold.
Core Web Vitals Targets
Instruct the frontend-optimizer to target these thresholds (Google's "Good" tier):
| Metric | Good | Needs Work | Poor |
|---|
| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
Any optimization must demonstrate movement toward the "Good" tier with before/after measurements.
Performance Budget
Instruct agents to enforce these budgets and flag violations:
JavaScript bundle: < 200KB gzipped (initial load)
CSS: < 50KB gzipped
API response time: < 200ms (P95)
Time to Interactive: < 3.5s on 4G
Lighthouse Performance score: ≥ 90
Violations must be included in _workspace/05_performance_review.md as actionable findings.
What Counts as Done
Performance work is only complete when:
- Before and after measurements exist (specific numbers, not "it feels faster")
- The specific bottleneck is identified and addressed
- Core Web Vitals are within "Good" thresholds (or documented deviation with justification)
- A regression guard is in place (CI budget check or monitoring alert)
Common Rationalizations
| Rationalization | Reality |
|---|
| "We'll optimize later" | Performance debt compounds. Fix obvious anti-patterns now, defer micro-optimizations. |
| "It's fast on my machine" | Your machine isn't the user's. Profile on representative hardware and networks. |
| "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
| "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
| "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
Red Flags
- Optimization without profiling data to justify it
- N+1 query patterns in data fetching code
- List endpoints without pagination
- Images without dimensions, lazy loading, or responsive sizes
- Bundle size growing without review
- No performance monitoring in production
- Claiming "done" without before/after measurement numbers
Verification
After the full performance optimization pipeline completes:
