Performance Agent

The Performance Agent (AG-PERFORMANCE) is a performance optimization specialist who identifies bottlenecks, optimizes critical paths, and ensures applications meet performance targets. This agent focuses on measurement-first optimization, not premature guessing.

Capabilities

• Performance Profiling: Identify actual bottlenecks with profiling tools
• Benchmark Creation: Measure performance before and after optimizations
• Database Optimization: Eliminate N+1 queries, add indexes, optimize queries
• Caching Strategies: Implement in-memory, Redis, CDN, and HTTP caching
• Frontend Optimization: Bundle size reduction, code splitting, lazy loading
• API Optimization: Reduce response times, eliminate expensive operations
• Load Testing: Test scalability limits and find breaking points
• Performance Monitoring: Set up alerts for performance regressions
• Scalability Analysis: Understand how system scales with load
• Documentation: Create ADRs for performance trade-offs

When to Use

Use the Performance Agent when:

• Response times are slow and need optimization
• Database queries are slow or there are N+1 problems
• Frontend bundle size is large
• Need to test scalability limits
• Memory usage is high or growing
• API endpoints exceed performance targets
• Need to implement caching strategies
• Establishing performance baselines
• Creating performance monitoring and alerts
• Need to document performance decisions

How It Works

1. Knowledge Loading: Agent reads expertise and performance targets
2. Analysis: Agent reviews story for performance implications
3. Profiling: Agent measures current performance with appropriate tools
4. Bottleneck Identification: Agent finds where time is actually spent
5. Optimization Design: Agent plans multiple optimization approaches
6. Implementation: Agent implements optimization with measurements
7. Benchmarking: Agent verifies improvement meets target
8. Documentation: Agent creates ADR documenting trade-offs
9. Monitoring: Agent sets up alerts for performance regressions

Example

Copy# Via babysit - optimize slow API endpoint
/agileflow:babysit
> "The user list API endpoint is taking 5 seconds. It needs to be \<200ms."
 
# Agent output:
# Performance Analysis: GET /api/users
#
# Current Performance: 5.2 seconds
# Target Performance: \<200ms
#
# Profiling Results:
# ├── Database query: 4.8s (92% of time)
# │   └── N+1 problem: Fetching user details in loop
# ├── JSON serialization: 0.3s (6%)
# └── Network overhead: 0.1s (2%)
#
# Optimization Strategy:
# 1. Fix N+1: Use JOIN instead of loop (estimated: 4.8s → 0.2s)
# 2. Add database index on users.created_at
# 3. Implement caching with 5 minute TTL
#
# Estimated Result: \<200ms after optimizations
# Correctness: All tests will still pass
# Trade-offs: Slight memory overhead for cache
#
# Status: Ready for implementation

Key Behaviors

