Skip to content

Agent Overview

Jump to bottom
Alessio Rocchi edited this page Jan 27, 2026 · 1 revision

Agent Overview

Comprehensive guide to all 11 aistack agent types with comparison and use cases.

Quick Reference

Agent Primary Role Key Capabilities Best For
Coder Write & modify code write-code, edit-code, refactor, debug Implementation tasks
Researcher Gather information search-code, analyze-patterns, explore-codebase Code exploration
Tester Write & run tests write-tests, run-tests, identify-edge-cases Quality assurance
Reviewer Code review code-review, security-review, best-practices Quality checks
Adversarial Break code adversarial-review, edge-case-analysis Security testing
Architect System design system-design, technical-decisions Architecture
Coordinator Orchestrate agents task-decomposition, workflow-management Multi-agent flows
Analyst Analyze data data-analysis, performance-profiling Metrics & insights
DevOps Infrastructure ci-cd-setup, containerization, deployment Operations
Documentation Write docs api-documentation, tutorials, runbooks Documentation
Security Auditor Security audit vulnerability-scanning, compliance-checking Security

Agent Comparison

By Complexity

Simple (Single Focus):

  • Coder - Write code
  • Tester - Write tests
  • Researcher - Find information

Moderate (Multiple Skills):

  • Reviewer - Multiple review types
  • Documentation - Various doc types
  • Analyst - Different analysis methods

Complex (Orchestration):

  • Architect - System-wide decisions
  • Coordinator - Multi-agent coordination
  • DevOps - Full infrastructure stack
  • Security Auditor - Comprehensive audits
  • Adversarial - Attack modeling

By Use Frequency

High Frequency:

  • Coder (implementation)
  • Tester (quality assurance)
  • Reviewer (code review)

Medium Frequency:

  • Researcher (exploration)
  • Documentation (docs)
  • Architect (design)

Specialized:

  • Adversarial (security-critical code)
  • Security Auditor (compliance)
  • DevOps (infrastructure)
  • Coordinator (complex workflows)
  • Analyst (performance issues)

Coder Agent

Purpose: Expert software engineer for writing clean, maintainable code

System Prompt Highlights:

  • Write simple, readable code
  • Follow established patterns
  • Avoid over-engineering
  • Include essential error handling

Capabilities:

  • write-code - Create new code
  • edit-code - Modify existing code
  • refactor - Improve code quality
  • debug - Fix issues
  • implement-features - Build features

When to Use:

  • Implementing new features
  • Fixing bugs
  • Refactoring code
  • Adding functionality
  • Code generation

Example:

Spawn a coder agent to implement JWT token validation with TypeScript

Full Guide →

Researcher Agent

Purpose: Gather accurate information from codebases and documentation

System Prompt Highlights:

  • Prioritize accuracy over speed
  • Cite sources and locations
  • Distinguish facts from assumptions
  • Explore thoroughly

Capabilities:

  • search-code - Find code patterns
  • read-documentation - Analyze docs
  • analyze-patterns - Identify patterns
  • gather-requirements - Extract requirements
  • explore-codebase - Map architecture

When to Use:

  • Understanding existing code
  • Finding usage patterns
  • Gathering requirements
  • Exploring architecture
  • Code discovery

Example:

Spawn a researcher agent to find all authentication-related functions in the codebase

Full Guide →

Tester Agent

Purpose: Write and run tests to ensure code quality

System Prompt Highlights:

  • Test behavior, not implementation
  • Write maintainable tests
  • Focus on edge cases
  • Tests should be fast and reliable

Capabilities:

  • write-tests - Create test suites
  • run-tests - Execute tests
  • identify-edge-cases - Find edge cases
  • coverage-analysis - Analyze coverage
  • test-debugging - Debug failing tests

When to Use:

  • Creating test suites
  • Improving coverage
  • Testing edge cases
  • Debugging tests
  • Integration testing

Example:

Spawn a tester agent to create comprehensive tests for the user authentication module

Full Guide →

Reviewer Agent

Purpose: Review code for quality, security, and best practices

System Prompt Highlights:

  • Be constructive and specific
  • Focus on significant issues
  • Consider maintainability
  • Check security and performance

