Skip to main content
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:
ScenarioAgent to Use
User requests complex featureplanner
Code just written/modifiedcode-reviewer
Implementing new feature or bug fixtdd-guide
Making architectural decisionarchitect
Writing security-sensitive codesecurity-reviewer
Build failsbuild-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

Only grant tools the agent actually needs. Read-only agents should only have Read, Grep, Glob.
  • Opus: Deep reasoning (planning, architecture, security)
  • Sonnet: Structured workflows (TDD, build fixes, docs)
  • Haiku: Simple, repetitive tasks (formatting, linting)
Agent instructions should be concrete and actionable. Avoid vague guidelines.
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 WhenUse Main Conversation When
Task has clear scope and methodologyExploratory or unclear requirements
Specialized expertise neededGeneral coding tasks
You want to limit tools/contextFull context needed
Task is repeatable across projectsOne-off, project-specific task
You want parallel executionSequential 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