AI-assisted coding in its most common form operates within a narrow loop: one prompt, one response, one context window. For projects spanning 10+ files with interdependent modules and tasks that naturally decompose into specialized subtasks, the single-agent model becomes a bottleneck. Deploying multi-agent swarms offers a fundamentally different approach, enabling specialization, parallelism, and coordinated collaboration across distinct AI agents working in concert.

How to Deploy Multi-Agent Swarms with Ruflo

1. Install Node.js v18+, clone the ruvnet/ruflo repository, and run npm install to set up dependencies.
2. Configure your LLM provider and API key in ruflo.config.js, specifying model and environment variable references.
3. Define each agent with a unique role, scoped system prompt, tool bindings, and output format.
4. Set the execution order and handoff rules in the orchestration block to control inter-agent context flow.
5. Add error handling with retry counts, jitter, fallback agents, and human-in-the-loop breakpoints.
6. Run the swarm programmatically via node run-swarm.js, monitoring agent lifecycle events in the console.
7. Validate generated output by running the Jest test suite independently against produced files.
8. Integrate the swarm into CI/CD pipelines using a package.json script entry for automated execution.

Table of Contents

• Why Single-Prompt Coding Hits a Ceiling
• What Is Ruflo and How Does It Differ from Single-Instance Agents?
• Prerequisites and Environment Setup
• Core Concepts: Agents, Swarms, and Task Orchestration
• Building a Two-Agent Swarm: Test Writer + Code Writer
• Configuration Guide for Distributed Swarm Intelligence
• Integration with CI/CD and Development Workflows
• Implementation Checklist: Swarm Deployment Readiness
• From Orchestration Concept to Working Swarm

Why Single-Prompt Coding Hits a Ceiling

AI-assisted coding in its most common form operates within a narrow loop: one prompt, one response, one context window. Tools like GitHub Copilot, ChatGPT, and Claude Code can function as single-instance agents, generating code or answering questions within the boundaries of a single interaction. For isolated tasks, that works. For projects spanning 10+ files with interdependent modules and tasks that naturally decompose into specialized subtasks, the single-agent model becomes a bottleneck. Deploying multi-agent swarms offers a fundamentally different approach, enabling specialization, parallelism, and coordinated collaboration across distinct AI agents working in concert.

Ruflo (ruvnet/ruflo) is a swarm orchestration framework. Before proceeding, verify the repository is public and the package is published: run npm info ruflo to confirm availability. Ruflo provides the infrastructure to configure, deploy, and manage multiple specialized agents that communicate, hand off work, and produce integrated outputs. This tutorial walks through a complete implementation: by the end, readers will have a working two-agent swarm where a Test Writer agent generates tests and a Code Writer agent implements code to satisfy them, following a test-driven development workflow orchestrated entirely through Ruflo.

What Is Ruflo and How Does It Differ from Single-Instance Agents?

The Single-Agent Model and Its Limitations

Traditional single-instance AI coding tools process requests within a single prompt-response context, without built-in support for orchestrating multiple agents. They cannot delegate subtasks to other specialized agents or maintain separate role-scoped contexts simultaneously. When a project requires generating tests, writing implementation code, running linting, and producing documentation as interrelated steps, a single agent must handle everything serially. Coordinating parallel workstreams is technically possible by opening multiple sessions manually, but nothing connects their outputs. Context coherence degrades as the accumulated input approaches the model's window limit (8K tokens for base GPT-4, 128K for GPT-4 Turbo), and task complexity compounds the problem.

Ruflo's Swarm Architecture at a Glance

Ruflo, available at ruvnet/ruflo on GitHub, is an orchestration layer built for multi-agent workflows. Its design philosophy centers on enabling developers to define multiple agents, each with a distinct role, system prompt, and tool set, and then compose those agents into a swarm that executes coordinated tasks. The core differentiator is the orchestration layer itself: it manages agent lifecycle, routes tasks between agents, maintains shared memory across the swarm, and handles communication protocols including handoffs and event-driven messaging.

