III. Focused Agents

Each agent does one thing well. Complex workflows compose specialized agents.

The Problem

The Solution

Unix Philosophy for AI

The Unix philosophy (1978) still applies:

Why It Works

::: info Single Responsibility Principle From software engineering (Robert C. Martin):

"An agent should have only one reason to execute"

Examples:

• validate-yaml: One responsibility (validation)
• do-everything-kubernetes: Multiple responsibilities :::

The Composition Model

::: code-group

research-best-practices:
  purpose: Gather information from docs
  single_responsibility: true

validate-yaml:
  purpose: Check YAML syntax and schema
  single_responsibility: true

generate-tests:
  purpose: Create test cases from specs
  single_responsibility: true

do-kubernetes-stuff:
  purpose: Everything Kubernetes
  single_responsibility: false  # Too vague

research-and-implement:
  purpose: Research then implement
  single_responsibility: false  # Two jobs

everything-for-statefulsets:
  purpose: All StatefulSet operations
  single_responsibility: false  # Not focused

:::

Real-World Evidence

Before: Monolithic Agent

After: Composed Agents

Improvement: 6x faster, 2.4x more reliable, infinitely more reusable

Agent Composition Pattern

::: code-group

workflow: create-kubernetes-application
  phases:
    - research:
        agent: research-k8s-patterns
        output: research-bundle.md

    - plan:
        agent: plan-statefulset
        inputs: [research-bundle.md]
        output: design-spec.md

    - implement:
        agents:
          - generate-manifest
          - create-tests
        inputs: [design-spec.md]
        outputs: [manifest.yaml, tests/]
        execution: parallel

    - validate:
        agents:
          - validate-yaml
          - run-tests
        inputs: [manifest.yaml, tests/]
        execution: sequential

# manifest-generator agent

## Responsibilities
Generate Kubernetes manifests

## Skills Used
- yaml-processing (structure output)
- file-operations (write manifests)
- git-operations (commit results)

## Does NOT Handle
- Research (use research-agent)
- Validation (use validate-agent)
- Deployment (use deploy-agent)

## Input Contract
required:
  - design-spec: markdown file
  - namespace: string

## Output Contract
- manifest.yaml: K8s manifest
- metadata.json: generation details

:::

The 52-Agent Validation

Top reused agents:

• validate-yaml: 47 workflows
• generate-tests: 23 workflows
• commit-with-context: 52 workflows (universal)

Implementation Checklist

• Define clear, single responsibility per agent
• Agents answer "What is the ONE thing this does?"
• Standard input/output contracts defined
• Agents compose into documented workflows
• Track reuse metrics (target 3+ workflows)

Anti-Patterns

The God Agent

Wrong: Single agent handles all tasks (12,000 tokens)

You are an expert in research, design, implementation,
testing, deployment, monitoring, documentation...

Right: Specialized agents for each responsibility

Overlapping Responsibilities

Wrong:

• research-and-plan (two jobs)
• implement-and-test (two jobs)

Right:

• research (one job)
• plan (one job)
• implement (one job)
• test (one job)

Hyper-Specialization

Wrong: Agent per line of code

- generate-yaml-line-1
- generate-yaml-line-2
- generate-yaml-line-3

Right: Agent per cohesive task

- generate-kubernetes-manifest

Related Factors