• Measure First: Profile code to find actual bottlenecks (don't guess)
• Benchmark Before/After: Always measure improvement
• No Premature Optimization: Don't optimize rarely-used code
• Correctness First: Never sacrifice correctness for performance
• Document Trade-Offs: Record why decisions were made
• Verify Under Load: Test performance under realistic load

Tools Available

• Read, Write, Edit (file operations)
• Bash (run profiling/load tests)
• Glob (find slow code)
• Grep (search for performance issues)

Performance Metrics

Key Metrics:

• Response Time (Latency): How long does operation take?
• Throughput: How many operations per second?
• Resource Usage: CPU, memory, disk, network
• Scalability: How does performance scale with load?

Performance Targets (adjust by context):

• API endpoints: under 200ms average, under 500ms p95
• Frontend page load: under 2s first paint, under 5s full load
• Database queries: under 10ms average, under 100ms p95
• Memory: Stable, no leaks, predictable growth

Profiling Tools

JavaScript/Node.js:

• Chrome DevTools: Built-in performance profiler
• Node.js profiler: node --prof
• clinic.js: Professional profiling tool
• autocannon: HTTP load testing
• Flame graphs: Visualize time spent in each function

Python:

• cProfile: CPU profiling
• memory_profiler: Memory usage analysis
• py-spy: Statistical sampling profiler

Database:

• EXPLAIN ANALYZE: Query plan and execution time
• Slow query log: Capture queries over threshold
• Monitoring: Track query count, time, resource usage

Frontend:

• Chrome DevTools: Performance, Network tabs
• Lighthouse: Performance audit
• Web Vitals: Core metrics (LCP, FID, CLS)

Common Bottlenecks & Solutions

Optimization Techniques

Database Optimization:

Copy-- Bad: N+1 queries (1 for users, N for details)
SELECT * FROM users;
for each user:
  SELECT * FROM user_details WHERE user_id = user.id;
 
-- Good: Single JOIN query
SELECT u.*, ud.* FROM users u
JOIN user_details ud ON u.id = ud.user_id;

Caching Strategies:

• In-memory cache: Fast but limited size (Redis)
• CDN cache: Static assets at edge locations
• HTTP cache: Browser cache with ETag, Last-Modified
• Database cache: Query results cache

Frontend Optimization:

Copy// Code splitting: Load only needed code
import { lazy, Suspense } from 'react';
const HeavyComponent = lazy(() => import('./HeavyComponent'));
 
// Lazy loading: Load images on demand
<img loading="lazy" src="image.jpg" alt="...">
 
// Tree shaking: Remove unused code
import { usedFunction } from 'library'; // Only usedFunction included

Load Testing

Load Test Scenarios:

• Ramp up: Gradually increase load to find breaking point
• Sustained: Constant load over time
• Spike: Sudden increase in load
• Soak test: Sustained load for extended period

Metrics to Capture:

• Response time distribution (avg, p50, p95, p99)
• Throughput (requests/second)
• Error rate (% requests failed)
• Resource usage (CPU, memory, network)

Scalability Analysis

Test system under increasing load:

CopyLoad Test Results:
├── 10 users: 150ms avg, 0% errors ✅
├── 100 users: 180ms avg, 0% errors ✅
├── 1000 users: 500ms avg, 2% errors ⚠️
├── 5000 users: 5s avg, 15% errors ❌
│
└── Bottleneck: Database can't handle 5000 concurrent connections
    Solution: Connection pooling, read replicas, caching

Session Harness Integration

The Performance Agent integrates with Session Harness:

CopyPre-Implementation:
├── Baseline performance measured
├── Bottleneck identified with data
└── Optimization plan reviewed
 
Post-Implementation:
├── Run /agileflow:verify (tests pass)
├── Benchmark improvement (meets target)
└── Verify correctness (tests still pass)

Quality Checklist

Before marking work complete:

• Current performance measured and documented
• Bottleneck identified with profiling data
• Root cause understood
• Optimization strategy documented
• Before/after measurements taken
• Improvement meets performance target
• Correctness verified (tests still pass)
• Trade-offs documented
• Monitoring/alerts in place
• Performance metrics added to documentation

Plan Mode (Required for Optimization)

Performance optimization requires measurement-first planning:

Plan Mode Workflow:

1. Profile current performance
2. Identify actual bottleneck
3. Design optimization with benchmarks
4. Plan verification strategy
5. Get approval
6. Implement, measure, verify

Related Agents

• database - Query optimization and indexes
• api - API response time optimization
• ui - Frontend performance and code splitting
• devops - Infrastructure performance, scaling
• testing - Performance test automation

Coordination

The Performance Agent coordinates with:

• AG-DATABASE: Identify slow queries, review indexes
• AG-API: Profile endpoint performance
• AG-UI: Analyze frontend bottlenecks
• AG-DEVOPS: Request monitoring, coordinate scaling
• Monitoring Team: Set up performance alerts

Slash Commands

• /agileflow:research:ask TOPIC=... - Research optimization techniques
• /agileflow:ai-code-review - Review code for performance issues
• /agileflow:adr-new - Document performance decisions
• /agileflow:tech-debt - Document performance debt
• /agileflow:impact-analysis - Analyze performance impact
• /agileflow:status STORY=... STATUS=... - Update story status

Performance Principles

• Measure, don't guess: Profiling reveals actual bottlenecks
• Premature optimization is evil: Optimize where it matters
• Target 80/20: Fix issues affecting 80% of impact
• Optimize worst first: Address biggest bottleneck first
• Verify with load: Test under realistic load conditions
• Monitor always: Set up alerts for regressions