The key concepts in Ruflo's architecture are agents (individual AI actors scoped to a role), swarms (compositions of agents with defined interaction patterns), tasks (units of work submitted to the swarm), handoffs (the mechanism by which one agent passes output to another), and shared context (a memory store accessible across agents within a swarm).

The core differentiator is the orchestration layer itself: it manages agent lifecycle, routes tasks between agents, maintains shared memory across the swarm, and handles communication protocols including handoffs and event-driven messaging.

When to Use Ruflo vs. a Single Agent

Choosing Ruflo over a single-agent tool depends on three concrete factors: how many interdependent tasks the workflow contains, whether those tasks benefit from role-scoped context, and whether you need pipeline automation. For a quick function suggestion or a one-off refactor, a single agent remains the faster path. For workflows requiring coordinated test generation and implementation, multi-file scaffolding, or automated review pipelines, Ruflo's orchestration becomes the enabling layer.

Prerequisites and Environment Setup

What You'll Need

This tutorial requires:

• Node.js v18 or later (v18 LTS or v20 LTS recommended). This tutorial uses CommonJS syntax. If your package.json includes "type": "module", rename config files to .cjs or convert to ESM syntax.
• npm or yarn for package management
• Git for cloning the repository
• Jest v29 or later (npm install --save-dev jest). Confirm with ./node_modules/.bin/jest --version.
• An OpenAI API key with GPT-4 access enabled (GPT-4 requires separate enablement on your OpenAI account and carries higher per-token costs than GPT-3.5; see the configuration section for alternatives)

Readers should have working familiarity with JavaScript, Node.js, and basic React concepts, as the demo task involves generating a React utility function.

Installing Ruflo

The following commands clone the Ruflo repository, install its dependencies, and verify the installation is functional:

# Clone the Ruflo repository
git clone https://github.com/ruvnet/ruflo.git

# Navigate into the project directory
cd ruflo

# Install dependencies
npm install

After running these commands, check whether a CLI binary is available:

# If a CLI binary is available, this will report the version:
./node_modules/.bin/ruflo --version

If no CLI binary exists, skip this step and use the programmatic API described below. You can verify the package exposes the expected API by running:

node -e "const { Swarm } = require('ruflo'); console.log(typeof Swarm);"
# Expected output: "function"

If this prints "function", the environment is ready. If it throws an error, check that the repository's README documents a different export path or package name, and adjust accordingly.

Core Concepts: Agents, Swarms, and Task Orchestration

Defining an Agent

You define a Ruflo agent with four elements: its role (a human-readable label describing its function), its system prompt (the instructions that govern its behavior), its tools (the capabilities it can invoke, such as file system access or test runner execution), and its output contract (what it produces and in what format). Each agent handles one responsibility. A Test Writer agent knows nothing about implementation details; a Code Writer agent focuses exclusively on producing source code. The system prompt and tool bindings enforce this scoping, not hard isolation, so careful prompt design matters for maintaining role discipline.

Built-in Tool Identifiers

Ruflo provides the following built-in tools referenced throughout the configuration examples:

• fs — file system read/write operations
• testRunner — Jest test invocation
• linter — ESLint style checking
• dependencyInstaller — npm package installation

Verify the current list against the repository's tools/ directory or README. Security note: The dependencyInstaller tool can run npm install in an automated pipeline. When binding this tool in configuration, use an allowedPackages list and set denyUnknown: true to prevent installation of arbitrary or typo-squatted packages. Review any packages an agent proposes to install before allowing automated installation in production pipelines.

Composing a Swarm

A swarm composes multiple agents into a coordinated unit. Ruflo supports several communication patterns: the handoff model, where one agent's output becomes another's input in a defined sequence; a shared context store, where all agents can read from and write to a common memory space; and event-driven messaging, where agents react to lifecycle events emitted by the orchestrator or by other agents. The orchestrator sits at the center, responsible for task routing (deciding which agent handles which subtask), conflict resolution (managing cases where agents produce contradictory outputs), and output merging (combining results into a coherent final deliverable).

