Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Agents

Agents are autonomous workers that execute specific tasks in agentful. Each agent has a specialized role, tools, and knowledge base.

Core Concept

Three-Tier Architecture

agentful organizes agents into three categories based on lifecycle and purpose:

  1. Core Agents - Universal specialists (orchestrator, reviewer, fixer, etc.) included in every installation. Same for all projects.
  2. Domain Agents - Generated by Architect based on your product's business logic (payment-processor, order-fulfillment, etc.). Project-specific.
  3. Ephemeral Agents - Temporary agents for one-off tasks (2-hour DB migration) or longer-term work (multi-week refactor). Deleted when done.

This pattern applies to skills too - see our philosophy for details.

Agent Types

1. Core Agents

Built-in agents that ship with agentful.

AgentPurposeToolsModel
OrchestratorCoordinates work, delegates to specialistsRead, Write, Edit, Glob, Grep, TaskOpus
ArchitectAnalyzes tech stack, generates domain agents and skillsRead, Write, Edit, Glob, Grep, TaskOpus
BackendImplements server-side codeRead, Write, Edit, Glob, Grep, BashSonnet
FrontendImplements client-side codeRead, Write, Edit, Glob, Grep, BashSonnet
TesterWrites tests, ensures 80% coverageRead, Write, Edit, Glob, Grep, BashSonnet
ReviewerValidates code quality (6 core gates)Read, Glob, Grep, Bash, Write, EditSonnet
FixerFixes issues found by ReviewerRead, Write, Edit, Glob, Grep, BashSonnet
Product AnalyzerAnalyzes product specs, identifies gapsRead, Write, Edit, Glob, GrepOpus

Location: .claude/agents/*.md

2. Domain Agents

Business-specific agents for your product's domain needs, generated by Architect.

E-commerce example:
  • payment-processor.md - Handles payments, refunds, billing (uses stripe-integration, payment-webhooks skills)
  • order-fulfillment.md - Order processing, shipping, tracking (uses shipping-api, order-state-machine skills)
  • inventory-manager.md - Stock tracking, restocking alerts (uses inventory-sync, stock-alerts skills)
SaaS platform example:
  • subscription-manager.md - Plans, upgrades, billing cycles (uses subscription-billing, plan-migration skills)
  • workspace-coordinator.md - Team creation, permissions, sharing (uses rbac-patterns, team-provisioning skills)
  • analytics-collector.md - Event tracking, metrics, reports (uses event-schema, metrics-aggregation skills)

Location: .claude/agents/domain/*.md

Generation: Architect analyzes your product spec and creates domain agents matching your business logic.

How Generated Skills Work With Agents

Generated tech stack skills are used by core agents (backend, frontend, tester).

Auto-generation workflow:

Run /agentful-generate and Architect will:

  1. 🔍 Scan your codebase for tech stack and conventions
  2. 📝 Generate skills documenting your specific patterns (not generic framework docs)
  3. ✨ Core agents automatically find and use these skills - zero modification
  4. 🏗️ Optionally create domain agents for business workflows

3. Ephemeral Agents

Temporary agents for one-off tasks. Created on-demand, destroyed after completion.

Use cases:
  • Database migrations
  • Large-scale refactoring
  • Security audits
  • Data imports
  • One-time cleanup

Location: .claude/agents/ephemeral/

Lifecycle: Created → Execute → Report → Archive/Delete

Using Agents

Manual Invocation

Tag agents with @agent-name in chat:

@backend Implement user authentication with JWT
@frontend Create login page with form validation
@tester Write tests for auth service
@reviewer Check all changes

Automatic Delegation

The Orchestrator automatically delegates work:

User: "Build authentication"
  ↓
Orchestrator → @backend (API routes)
Orchestrator → @frontend (login page)
Orchestrator → @tester (tests)
Orchestrator → @reviewer (validation)
Orchestrator → @fixer (fix issues)

Agent Workflow

Standard development cycle:

1. Orchestrator reads product spec
2. Delegates to Backend/Frontend for implementation
3. Delegates to Tester for test coverage
4. Delegates to Reviewer for validation
5. If issues found → Fixer → Reviewer again
6. Updates completion tracking
7. Continues to next feature

Key Distinctions

Reviewer vs Fixer

  • Reviewer = DETECTS issues (runs 6 core quality gates)
  • Fixer = FIXES issues (reads .agentful/last-validation.json)

Reviewer finds problems, Fixer solves them.

Backend vs Frontend

  • Backend = API routes, services, repositories, database
  • Frontend = UI components, pages, hooks, state, styling

Agents never cross domains. Backend doesn't modify UI; Frontend doesn't touch APIs.

Core vs Domain

  • Core agents = General roles (backend, frontend, tester, reviewer)
  • Domain agents = Business-specific roles (payment-processor, order-fulfillment, subscription-manager)

Core agents handle generic implementation. Domain agents understand your business logic and workflows.

Agent Communication

Agents communicate through:

  1. State files - .agentful/state.json, completion.json, decisions.json
  2. Task tool - Spawn other agents: Task("backend", "implement X")
  3. File system - Shared codebase
  4. Review reports - .agentful/last-validation.json

See Background Agent Patterns for detailed information on how agents delegate work, execution patterns, and future parallelization plans.

Model Selection

Opus (Highest Reasoning)

  • Orchestrator - Complex coordination
  • Architect - Tech stack analysis

Sonnet (Balanced)

  • Backend, Frontend, Tester, Reviewer, Fixer - Implementation work

Opus = expensive but smarter. Sonnet = fast and capable for most tasks.

Creating Custom Agents

See Custom Agents for:

  • Creating specialized agents
  • Supporting new technologies
  • Building ephemeral agents
  • Agent templates and patterns

Monitoring Agents

Check agent activity:

# View state
cat .agentful/state.json
 
# View completion
cat .agentful/completion.json
 
# View pending decisions
cat .agentful/decisions.json
 
# View last review
cat .agentful/last-validation.json

Next Steps