How Engineering Agents Ensure Core Web Vitals Optimization in Agency-Agents

Engineering agents in the Agency-Agents repository ensure Core Web Vitals optimization by embedding hard-coded performance mandates into role definitions, enforcing critical rules through automated CI/CD pipelines, and continuously monitoring real-user metrics against strict LCP, FID, and CLS thresholds.

The msitarzewski/agency-agents repository implements a multi-layered system where specialized engineering agents treat Core Web Vitals (CWV) as non-negotiable constraints rather than optional optimizations. This architecture combines role-specific mandates, automated tooling, and continuous shadow-testing to guarantee that every web project meets Google’s performance standards from inception through production.

Role-Specific Mandates for Core Web Vitals

Each engineering agent in the system carries explicit CWV responsibilities defined in markdown role files. These mandates are parsed by the workflow engine and converted into enforcement policies during task execution.

Frontend Developer Agent

The Frontend Developer agent, defined in engineering/engineering-frontend-developer.md, includes specific critical rules stating: "Implement Core Web Vitals optimization from the start" and "Core Web Vitals optimization for excellent page performance." These instructions mandate the use of modern performance techniques including code splitting, lazy loading, and image optimization.

Autonomous Optimization Architect

The Autonomous Optimization Architect, detailed in engineering/engineering-autonomous-optimization-architect.md, continuously shadow-tests APIs and enforces budgeted latency and cost constraints. This includes CWV thresholds for any UI-facing endpoint, ensuring that backend performance directly supports frontend Core Web Vitals targets.

Performance Benchmarker

The Performance Benchmarker agent, specified in testing/testing-performance-benchmarker.md, provides a concrete CWV analysis checklist and establishes baseline metrics. This agent supplies k6 testing scripts that proxy CWV measurements through latency thresholds, ensuring measurable performance standards before deployment.

Agent Activation Prompts

All activation prompts in strategy/coordination/agent-activation-prompts.md explicitly require engineers to "Optimize for Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)." The platform parses these targets and blocks task execution if current project telemetry does not meet the specified thresholds.

Critical Rules Engine

Each agent includes a 🚨 Critical Rules block that the platform treats as non-negotiable constraints. The workflow engine reads these rules from the markdown role definitions and automatically implements a four-stage enforcement pipeline:

1. Static Analysis: Linting scripts verify that the project's package.json contains performance-related dependencies such as @tanstack/react-virtual and webpack-bundle-analyzer.

2. Build Configuration: Build scripts defined in scripts/lint-agents.sh inject webpack or Vite settings for code-splitting, lazy-loading, and asset optimization.

3. CI/CD Guardrails: The CI pipeline runs a Lighthouse CI job after each pull request. A failure in the Performance category blocks merge until CWV thresholds are met.

4. Runtime Monitoring: A thin Telemetry library included in all agents pushes Real-User-Monitoring (RUM) data to a dashboard. Alerts fire automatically if LCP exceeds 2.5 seconds, FID exceeds 100 milliseconds, or CLS exceeds 0.1.

Automated Tooling and Templates

The repository provides concrete implementations that engineering agents use to satisfy CWV requirements.

Performance Testing with k6

The Performance Benchmarker supplies a k6 script that measures request latency as a proxy for CWV metrics. This script enforces that 95% of requests complete within 500 milliseconds, correlating directly with First Input Delay and Largest Contentful Paint targets:

// performance-test.cwv.js
import http from 'k6/http';
import { check, sleep } from 'k6';
import { Trend, Rate } from 'k6/metrics';

const responseTime = new Trend('cwv_response_time');
const errorRate = new Rate('cwv_errors');

export const options = {
  thresholds: {
    // Proxy for LCP / FID → 95% of requests < 500ms
    cwv_response_time: ['p(95)<500'],
    cwv_errors: ['rate<0.01'],
  },
};

export default function () {
  const res = http.get(`${__ENV.BASE_URL}/`);
  check(res, {
    'status 200': (r) => r.status === 200,
    'fast enough': (r) => r.timings.duration < 500,
  });
  responseTime.add(res.timings.duration);
  errorRate.add(res.status !== 200);
  sleep(1);
}

Running this script after every build ensures that FID-like latency stays within the CWV budget.

React Component Boilerplates

Frontend agents receive a React component template that already implements performance optimizations. The template in engineering-frontend-developer.md uses React.memo for render avoidance, useVirtualizer for efficient large lists (reducing layout shifts), and dynamic imports for lazy loading (improving LCP):

// src/components/DataTable.tsx
import React, { memo, useCallback } from 'react';
import { useVirtualizer } from '@tanstack/react-virtual';

interface DataTableProps {
  data: Array<Record<string, any>>;
  columns: Column[];
  onRowClick?: (row: any) => void;
}