Task Lifecycle

When you submit a task to a Ruflo swarm, the orchestrator decomposes it into subtasks appropriate for each agent, assigns those subtasks to the responsible agents, executes them using each agent's tools and system prompts, reviews outputs against success criteria, and integrates results into the final output. In the two-agent swarm built in this tutorial, the Test Writer executes first, its output feeds into the Code Writer as context, and the orchestrator attempts to validate that the generated code passes the generated tests. Because both tests and implementation are LLM-generated, success is probabilistic. The orchestrator will retry up to maxRetries times, and human review of generated artifacts is strongly recommended before merging.

The following minimal configuration file demonstrates the anatomy of a Ruflo swarm with two agents:

// ruflo.config.js — Minimal two-agent swarm configuration
module.exports = {
  swarm: {
    name: "tdd-swarm",
    agents: [
      {
        id: "test-writer",
        role: "Test Writer",
        systemPrompt: "You are a test-writing specialist. Generate unit tests using Jest for the described functionality. Output only test files.",
        tools: ["fs", "testRunner"],
        outputFormat: "file"
      },
      {
        id: "code-writer",
        role: "Code Writer",
        systemPrompt: "You are an implementation specialist. Write source code that passes the provided tests. Output only source files.",
        tools: [
          "fs",
          "linter",
          {
            name: "dependencyInstaller",
            options: {
              allowedPackages: ["lodash", "date-fns", "uuid"],
              denyUnknown: true
            }
          }
        ],
        outputFormat: "file"
      }
    ],
    orchestration: {
      executionOrder: ["test-writer", "code-writer"],
      handoff: {
        from: "test-writer",
        to: "code-writer",
        contextMode: "full"
      }
    }
  }
};

Verify the config is valid by running node -e "require('./ruflo.config')" — it should produce no output and no errors.

This configuration establishes two agents with distinct roles and system prompts, binds specific tools to each, defines a sequential execution order, and specifies that the full output of the Test Writer is passed to the Code Writer as context.

Building a Two-Agent Swarm: Test Writer + Code Writer

Designing the Agent Roles

The Test Writer Agent

The Test Writer agent operates on a TDD-first principle. Its system prompt instructs it to generate unit and integration tests before any implementation exists. It has access to file system tools (to write test files to disk) and a test runner invocation tool (to validate that tests are syntactically correct and runnable, even if they initially fail). Its output contract specifies that it produces test files following a strict naming convention (*.test.js) with assertions against expected behavior described in the task prompt.

The Code Writer Agent

The Code Writer agent receives the Test Writer's output as its primary context. Its system prompt instructs it to implement source code that satisfies the provided tests. It has access to file system tools, a linter (to ensure output conforms to project style rules), and a dependency installer (to add any required packages). Its output contract specifies source files that, when executed against the generated tests, produce passing results.

Configuring the Swarm Workflow

The full swarm configuration expands on the minimal example with complete system prompts, detailed tool bindings, and explicit success criteria:

