Agents
Specialized AI subagents with focused roles and defined tool access, enabling parallel execution of complex development tasks.
Definition
Agents are specialized AI subagents that live in .claude/agents/. Each Agent has a focused role, a defined set of tools it can access, and specific instructions for its domain of expertise.
Where a command is a workflow, an agent is a worker. They're spawned by Claude to handle specific tasks in parallel, returning their results to the parent conversation. Think of them as specialized farmhands, each expert in their particular area.
Philosophy
Core Principle
Agents embody the principle of separation of concerns. By giving each Agent a focused role with limited tools, you get better results than asking a single context to juggle multiple complex tasks.
The agricultural metaphor continues: a farm operates efficiently not because one person does everything, but because different workers specialize. The shepherd tends sheep while the farmer works the fields. Agents work the same way.
Why Specialized Agents
- Focused context produces higher quality analysis
- Parallel execution dramatically speeds up multi-faceted tasks
- Tool restrictions prevent accidental side effects
- Each agent can be tuned for its specific domain
- Results are composable and can be reviewed independently
Structure
Each Agent is defined in a single markdown file with YAML frontmatter:
---
name: code-reviewer
description: Review code for quality, security, performance,
code smells, and basic accessibility. Updates FARMHOUSE.md.
tools: Read, Grep, Glob, Edit
model: opus
---
# Code Reviewer Agent
## Purpose
Single pass over changed code covering quality, OWASP-style
security issues, performance anti-patterns, code smells, and
basic accessibility - one merged review instead of five.
## Workflow
1. Scan for quality issues, DRY violations, complexity
2. Check for security and input-validation problems
3. Flag performance anti-patterns
4. Note basic accessibility issues (alt text, contrast, labels)
5. Report findings back to the parent conversation
...Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name |
Yes | Unique identifier for the agent |
description |
Yes | What the agent does and when to use it |
tools |
Yes | Comma-separated list of allowed tools |
model |
No | Model to use (opus, sonnet, haiku) |
Orchestration
Agents are invoked by commands. /inspect, for example, spawns the code-reviewer agent to run its checks:
Parallel Execution
When multiple agents have no dependencies between them, they execute in parallel. This speeds up comprehensive audits where code review and cleanup can run simultaneously.
Built-in Agents
Farmwork installs 4 specialized agents during initialization. Earlier versions shipped 13-15 narrow agents; v2.0.0 merges quality, security, performance, code-smell, and accessibility review into a single code-reviewer and cuts the rest that weren't pulling their weight:
- the-farmer — Audits and updates FARMHOUSE.md metrics
- code-reviewer — Quality, security, performance, code smells, and basic accessibility in one pass
- code-cleaner — Removes comments and console.logs
- idea-gardener — Manages the Idea Garden and Compost
Creating Custom Agents
You can create project-specific agents. A well-designed agent should:
- Have a single, clearly defined responsibility
- Request only the tools it actually needs
- Specify its output format clearly
- Update relevant audit documents with findings
- Return structured results the parent can use
Tool Restrictions
Be conservative with tool access. An agent that only needs to read code shouldn't have Write or Bash access. Minimal permissions reduce risk and focus the agent on its core task.