Understanding Agents

Agents are AI-powered specialists that perform development tasks autonomously. They read code, make changes, run commands, and iterate until the job is done.

Primary Agents vs Sub-Agents

Primary Agents (4)

These are the entry points to the system. You start conversations with primary agents, and they orchestrate the work.

  • @builderBuilds features from PRDs or ad-hoc requests by orchestrating implementation agents
  • @plannerRefine draft PRDs and prepare them for implementation
  • @toolkitMaintains the AI toolkit - agents, skills, templates, and scaffolds
  • @ui-test-full-app-auditorAutonomous E2E test auditor that analyzes apps and generates comprehensive test coverage

Sub-Agents (61)

Specialists that are delegated to by primary agents. You don't usually invoke them directly—they're called when needed.

aesthetic-criticansible-criticapi-criticaws-devbuilderdeveloper+55 more

How Agents Are Invoked

1

Direct Invocation

Start a conversation with a primary agent using the @ prefix:

@builder Add a dark mode toggle to the settings page
2

Automatic Delegation

Primary agents automatically delegate to specialists using the Task tool. When @builder needs React work done, it invokes react-dev. When code review is needed, it calls critic.

3

Proactive Triggers

Some agents are triggered automatically based on context. For example, the critic agent runs after significant code changes to catch issues early.

The Delegation Pattern

Here's how a typical task flows through the agent system:

1

You ask @builder to implement a feature

“Add user profile editing to the settings page”

2

@builder delegates to react-dev

The specialist implements the React components

3

@builder delegates to critic

Code is reviewed for quality, security, and best practices

4

@builder delegates to tester

Tests are written and run to verify the implementation

Work complete—ready for your review

@builder reports back with a summary of what was done

Canonical Source Fidelity

When tasks reference specific source files — config schemas, multi-step flows, field names — implementation agents must read and reproduce the source faithfully rather than generating content from conceptual understanding. LLMs produce plausible-but-wrong field names that pass automated checks but are semantically incorrect.

⚠️

The “Plausible Fabrication” Anti-Pattern

When told “document the CLI auth fields from auth-headless”, an agent may write strategy, tokenOutput, sessionCookie instead of the actual fields command, responseFormat, tokenPath. The fabricated content is structurally valid — it passes typecheck and lint — but the field names are wrong.

Required Steps for @developer

When a task references specific files, line ranges, schemas, or says “match X” / “reproduce Y”:

1READ

Read every referenced source file before writing anything

2EXTRACT

Extract exact field names, column headers, and structure from the source

3REPRODUCE

Reproduce faithfully — do not rename fields, reorder columns, or “improve” the structure

4VERIFY

Re-read the source after writing and diff against your output for mismatches

Inline Canonical Source in Delegation

For documentation tasks, @builder embeds the canonical content directly in the delegation context block using a canonicalSource field. This ensures the agent has the exact text in its context window and doesn't need to read external files:

<context>
version: 1
project:
  path: /Users/dev/code/website
canonicalSource:
  description: "Exact content to reproduce"
  sources:
    - file: skills/auth-headless/SKILL.md
      lines: "331-359"
      content: |
        headless:
          method: cli
          command: "pnpm cli auth:test-token"
          responseFormat: json
          tokenPath: accessToken
          sessionStorage: localStorage
</context>

Field names and structure MUST match
canonicalSource exactly.

This belt-and-suspenders approach combines the developer's READ-EXTRACT-REPRODUCE-VERIFY rule with Builder embedding the source content inline, ensuring faithful reproduction even when the agent skips reading referenced files.

How Agents Communicate

Agents communicate through files and conventions, not direct API calls. This makes the system transparent and debuggable.

Task Tool

Primary agents use the Task tool to spawn sub-agent sessions with specific prompts. The sub-agent works autonomously and returns results.

File Artifacts

Agents communicate context through files: PRDs define requirements, session locks prevent conflicts, and code changes are visible in git.

Project Context

All agents read project.json and CONVENTIONS.md to understand your codebase.

Tool Results

Each tool call returns results that agents use to decide next steps. Read, Write, Edit, Bash, and more—all produce visible outputs.

Test Documentation Sync

Both @builder and @developer enforce test documentation sync before every commit. This prevents stale test references from being committed.

Pre-Commit Detection

Before staging files for commit, agents scan for stale test references—deleted test files that are still referenced in configuration, old function names that have been renamed, or missing test utilities.

What Gets Checked

  • Test file imports match existing source files
  • Jest/Vitest config references valid test patterns
  • Playwright config test directories exist
  • Mock/fixture references point to valid files

When Issues Are Found

If stale references are detected, the agent automatically fixes them before proceeding with the commit. This typically involves updating import paths, removing references to deleted files, or renaming function calls to match current implementations.

Temporary Files Policy

All implementation agents enforce a strict rule: never write temporary files to system paths like /tmp/. Instead, agents use the project-local .tmp/ directory. This is enforced in AGENTS.md and in each agent's individual instructions.

⚠️Why not /tmp/?

  • Module resolution failures—Scripts in /tmp/ can't resolve project dependencies. require('../../src/utils') breaks when the script runs from a different filesystem root.
  • macOS /private/tmp/ mapping—macOS maps /tmp/ to /private/tmp/, causing path comparison mismatches and confusing debug output.
  • Permission prompts—Some environments restrict /tmp/ access, causing unexpected permission dialogs mid-automation.

Affected Agents

This policy is enforced across all 8 implementation sub-agents:

developer

Added Temporary Files section with AGENTS.md anchor and developer-specific rules

hammer

Added Temporary Files section with AGENTS.md anchor

overlord

Added Temporary Files section with AGENTS.md anchor

go-dev

Added /tmp/ restriction to Scope Restrictions

react-dev

Added /tmp/ restriction to Scope Restrictions

java-dev

Added /tmp/ restriction to Scope Restrictions

python-dev

Added /tmp/ restriction to Scope Restrictions

ui-tester-playwright

Added /tmp/ restriction to Important Notes

Correct Pattern

# ❌ Don't do this
/tmp/debug-output.log
/tmp/test-script.sh

# ✅ Do this instead
<project>/.tmp/debug-output.log
<project>/.tmp/test-script.sh

Agent Categories

Sub-agents are organized by their specialty:

29

Critics

Review code quality, security, accessibility, and best practices.

16

Developers

Implement features in React, Go, Python, Java, and more.

9

Testers

Write unit tests, integration tests, and E2E tests.

3

Orchestrators

Coordinate other agents and manage workflows.

8

Utilities

Debugging, docs, cleanup, and specialized tools.

Browse All 65 Agents