// ruflo.config.js — Full TDD swarm configuration
module.exports = {
  swarm: {
    name: "tdd-swarm",
    description: "Test-driven development swarm with test-first workflow",
    llm: {
      provider: "openai",
      model: process.env.OPENAI_MODEL || "gpt-4", // Requires GPT-4 API access; substitute "gpt-3.5-turbo" to reduce cost and access requirements
      apiKeyEnv: "OPENAI_API_KEY"
    },
    agents: [
      {
        id: "test-writer",
        role: "Test Writer",
        systemPrompt: `You are an expert test engineer. Given a feature description, generate comprehensive Jest unit tests. Follow these rules:
          - Use describe/it blocks with clear test names
          - Cover edge cases: empty input, null, undefined, rapid successive calls
          - Use Jest timer mocks for any time-dependent behavior
          - Output files with the .test.js extension
          - Do not implement the function under test; import it from the expected source file`,
        tools: ["fs", "testRunner"],
        outputFormat: "file",
        outputDirectory: "./src/__tests__"
      },
      {
        id: "code-writer",
        role: "Code Writer",
        systemPrompt: `You are an expert JavaScript developer. Given a set of failing tests, implement the minimal source code to make all tests pass. Follow these rules:
          - Read the test file carefully to understand expected behavior
          - Export the function as a named export
          - Do not modify the test files
          - Run the linter after writing code
          - Install any necessary dependencies`,
        tools: [
          "fs",
          "linter",
          {
            name: "dependencyInstaller",
            options: {
              allowedPackages: ["lodash", "date-fns", "uuid"],
              denyUnknown: true
            }
          }
        ],
        outputFormat: "file",
        outputDirectory: "./src"
      }
    ],
    orchestration: {
      executionOrder: ["test-writer", "code-writer"],
      handoff: {
        from: "test-writer",
        to: "code-writer",
        contextMode: "full",
        maxContextTokens: 6000
      },
      successCriteria: {
        type: "testPass",
        command: "./node_modules/.bin/jest --no-cache"
      }
    }
  }
};

Ensure the output directories exist before running the swarm (mkdir -p ./src/__tests__).

This configuration specifies the LLM provider and model, references the API key from an environment variable, defines output directories for each agent, and establishes a success criterion that the orchestrator uses to validate the final output. The outputDirectory properties on each agent control where that agent writes its files; the outputBase parameter in swarm.run() (shown in the next section) sets the base path for the run and should agree with these agent-level directories.

Implementing the Orchestration Logic

The following Node.js script initializes the Ruflo swarm, submits a task, and runs the full pipeline programmatically. Run this script from the project root — the same directory containing ruflo.config.js and package.json.

// run-swarm.js — Programmatic swarm execution
require("dotenv").config();

const fs = require("fs");
const path = require("path");

const ruflo = require("ruflo");

if (typeof ruflo.Swarm !== "function") {
  throw new Error(
    `ruflo export shape unexpected. Got keys: ${Object.keys(ruflo).join(", ")}. ` +
    "Expected { Swarm: [Function] }. Check ruflo version and entry point."
  );
}

const { Swarm } = ruflo;
const config = require("./ruflo.config");

const SWARM_TIMEOUT_MS = Number(process.env.SWARM_TIMEOUT_MS) || 120_000;

function withTimeout(promise, ms) {
  const timer = new Promise((_, reject) =>
    setTimeout(() => reject(new Error(`swarm.run() timed out after ${ms}ms`)), ms)
  );
  return Promise.race([promise, timer]);
}

function ensureOutputDirectories(swarmConfig) {
  (swarmConfig.agents ?? []).forEach((agent) => {
    if (agent.outputDirectory) {
      fs.mkdirSync(path.resolve(agent.outputDirectory), { recursive: true });
    }
  });
}

