AntFarm Workflows and Workspaces

The AntFarm framework in the assistant module orchestrates complex engineering tasks by employing specialized swarms of agents.

Workspace Management

Every project operated on by the AntFarm is confined to an isolated Workspace. A workspace provides:

A dedicated directory (e.g., workspaces/user/project/)
Local context files: memory.md (state), .ai_context (rules), and project.json (metadata).
Sandboxed terminal execution.

The Queen's Toolkit (Project Management)

The Queen agent directs the swarm using a suite of pm_* tools:

pm_spawn_ant: Deploys a new worker (Scout, Soldier, Debugger, Janitor) into the workspace with a specific prompt.
pm_run_batch: Pushes multiple tasks to the Swarm Queue for concurrent execution by the worker pool.
pm_snapshot / pm_restore_snapshot: Manages the project state for safe rollbacks.
pm_prepare_workspace: Initializes the workspace structure before starting a swarm task.

The Ralph Loop: Self-Correction Engine

Worker ants do not blindly return output. They utilize the "Ralph Loop," an iterative, self-verifying cycle:

Execution: The worker attempts the task.
Verification: The worker evaluates its own output against the acceptance criteria.
Correction: If flawed, the worker formulates internal feedback and retries.
Submission: Only upon successful self-verification does the worker submit the result back to the Queen.

Swarm Queue & Batch Processing

For parallelizable tasks (e.g., linting multiple files, generating documentation for several modules), the Queen uses the Swarm Queue. The system limits concurrent workers to prevent rate-limiting from the LLM provider and manages the consolidation of their outputs.

Mermaid Diagram: AntFarm Lifecycle

sequenceDiagram
    participant User
    participant Queen
    participant Workspace
    participant Swarm Queue
    participant Workers

    User->>Queen: "Refactor the authentication module"
    Queen->>Workspace: pm_prepare_workspace()
    Queen->>Queen: Decompose task into steps
    Queen->>Swarm Queue: pm_run_batch(Task 1, Task 2)
    Swarm Queue->>Workers: Dispatch tasks
    Note over Workers: Execute Ralph Loop (Verify/Retry)
    Workers-->>Swarm Queue: Consolidated Results
    Swarm Queue-->>Queen: Return batch results
    Queen->>Workspace: pm_snapshot() (Save Progress)
    Queen-->>User: "Refactoring complete."

Extension Points for AI Agents

New Ant Roles: Introduce new worker types with specialized prompts (e.g., an "Architect" ant for high-level design review before execution).
Tool Whitelists: Restrict certain ants (like "Scouts") to read-only tools to prevent accidental modification during research phases.

Antfarm Workflows