Agent Architecture

agentful's architecture centers around a hub-and-spoke model where the Orchestrator coordinates all specialist agents. Each agent has clear boundaries, knows when to delegate, and communicates status back to the Orchestrator.

Core Principles

1. Clear Separation of Concerns

Each agent focuses on a specific domain:

• Product Analyzer - Requirements analysis, gap detection
• Architect - System design, tech stack decisions
• Backend - APIs, databases, server logic
• Frontend - UI components, state, client code
• Tester - Unit, integration, and E2E tests
• Reviewer - Quality gates, validation checks
• Fixer - Automated issue remediation

2. Hub-and-Spoke Delegation

The Orchestrator never writes code directly. Instead, it:

1. Analyzes the current phase of work
2. Determines which specialist is needed
3. Delegates the task with clear context
4. Receives status and results
5. Coordinates the next step

3. Bidirectional Communication

Agents communicate back to the Orchestrator when:

• Task is complete
• Decision needed from human
• Blocker encountered
• Quality gate failed

This creates a feedback loop that keeps work flowing while maintaining quality.

Agent Responsibilities

Orchestrator 🎯

Role: Workflow coordinator and task delegator

Responsibilities:

• Parse product specs and build work queues
• Delegate tasks to appropriate specialists
• Track completion percentage
• Manage decision checkpoints
• Never write code directly

Delegates to: All specialist agents

Product Analyzer 📊

Role: Requirements analysis and product spec validation

Responsibilities:

• Analyze product specifications for completeness
• Detect gaps, ambiguities, and conflicts
• Score readiness for development
• Suggest improvements to product docs

Outputs: Gap reports, readiness scores, improvement suggestions

Architect 🏗️

Role: System design and technical planning

Responsibilities:

• Detect tech stack from codebase
• Design system architecture
• Generate domain-specific agents
• Establish coding patterns and conventions
• Create architectural decision records (ADRs)

Outputs: Architecture docs, generated agents, tech stack config

Backend ⚙️

Role: Server-side development

Responsibilities:

• API endpoints and routes
• Database schemas and migrations
• Authentication and authorization
• Business logic and domain models
• Server configuration

Delegates to: @tester for backend tests, @reviewer for API validation

Frontend 🎨

Role: Client-side development

Responsibilities:

• UI components and pages
• State management
• Form handling and validation
• Responsive design
• Client-side routing
• Asset optimization

Delegates to: @tester for component tests, @reviewer for accessibility checks

Tester 🧪

Role: Test generation and execution

Responsibilities:

• Write unit tests
• Write integration tests
• Write E2E tests
• Ensure 80%+ code coverage
• Maintain test infrastructure

Outputs: Test files, coverage reports

Reviewer 🔍

Role: Quality validation and production readiness

Responsibilities:

• Run all quality gates (type checking, linting, tests, coverage)
• Detect dead code and unused dependencies
• Security vulnerability scanning
• Performance analysis
• Accessibility validation

Outputs: Validation reports, quality scores

Fixer 🔧

Role: Automated issue remediation

Responsibilities:

• Fix type errors
• Fix linting issues
• Fix failing tests
• Remove dead code
• Update dependencies with vulnerabilities

Triggered by: Failed validation from @reviewer

Workflow Example

Here's how agents collaborate to implement a new feature:

Agent Communication Protocol

Agents communicate through structured messages and update state files using the centralized validator.

Status Updates

Agents report completion status and artifacts created:

{
  "agent": "backend",
  "status": "complete",
  "artifacts": ["/api/users.ts", "/lib/db/users.ts"],
  "next_steps": "Request @tester to write tests"
}

After completing work, agents update state using updateStateFile():

// Backend agent updates completion tracking
updateStateFile(projectRoot, 'completion.json', (state) => ({
  ...state,
  features: {
    ...state.features,
    'user-api': { status: 'complete', progress: 100 }
  }
}));

Decision Requests

Agents can request human input for architectural or design decisions:

{
  "agent": "architect",
  "status": "blocked",
  "decision": {
    "question": "Use PostgreSQL or MongoDB for user data?",
    "options": ["PostgreSQL", "MongoDB"],
    "context": "User data is relational, but we may need flexible schemas for metadata"
  }
}

Decisions are tracked in decisions.json and can be resolved via /agentful-decide.

Quality Gate Results

The Reviewer agent validates code and updates quality gate status:

{
  "agent": "reviewer",
  "status": "failed",
  "gates": {
    "type_check": "passed",
    "lint": "failed",
    "tests": "passed",
    "coverage": "passed",
    "security": "passed",
    "dead_code": "passed"
  },
  "failures": [
    { "gate": "lint", "count": 3, "details": "..." }
  ]
}

Quality gates are persisted to completion.json for tracking overall quality metrics.

State Management & Validation

agentful tracks all runtime state in the .agentful/ directory using 7 core JSON files. These files maintain the current work phase, feature completion, pending decisions, and conversation context.

State Files Overview

Centralized Validation

All state files use a centralized validator (lib/state-validator.js) that:

• Validates JSON structure - Ensures files are valid JSON and parse correctly
• Checks required fields - Verifies all mandatory fields are present
• Auto-recovers corrupted files - Automatically repairs or recreates invalid state
• Provides consistent error messages - Standardized error reporting across all files

Auto-Recovery Mechanisms

When state files are missing or corrupted, the validator automatically:

1. Detects the issue - Identifies missing files, invalid JSON, or missing required fields
2. Backs up corrupted files - Creates timestamped backup (e.g., state.json.backup-1706198400)
3. Creates fresh file with defaults - Initializes new file with schema-defined default values
4. Logs recovery action - Reports what was recovered and how

import { getStateFile, updateStateFile } from './lib/state-validator.js';
 
// Get state with automatic recovery
const result = getStateFile(projectRoot, 'completion.json', { autoRecover: true });
 
if (result.recovered) {
  console.log('State file was corrupted and has been recovered');
}
 
// Update state with validation
updateStateFile(projectRoot, 'completion.json', {
  overall_progress: 85,
  features_complete: 17,
  features_total: 20
});

Agent State Integration

Agents communicate and update state through the centralized validator:

// Orchestrator updates current phase
updateStateFile(projectRoot, 'state.json', (current) => ({
  ...current,
  current_phase: 'implementation',
  current_task: 'backend-api',
  last_updated: new Date().toISOString()
}));
 
// Reviewer updates quality gates
updateStateFile(projectRoot, 'completion.json', (current) => ({
  ...current,
  gates: {
    ...current.gates,
    tests_passing: true,
    coverage_80: true,
    no_type_errors: true
  }
}));

State File Schemas

All state files follow strict schemas with required fields and defaults. For detailed schema documentation, see:

• State Files Reference - Complete schema definitions
• State Validator API - Validation and recovery API

Manual State Recovery

If you need to manually reset state:

# Delete corrupted state file (will be auto-recovered on next command)
rm .agentful/state.json
 
# Or delete all state to start fresh
rm -rf .agentful/
 
# Run any agentful command to trigger initialization
/agentful-status

Adding Custom Agents

agentful can generate domain-specific agents based on your codebase patterns:

# Architect agent analyzes your code and generates specialists
/agentful-start
 
# Generated agents appear in .claude/agents/
# Examples:
# - auth-agent.md - Authentication patterns
# - payment-agent.md - Payment processing
# - notification-agent.md - Email/SMS/push

Custom agents follow the same delegation principles and quality standards as core agents.

Next Steps

• Run your first agentful session →
• Configure quality gates →
• View all available commands →