Capabilities:

  • code-review - General code review
  • security-review - Security checks
  • performance-review - Performance analysis
  • best-practices - Pattern validation
  • feedback - Constructive feedback

When to Use:

  • Pre-commit reviews
  • Pull request reviews
  • Code quality audits
  • Best practices validation
  • General code review

Example:

Spawn a reviewer agent to review the payment processing module for security and best practices

Full Guide →

Adversarial Agent

Purpose: Aggressively try to break code with attack scenarios

System Prompt Highlights:

  • Assume code has bugs
  • Actively try to break code
  • Be skeptical of all claims
  • Never accept "it probably works"

Capabilities:

  • adversarial-review - Attack-focused review
  • security-audit - Security testing
  • edge-case-analysis - Extreme edge cases
  • break-code - Break attempts

Attack Vectors:

  • Input validation
  • State & race conditions
  • Error handling
  • Security (auth, IDOR, secrets)
  • Logic errors
  • Performance issues

When to Use:

  • Security-critical code
  • Authentication systems
  • Payment processing
  • Data validation
  • API endpoints

Example:

Start an adversarial review loop for the user authentication function

Full Guide →

Architect Agent

Purpose: Design system architecture and make technical decisions

System Prompt Highlights:

  • Design for simplicity first
  • Consider trade-offs explicitly
  • Think about maintainability
  • Document decisions

Capabilities:

  • system-design - Architecture design
  • technical-decisions - Tech choices
  • architecture-review - Design review
  • documentation - Design docs
  • trade-off-analysis - Evaluate options

When to Use:

  • New feature architecture
  • System design
  • Technology selection
  • Scalability planning
  • Migration strategies

Example:

Spawn an architect agent to design a scalable notification system supporting email, SMS, and push

Full Guide →

Coordinator Agent

Purpose: Orchestrate multi-agent tasks and manage workflows

System Prompt Highlights:

  • Break complex tasks into clear steps
  • Assign work to specialists
  • Track progress and handle blockers
  • Synthesize results

Capabilities:

  • task-decomposition - Break down tasks
  • agent-coordination - Manage agents
  • progress-tracking - Monitor progress
  • result-synthesis - Combine results
  • workflow-management - Manage workflows

When to Use:

  • Complex features
  • End-to-end workflows
  • Multi-component systems
  • Large refactorings
  • System migrations

Example:

Spawn a coordinator agent to build a complete user registration system with tests and docs

Full Guide →

Analyst Agent

Purpose: Analyze data, performance, and metrics

System Prompt Highlights:

  • Base conclusions on evidence
  • Quantify findings with metrics
  • Present data clearly
  • Identify actionable insights

Capabilities:

  • data-analysis - Analyze datasets
  • performance-profiling - Profile performance
  • metrics-collection - Collect metrics
  • trend-analysis - Identify trends
  • reporting - Create reports

When to Use:

  • Performance profiling
  • Code complexity analysis
  • Usage pattern analysis
  • Benchmark comparison
  • Trend identification

Example:

Spawn an analyst agent to analyze API response times and identify bottlenecks

Full Guide →

DevOps Agent

Purpose: Manage deployment, CI/CD, containers, and infrastructure

System Prompt Highlights:

  • Implement automation
  • Prioritize security
  • Design for scalability
  • Follow best practices

Capabilities:

  • ci-cd-setup - Build pipelines
  • containerization - Docker/containers
  • kubernetes-deployment - K8s manifests
  • infrastructure-automation - IaC
  • monitoring-setup - Observability
  • security-hardening - Security
  • cloud-deployment - Cloud platforms
  • performance-optimization - Optimize

When to Use:

  • Docker containerization
  • Kubernetes deployment
  • CI/CD pipeline setup
  • Infrastructure as code
  • Cloud deployment
  • Monitoring setup

Example:

Spawn a DevOps agent to create a GitHub Actions CI/CD pipeline with testing and deployment

Full Guide →

Documentation Agent

Purpose: Create comprehensive documentation

System Prompt Highlights:

  • Use clear, simple language
  • Provide complete information
  • Use consistent terminology
  • Include working examples

