Optimal 5-Agent Setup for TypeScript/Next.js/LLM Applications

This directory contains the battle-tested, production-ready agents optimized for full-stack TypeScript applications with Next.js and LLM integrations.

The 5 Essential Agents

1. spec-analyst (Requirements & Product Ownership)

• Source: zhsama/claude-sub-agent
• Purpose: Transforms ideas into comprehensive requirements
• Key Features:
  • User story creation with acceptance criteria
  • Stakeholder analysis and persona development
  • SMART criteria and EARS format
  • Functional and non-functional requirements
• Use: ALWAYS use FIRST for any new feature

2. senior-frontend-architect (Complete Frontend Solution)

• Source: zhsama/claude-sub-agent
• Purpose: All-in-one TypeScript/React/Next.js expert
• Key Features:
  • 10+ years Meta experience
  • Next.js 15 App Router & Server Components
  • Performance optimization built-in
  • Replaces both typescript-pro AND frontend-developer
• Use: For all UI/frontend implementation

3. backend-architect (API & System Design)

• Source: wshobson/agents
• Purpose: RESTful APIs and serverless architecture
• Key Features:
  • Microservice boundaries
  • Database schema design
  • Express/Fastify expertise
  • Serverless functions (Vercel/AWS Lambda)
• Use: For backend services and API design

4. ai-engineer (LLM Integration Specialist)

• Source: wshobson/agents
• Purpose: OpenAI/Anthropic integration expert
• Key Features:
  • RAG systems and vector databases
  • Prompt optimization
  • Token management
  • Streaming responses
• Model: Uses Opus for complex AI tasks
• Use: For any LLM/AI features

5. test-automator (Comprehensive Testing)

• Source: wshobson/agents
• Purpose: All testing needs
• Key Features:
  • Vitest/Jest unit tests
  • Playwright E2E tests
  • CI/CD pipeline setup
  • Test data management
• Use: ALWAYS before marking features complete

Why This Setup Is Optimal

1. No Overlap: Each agent has completely distinct responsibilities
2. Complete Coverage: Product → Frontend → Backend → AI → Testing
3. Battle-Tested: From proven repositories with thousands of users
4. Right-Sized: 5 agents is within the optimal 5-8 range (research shows 100+ agents degrades performance)
5. Performance Built-In: No need for separate performance-engineer

Installation

# Copy all 5 agents to your Claude agents directory
cp /Users/James/Dev/claude-project-manager/recommended-agents/*.md ~/.claude/agents/

# Verify installation
ls ~/.claude/agents/

Required CLAUDE.md Configuration

Add this to your project's CLAUDE.md:

## The 5 Essential Agents (USE PROACTIVELY!)
1. **spec-analyst** - ALWAYS use FIRST for requirements & user stories
2. **senior-frontend-architect** - All frontend (TypeScript/React/Next.js)
3. **backend-architect** - API design & serverless 
4. **ai-engineer** - LLM integration & RAG
5. **test-automator** - ALWAYS write tests BEFORE marking complete

## Mandatory Workflow
1. NO CODE until spec-analyst completes requirements
2. ALWAYS write tests with test-automator
3. Use agents PROACTIVELY without being asked
4. Add "ultrathink" for complex problems

Workflow Order

spec-analyst
    ↓
backend-architect (if backend needed)
    ↓
senior-frontend-architect
    ↓
ai-engineer (if LLM features needed)
    ↓
test-automator (MANDATORY)

What We Removed and Why

• docs-architect: Was for documenting existing code, not gathering requirements
• typescript-pro: Redundant with senior-frontend-architect
• frontend-developer: Redundant with senior-frontend-architect
• performance-engineer: Built into senior-frontend-architect

Notes

• These agents use different models based on complexity (Opus for complex, Sonnet for standard)
• Each agent will be invoked automatically based on context
• The senior-frontend-architect is a single agent that replaces multiple specialists
• Research shows 5-8 agents is optimal; more causes performance issues