Agents

Agents are specialized subagents that handle delegated tasks with a limited scope. Each agent is optimized for specific domain tasks, using only the tools it needs and operating with focused instructions.

What Are Agents?

Agents are markdown files with YAML frontmatter that define:

Name - Unique identifier for the agent
Description - When and why to use this agent
Tools - Limited set of tools the agent can use
Model - Which AI model to use (opus, sonnet, haiku)
Instructions - Detailed behavior and methodology

Agent Structure

Here’s an example from the planner agent:

~/workspace/source/agents/planner.md

---
name: planner
description: Expert planning specialist for complex features and refactoring. Use PROACTIVELY when users request feature implementation, architectural changes, or complex refactoring.
tools: ["Read", "Grep", "Glob"]
model: opus
---

You are an expert planning specialist focused on creating comprehensive, actionable implementation plans.

## Your Role

- Analyze requirements and create detailed implementation plans
- Break down complex features into manageable steps
- Identify dependencies and potential risks
- Suggest optimal implementation order

Agents use limited tool sets to maintain focus. The planner only has read-only tools (Read, Grep, Glob) because planning shouldn’t modify code.

Available Agents

ECC provides 13 specialized agents across four categories:

Development Agents

planner

Purpose: Implementation planningWhen to use: Complex features, refactoring, architectural changesModel: Opus (deep reasoning required)Tools: Read, Grep, Glob (read-only)

architect

Purpose: System design and scalability decisionsWhen to use: Architectural decisions, scaling strategiesModel: OpusTools: Read, Grep, Glob

tdd-guide

Purpose: Test-driven development enforcementWhen to use: New features, bug fixes, refactoringModel: Sonnet (cost-effective for structured workflows)Tools: Read, Write, Edit, Bash, Grep

code-reviewer

Purpose: Code quality and maintainability reviewWhen to use: After writing/modifying codeModel: OpusTools: Read, Grep, Glob

build-error-resolver

Purpose: Fix build and type errorsWhen to use: Build failures, type errorsModel: SonnetTools: Read, Edit, Bash

Specialized Agents

security-reviewer

Purpose: Vulnerability detection and security analysisWhen to use: Before commits, security-sensitive codeModel: Opus

e2e-runner

Purpose: End-to-end Playwright testingWhen to use: Critical user flowsModel: Sonnet

refactor-cleaner

Purpose: Dead code cleanup and refactoringWhen to use: Code maintenance, technical debt reductionModel: Sonnet

doc-updater

Purpose: Documentation and codemap updatesWhen to use: Updating docs after code changesModel: Sonnet

database-reviewer

Purpose: PostgreSQL/Supabase specialistWhen to use: Schema design, query optimizationModel: Opus

Language-Specific Agents

go-reviewer

Purpose: Go code review and best practicesWhen to use: Go projects

go-build-resolver

Purpose: Fix Go build errorsWhen to use: Go build failures

python-reviewer

Purpose: Python code review (PEP 8, type hints)When to use: Python projects

When to Use Agents

Proactive Agent Use

Use agents proactively without waiting for user prompts:

Scenario	Agent to Use
User requests complex feature	planner
Code just written/modified	code-reviewer
Implementing new feature or bug fix	tdd-guide
Making architectural decision	architect
Writing security-sensitive code	security-reviewer
Build fails	build-error-resolver

Example Workflow

User: "Add Stripe subscription billing"

1. AUTO-INVOKE planner agent
   → Creates implementation plan
   → Identifies 5 phases, 12 files to change
   → Lists risks and mitigations

2. User confirms plan

3. AUTO-INVOKE tdd-guide agent
   → Enforces write-tests-first
   → Implements each phase with TDD

4. After each file edit:
   → AUTO-INVOKE code-reviewer agent
   → Checks for quality issues
   → Flags CRITICAL/HIGH concerns

5. Before commit:
   → AUTO-INVOKE security-reviewer agent
   → Scans for secrets, SQL injection, XSS

Agent Orchestration

Sequential Execution

Use when agents depend on each other’s output:

planner → tdd-guide → code-reviewer → security-reviewer

Parallel Execution

Use when operations are independent:

// Launch multiple agents simultaneously
const results = await Promise.all([
  invokeAgent('go-reviewer', goFiles),
  invokeAgent('python-reviewer', pythonFiles),
  invokeAgent('security-reviewer', allFiles)
])

Agent Teams spawn multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews).

Creating Custom Agents

You can create your own agents for project-specific needs:

~/.claude/agents/my-agent.md

---
name: my-agent
description: Custom agent for specific domain tasks
tools: ["Read", "Grep"]
model: sonnet
---

# Agent Instructions

You are a specialist in...

## Your Role

- Specific task 1
- Specific task 2

## Methodology

1. Step 1
2. Step 2

Agent Best Practices

Limit Tools

Only grant tools the agent actually needs. Read-only agents should only have Read, Grep, Glob.

Choose Right Model

Opus: Deep reasoning (planning, architecture, security)
Sonnet: Structured workflows (TDD, build fixes, docs)
Haiku: Simple, repetitive tasks (formatting, linting)

Be Specific

Agent instructions should be concrete and actionable. Avoid vague guidelines.

Test Isolation

Ensure agents work correctly with limited tool sets. Don’t assume access to tools they don’t have.

Agent vs. Main Conversation

When should you delegate to an agent vs. handle in the main conversation?

Use Agent When	Use Main Conversation When
Task has clear scope and methodology	Exploratory or unclear requirements
Specialized expertise needed	General coding tasks
You want to limit tools/context	Full context needed
Task is repeatable across projects	One-off, project-specific task
You want parallel execution	Sequential dependencies

Next Steps

Explore Skills

Learn how agents reference skills for domain knowledge

Use Commands

Discover slash commands that invoke agents

Agent Reference

Full reference for all 13 agents

Get Started

Core Concepts

Platform Support

Guides

What Are Agents?

Agent Structure

Available Agents

Development Agents

planner

architect

tdd-guide

code-reviewer

build-error-resolver

Specialized Agents

security-reviewer

e2e-runner

refactor-cleaner

doc-updater

database-reviewer

Language-Specific Agents

go-reviewer

go-build-resolver

python-reviewer

When to Use Agents

Proactive Agent Use

Example Workflow

Agent Orchestration

Sequential Execution

Parallel Execution

Creating Custom Agents

Agent Best Practices

Agent vs. Main Conversation

Next Steps

Explore Skills

Use Commands

Agent Reference

​What Are Agents?

​Agent Structure

​Available Agents

​Development Agents

planner

architect

tdd-guide

code-reviewer

build-error-resolver

​Specialized Agents

security-reviewer

e2e-runner

refactor-cleaner

doc-updater

database-reviewer

​Language-Specific Agents

go-reviewer

go-build-resolver

python-reviewer

​When to Use Agents

​Proactive Agent Use

​Example Workflow

​Agent Orchestration

​Sequential Execution

​Parallel Execution

​Creating Custom Agents

​Agent Best Practices

​Agent vs. Main Conversation

​Next Steps

Explore Skills

Use Commands

Agent Reference

What Are Agents?

Agent Structure

Available Agents

Development Agents

Specialized Agents

Language-Specific Agents

When to Use Agents

Proactive Agent Use

Example Workflow

Agent Orchestration

Sequential Execution

Parallel Execution

Creating Custom Agents

Agent Best Practices

Agent vs. Main Conversation

Next Steps