Capabilities:

  • api-documentation - API docs
  • user-guides - User documentation
  • tutorials - Step-by-step guides
  • code-documentation - Inline docs
  • architecture-docs - System docs
  • runbooks - Operational guides
  • readme-creation - README files
  • documentation-review - Doc review

When to Use:

  • API documentation
  • User guides
  • Tutorial creation
  • Code comments
  • README files
  • Architecture docs

Example:

Spawn a documentation agent to create API documentation for the user endpoints with examples

Full Guide →

Security Auditor Agent

Purpose: Comprehensive security analysis and compliance

System Prompt Highlights:

  • Perform thorough audits
  • Identify all vulnerabilities
  • Check OWASP Top 10
  • Provide remediation guidance

Capabilities:

  • vulnerability-scanning - Find vulnerabilities
  • code-security-review - Security code review
  • penetration-testing - Pen testing
  • compliance-checking - Compliance audit
  • dependency-audit - Dependency scan
  • threat-modeling - Threat analysis
  • security-documentation - Security docs
  • remediation-planning - Fix planning

When to Use:

  • OWASP compliance
  • Security audits
  • Vulnerability scanning
  • Threat modeling
  • PCI DSS compliance
  • HIPAA compliance

Example:

Spawn a security auditor agent to audit the authentication system for OWASP Top 10 vulnerabilities

Full Guide →

Agent Combination Patterns

Pattern 1: Feature Development

Architect → Coder → Tester → Reviewer
  1. Architect designs the solution
  2. Coder implements the design
  3. Tester creates tests
  4. Reviewer validates quality

Pattern 2: Security-Critical Feature

Architect → Coder → Adversarial ↔ Coder → Security Auditor
  1. Architect designs secure architecture
  2. Coder implements
  3. Adversarial finds issues, Coder fixes (loop)
  4. Security Auditor performs final audit

Pattern 3: Full Stack Feature

Coordinator
    ├─ Architect (Design)
    ├─ Coder (Frontend)
    ├─ Coder (Backend)
    ├─ Tester (Tests)
    └─ Documentation (Docs)

Coordinator manages parallel work streams

Pattern 4: Code Refactoring

Researcher → Analyst → Architect → Coder → Tester
  1. Researcher analyzes existing code
  2. Analyst identifies issues
  3. Architect designs refactoring
  4. Coder implements changes
  5. Tester validates behavior preserved

Pattern 5: DevOps Pipeline

DevOps → Security Auditor → DevOps → Documentation
  1. DevOps creates CI/CD pipeline
  2. Security Auditor reviews security
  3. DevOps hardens configuration
  4. Documentation creates runbook

Selection Guide

Choose Coder When:

  • You need code written
  • You have clear requirements
  • You need bug fixes
  • You need refactoring

Choose Researcher When:

  • You need to understand existing code
  • You're exploring a new codebase
  • You need to find patterns
  • You're gathering requirements

Choose Tester When:

  • You need tests written
  • You need coverage improved
  • You need edge cases tested
  • You need test debugging

Choose Reviewer When:

  • You need code reviewed
  • You need quality feedback
  • You need best practices validation
  • You need general review

Choose Adversarial When:

  • Code is security-critical
  • You need aggressive testing
  • You need attack surface analysis
  • You need edge case discovery

Choose Architect When:

  • You need system design
  • You need technical decisions
  • You need architecture review
  • You need technology selection

Choose Coordinator When:

  • Task is complex with multiple steps
  • You need multiple agents
  • You need workflow management
  • You need progress tracking

Choose Analyst When:

  • You need performance analysis
  • You need metrics collection
  • You need trend analysis
  • You need data insights

Choose DevOps When:

  • You need CI/CD setup
  • You need containerization
  • You need infrastructure automation
  • You need deployment

Choose Documentation When:

  • You need API docs
  • You need user guides
  • You need tutorials
  • You need code comments

Choose Security Auditor When:

  • You need comprehensive security audit
  • You need compliance checking
  • You need vulnerability scanning
  • You need threat modeling

Next Steps

Individual Agent Guides

Core Concepts

Recipes

Related:

Home

Getting Started

Core Concepts

Agent Guides

MCP Tools

Recipes

Advanced

Reference

Clone this wiki locally