// memo prevents unnecessary re-renders → better FID
export const DataTable = memo<DataTableProps>(({ data, columns, onRowClick }) => {
  const parentRef = React.useRef<HTMLDivElement>(null);

  // virtualizer limits DOM nodes → reduces CLS & improves LCP
  const rowVirtualizer = useVirtualizer({
    count: data.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    overscan: 5,
  });

  const handleRowClick = useCallback(
    (row: any) => onRowClick?.(row),
    [onRowClick],
  );

  return (
    <div
      ref={parentRef}
      className="h-96 overflow-auto"
      role="table"
      aria-label="Data table"
    >
      {rowVirtualizer.getVirtualItems().map((virtualItem) => {
        const row = data[virtualItem.index];
        return (
          <div
            key={virtualItem.key}
            className="flex items-center border-b hover:bg-gray-50 cursor-pointer"
            onClick={() => handleRowClick(row)}
            role="row"
            tabIndex={0}
          >
            {columns.map((column) => (
              <div key={column.key} className="px-4 py-2 flex-1" role="cell">
                {row[column.key]}
              </div>
            ))}
          </div>
        );
      })}
    </div>
  );
});

All performance-related comments in this template are derived from the Frontend Developer role description.

Activation Prompt Enforcement

When a new UI task is created, the activation prompt forces the developer to declare CWV targets (LCP < 2.5s, FID < 100ms, CLS < 0.1). The platform validates these numbers against the telemetry baseline before allowing the task to start:

### Frontend Developer Prompt (excerpt)

- Optimize for Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)
- Write component tests for all new components

Continuous Optimization Loop

The Autonomous Optimization Architect continuously shadows production traffic, running the same CWV measurements on experimental models. It updates routing weights only when the new model beats the baseline while staying under CWV thresholds. If any metric regresses, the router trips a circuit-breaker and rolls back automatically.

This process ensures that engineering agents do not merely optimize once but maintain Core Web Vitals compliance through continuous validation against real user data.

Governance and Reporting

After each sprint, agents generate a Markdown report summarizing CWV metrics (LCP, FID, CLS) and variance from the target. The report is stored under docs/performance/ and linked in the sprint review.

Real-time alerts are sent to the Evidence Collector and Infrastructure Maintainer agents when thresholds are violated, prompting immediate remediation before user experience degrades.

Summary

• Role-specific mandates in engineering-frontend-developer.md and related files hard-code CWV requirements into agent definitions.
• Critical Rules Engine automatically enforces performance standards through static analysis, build configuration, CI/CD guardrails, and runtime monitoring.
• Automated tooling includes k6 performance tests, React boilerplates with virtualization, and activation prompts that validate CWV targets before work begins.
• Continuous optimization via the Autonomous Optimization Architect ensures ongoing compliance through shadow testing and automatic rollback capabilities.
• Governance processes generate performance reports and trigger alerts when LCP, FID, or CLS thresholds are breached.

Frequently Asked Questions

What specific Core Web Vitals thresholds do the engineering agents enforce?

The engineering agents enforce the standard Google Core Web Vitals thresholds: Largest Contentful Paint (LCP) must be less than 2.5 seconds, First Input Delay (FID) must be less than 100 milliseconds, and Cumulative Layout Shift (CLS) must be less than 0.1. These values are hard-coded in the activation prompts and validated against real-user monitoring data before tasks can proceed.

How does the Autonomous Optimization Architect maintain CWV compliance?

The Autonomous Optimization Architect maintains compliance by continuously shadow-testing production traffic against experimental models. It measures CWV metrics on candidate changes and only promotes them to production if they beat the baseline while staying under the defined thresholds. If any metric regresses during this process, the architect triggers an automatic circuit-breaker that rolls back the change to prevent user experience degradation.

What happens if a pull request fails the Lighthouse CI check?

If a pull request fails the Lighthouse CI check, the merge is blocked until the performance issues are resolved. The CI pipeline, orchestrated through scripts/lint-agents.sh, runs Lighthouse after each pull request and validates the Performance category against the CWV thresholds. Agents receive real-time alerts through the Evidence Collector and Infrastructure Maintainer agents when checks fail, prompting immediate remediation.

Which files contain the CWV requirements for engineering agents?

The primary CWV requirements are located in four key files: engineering/engineering-frontend-developer.md defines the Frontend Developer agent's performance mandates and React boilerplates; testing/testing-performance-benchmarker.md provides the k6 testing scripts and CWV analysis checklists; strategy/coordination/agent-activation-prompts.md embeds the specific LCP, FID, and CLS thresholds into task activation; and engineering/engineering-autonomous-optimization-architect.md implements the continuous optimization and circuit-breaker logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}