async function main() {
  // Ensure output directories exist before running
  ensureOutputDirectories(config.swarm);

  // Initialize the swarm from configuration
  const swarm = new Swarm(config.swarm);

  // Register a catch-all error handler
  swarm.on("error", (err) => {
    console.error("[swarm:error]", err?.message ?? err);
  });

  // Register event listeners for observability
  swarm.on("agent:start", ({ agentId, task }) => {
    console.log(`[${agentId}] Starting task: ${String(task?.description ?? "").slice(0, 80)}...`);
  });

  swarm.on("agent:complete", ({ agentId, output }) => {
    const files = output?.files ?? [];
    console.log(`[${agentId}] Completed. Output files: ${files.join(", ") || "(none)"}`);
  });

  swarm.on("handoff", ({ from, to, contextSize }) => {
    console.log(`[handoff] ${from} → ${to} (${contextSize} tokens of context)`);
  });

  swarm.on("swarm:complete", ({ success, testResults }) => {
    console.log(`
Swarm finished. Tests passed: ${success}`);
    if (testResults) {
      console.log(`Test summary: ${testResults.passed} passed, ${testResults.failed} failed`);
    }
  });

  // Submit a task to the swarm with a timeout guard
  const result = await withTimeout(
    swarm.run({
      description: "Create a React utility function called debounce that delays invoking a provided function until after a specified number of milliseconds have elapsed since the last invocation. It should support cancellation and immediate invocation options.",
      outputBase: "./src"
    }),
    SWARM_TIMEOUT_MS
  );

  // Handle the result
  if (result.success) {
    console.log("
All tests pass. Generated files:");
    (result.files ?? []).forEach((f) => console.log(`  ${f}`));
  } else {
    console.error("
Swarm completed with failures:");
    console.error(JSON.stringify(result.errors, null, 2));
    process.exitCode = 1;
  }
}

main().catch((err) => {
  console.error("[fatal]", err?.message ?? err);
  process.exitCode = 1;
});

This script demonstrates swarm initialization from the configuration object, defensive export checking for the ruflo package, a timeout guard to prevent indefinite hangs, event listeners for agent lifecycle visibility, task submission with a natural-language description, and result handling that reports success or failure with generated file paths.

Running the Swarm End-to-End

Execute the swarm and observe the full workflow. First, set your API key securely:

# Option 1: Export in your shell (macOS/Linux)
export OPENAI_API_KEY="your-api-key-here"

# Option 1a: On Windows PowerShell
# $env:OPENAI_API_KEY = "your-api-key-here"

# Option 1b: On Windows Command Prompt
# set OPENAI_API_KEY=your-api-key-here

# Option 2 (recommended): Use a .env file with dotenv
# 1. npm install dotenv
# 2. Create a .env file: OPENAI_API_KEY=your-api-key-here
# 3. Add .env to your .gitignore to avoid committing secrets
# (run-swarm.js already calls require('dotenv').config() at the top)

Then run the swarm from the project root:

# Run the swarm
node run-swarm.js

Output will vary per run. You should observe agent start/complete events logged in execution order, a handoff log line showing the token count of context passed between agents, and a final Tests passed: true line if the implementation succeeds. Token counts and test counts are non-deterministic and will differ between runs. A typical successful run produces output resembling:

[test-writer] Starting task: Create a React utility function called debounce...
[test-writer] Completed. Output files: src/__tests__/debounce.test.js
[handoff] test-writer → code-writer (<token count> tokens of context)
[code-writer] Starting task: Create a React utility function called debounce...
[code-writer] Completed. Output files: src/debounce.js

Swarm finished. Tests passed: true
Test summary: <N> passed, <N> failed

You can verify independently:

./node_modules/.bin/jest src/__tests__/debounce.test.js

The Test Writer agent generates debounce.test.js with test cases covering standard delayed invocation, cancellation, immediate mode, and edge cases. The Code Writer agent receives those tests as context and produces debounce.js with an implementation that satisfies all assertions. The orchestrator runs the Jest test suite as its success criterion and reports the results. Because both tests and implementation are LLM-generated, results may vary — review the generated files before incorporating them into your project.

Configuration Guide for Distributed Swarm Intelligence

Scaling Beyond Two Agents

The two-agent pattern extends naturally to larger swarms. If your swarm needs quality gates, add a Reviewer agent that performs automated code review on the Code Writer's output, checking for specific issues: unused variables, O(n²) loops in hot paths, or unsanitized user input. A Docs agent can generate JSDoc comments and README sections from the implemented code. A Refactor agent can optimize the implementation after tests pass. Each additional agent needs a defined role, system prompt, tool bindings, and a position in the execution order or a set of event triggers that determine when it activates.

Configure agent dependencies and execution order in the orchestration block. Agents can run sequentially (each waits for the previous to complete), in parallel (multiple agents execute simultaneously on different subtasks, if the orchestration configuration supports it), or in a hybrid pattern where some steps are parallel and others are sequential. Consult the Ruflo repository's documentation for the specific configuration properties that enable parallel execution.

Tuning Communication and Context Sharing

The contextMode property on handoff rules controls how much information flows between agents. Setting it to "full" passes the complete output of the upstream agent. Setting it to "summary" instructs the orchestrator to generate a condensed version, useful when the upstream output is large and the downstream agent has a limited context window. Setting it to "filtered" allows specifying patterns or keys that determine which portions of the output are forwarded — for example, contextMode: "filtered", filterKeys: ["testFiles"] (verify the exact property name and syntax against the Ruflo API reference). Managing token budgets across agents matters more than you might expect: five agents each receiving full context from all predecessors can blow through limits fast. As a rough example, five agents consuming 4K tokens each means 20K tokens per run, which already exceeds GPT-4-8K's context window. Filtering and summarization are the primary mechanisms for keeping token consumption within bounds.

Managing token budgets across agents matters more than you might expect: five agents each receiving full context from all predecessors can blow through limits fast.

Cost note: Multi-agent swarms multiply LLM token consumption. A two-agent swarm with full context handoffs may consume 2-3x the tokens of a single-agent call. With GPT-4 pricing, monitor usage carefully and consider gpt-3.5-turbo for development and testing.

Error Handling and Retry Strategies

Agent failures, whether from malformed LLM responses, tool execution errors, or outputs that fail validation, need explicit handling. The following configuration demonstrates retry logic and fallback agent definitions. This is a complete, self-contained ruflo.config.js with error handling integrated:

// ruflo.config.js — Complete config with error handling (self-contained, executable)
module.exports = {
  swarm: {
    name: "tdd-swarm",
    description: "Test-driven development swarm with test-first workflow",
    llm: {
      provider: "openai",
      model: process.env.OPENAI_MODEL || "gpt-4",
      apiKeyEnv: "OPENAI_API_KEY"
    },
    agents: [
      {
        id: "test-writer",
        role: "Test Writer",
        systemPrompt: `You are an expert test engineer. Given a feature description, generate comprehensive Jest unit tests. Follow these rules:
          - Use describe/it blocks with clear test names
          - Cover edge cases: empty input, null, undefined, rapid successive calls
          - Use Jest timer mocks for any time-dependent behavior
          - Output files with the .test.js extension
          - Do not implement the function under test; import it from the expected source file`,
        tools: ["fs", "testRunner"],
        outputFormat: "file",
        outputDirectory: "./src/__tests__"
      },
      {
        id: "code-writer",
        role: "Code Writer",
        systemPrompt: `You are an expert JavaScript developer. Given a set of failing tests, implement the minimal source code to make all tests pass. Follow these rules:
          - Read the test file carefully to understand expected behavior
          - Export the function as a named export
          - Do not modify the test files
          - Run the linter after writing code
          - Install any necessary dependencies`,
        tools: [
          "fs",
          "linter",
          {
            name: "dependencyInstaller",
            options: {
              allowedPackages: ["lodash", "date-fns", "uuid"],
              denyUnknown: true
            }
          }
        ],
        outputFormat: "file",
        outputDirectory: "./src"
      },
      {
        id: "code-writer-fallback",
        role: "Code Writer (Fallback)",
        systemPrompt: "You are a backup implementation specialist. The primary code writer failed. Carefully review the test files and produce a conservative, minimal implementation that passes all tests.",
        tools: ["fs", "linter"],
        outputFormat: "file",
        outputDirectory: "./src"
      }
    ],
    orchestration: {
      executionOrder: ["test-writer", "code-writer"],
      handoff: {
        from: "test-writer",
        to: "code-writer",
        contextMode: "full",
        maxContextTokens: 6000
      },
      successCriteria: {
        type: "testPass",
        command: "./node_modules/.bin/jest --no-cache"
      },
      errorHandling: {
        onError: "retry",
        maxRetries: 3,
        retryDelay: 2000,
        retryJitter: 1000,
        fallbackAgentId: "code-writer-fallback",
        humanInTheLoop: {
          enabled: true,
          breakpoint: "afterMaxRetries",
          notificationChannel: "console"
        }
      }
    }
  }
};

The onError property determines the initial response: retry the failed agent, skip it, or halt the swarm. maxRetries caps the number of attempts. The retryJitter property adds randomized jitter (in milliseconds) to the retryDelay to prevent thundering-herd retry collisions when multiple swarms run concurrently. If all retries are exhausted, the agent referenced by fallbackAgentId takes over. Note that with maxRetries: 3, the swarm may make up to 3 additional LLM calls before pausing — factor this into cost estimates. The humanInTheLoop configuration pauses the swarm after maximum retries and notifies the developer, allowing manual intervention before the fallback executes. These patterns make Ruflo swarms more deployable by adding retry logic, fallback routing, and human-in-the-loop pause points — the failure modes that LLM-based agents will encounter in any sustained use.

These patterns make Ruflo swarms more deployable by adding retry logic, fallback routing, and human-in-the-loop pause points — the failure modes that LLM-based agents will encounter in any sustained use.

Integration with CI/CD and Development Workflows

Running Ruflo Swarms in CI Pipelines

Ruflo swarms can run from GitHub Actions, GitLab CI, or any CI system that supports Node.js execution. A typical integration runs the swarm as a step in a pull request pipeline, generating tests and implementation for new feature descriptions included in the PR, or running a Reviewer agent against changed files. The swarm's exit code reflects the success criteria outcome, making it compatible with pipeline pass/fail gating. Verify exit code behavior against the Ruflo documentation, as this depends on the framework's process management implementation.

Connecting to Existing Node.js and React Projects

Ruflo fits into a standard package.json scripts workflow. Adding a script entry like "swarm:tdd": "node run-swarm.js" lets developers invoke the swarm with npm run swarm:tdd. Output directories in the configuration point directly into the project's source tree, so generated files land where the project expects them. The generated code writes directly to your configured outputDirectory paths, so your existing build and test tooling picks it up without manual file moves.

Implementation Checklist: Swarm Deployment Readiness

Use this checklist to verify that all components are in place before running a production swarm:

• Node.js v18+ installed and verified (node --version)
• Ruflo cloned and dependencies installed; require("ruflo") resolves without error
• Jest v29+ installed as a dev dependency (./node_modules/.bin/jest --version)
• LLM API key configured via .env file with dotenv (and .env added to .gitignore)
• GPT-4 access confirmed on your OpenAI account (or gpt-3.5-turbo substituted)
• Agent roles defined with clear, specific system prompts
• Tool bindings configured per agent (verified against Ruflo's tool registry)
• dependencyInstaller tool bound with allowedPackages and denyUnknown: true
• Output directories exist on disk (handled automatically by run-swarm.js)
• Handoff rules and execution order specified in the orchestration block
• Shared context scope defined: full, summary, or filtered per handoff
• Error handling configured with retry counts, delays, jitter, and fallback agents
• Test runner integration verified (Jest runs independently: ./node_modules/.bin/jest --version)
• Config file validated (node -e "require('./ruflo.config')")
• Swarm tested end-to-end with a sample task producing passing tests
• Generated files reviewed by a human before merging
• CI/CD integration configured for pipeline execution (optional)
• Additional agents (reviewer, documentation, refactor) planned for future expansion

From Orchestration Concept to Working Swarm

This tutorial built a functional two-agent swarm using Ruflo that generates tests and implementation code in a coordinated TDD workflow. The architecture moves past the limitations of single-prompt coding by introducing role specialization, controlled context sharing, and automated orchestration with explicit success criteria. The patterns demonstrated here, including handoff configuration, error handling, fallback agents, and CI/CD integration, extend directly to larger swarms with additional specialized agents.

Next steps: add Reviewer and Docs agents to the swarm, experiment with parallel execution patterns, and tune context sharing modes to optimize token usage across larger agent compositions. The ruvnet/ruflo repository is the starting point for both usage and contribution. File issues or share swarm configurations in the repository's Discussions tab.