Assistant AntFarm Swarm Architecture

AntFarm is a project-oriented execution framework designed for complex engineering and content creation tasks using a swarm of specialized agents.

Swarm Hierarchy

The swarm is orchestrated by a Queen session that manages multiple Ant workers.

Role	Purpose
Queen	Swarm orchestrator, task decomposition, and delegation.
Worker	General task execution (coding, writing, analysis).
Soldier	Security validation, testing, and error checking.
Scout	Research, information gathering, and discovery.
Debugger	Troubleshooting, log analysis, and bug fixing.
Janitor	Optimization, cleanup, and resource management.

Execution Model

Swarm Queue

The system supports parallel execution via a Swarm Queue. The Queen decomposes the objective into a list of tasks, which are then distributed to a worker pool.

Ralph Loop (Self-Correction)

Every ant worker performs a "Ralph Loop" after completing a task:

Verification: The worker verifies its output against the original task requirement.
Internal Feedback: If the verification fails, the worker generates internal feedback and retries the task (up to a predefined limit).
Final Delivery: Only verified outputs are returned to the Queen.

Circuit Breakers

The AntFarm includes workspace-level circuit breakers that "trip" if a project environment experiences a high failure rate. This prevents the swarm from wasting tokens on a broken or inaccessible workspace.

Component Diagram: AntFarm Orchestration

graph TD
    User([User Objective]) --> Queen[Queen Session]
    Queen --> Planner[Task Decomposition]
    Planner --> Queue[Swarm Queue]
    
    subgraph "Worker Pool"
        Queue --> W1[Worker Ant]
        Queue --> W2[Scout Ant]
        Queue --> W3[Soldier Ant]
    end
    
    W1 --> Ralph[Ralph Loop: Verify & Retry]
    Ralph --> Queen
    W2 --> Ralph
    W3 --> Ralph

Key Files & Functions

assistant/antfarm.go: Core swarm orchestration and worker lifecycle management.
assistant/ant_tools.go: Specialized tools for file system and workspace operations used by ants.
pm_* Tools: The suite of Project Management tools used by the Queen.

Guidance for AI Agents

Trust the Soldiers: If a Soldier ant flags a security or testing issue, do not ignore it. Fix the underlying problem before proceeding.
Parallelize Wisely: Use pm_run_batch for independent sub-tasks to speed up project execution.

Antfarm Swarm