# How Agent Teams and Swarm Coordination Work in Personal AI Infrastructure (PAI)

> Discover how agent teams and swarm coordination power Personal AI Infrastructure. Learn to create coordinated autonomous workers for parallel task execution.

- Repository: [Daniel Miessler 🛡️/Personal_AI_Infrastructure](https://github.com/danielmiessler/personal_ai_infrastructure)
- Tags: deep-dive
- Published: 2026-02-16

---

**Agent teams in PAI are coordinated swarms of autonomous workers that share task lists and execute in parallel, triggered by the specific phrase "create an agent team" and orchestrated through the experimental `TeamCreate` tool.**

Personal AI Infrastructure (PAI) by Daniel Miessler extends single-agent workflows into collaborative **agent teams** that operate as a coordinated swarm. This architecture allows multiple autonomous agents to decompose complex problems, execute criteria in parallel, and synchronize state through shared memory and message passing.

## What Are Agent Teams in PAI?

An **agent team** (also called a **swarm**) is a coordinated collection of agents that operate on shared work items. All members see the same list of criteria and can report progress, blockers, or results to each other. This design treats agents as autonomous workers capable of tackling complex problems that would overwhelm a single agent.

Key characteristics include:

- **Shared Task Lists**: Every team member accesses the same criteria and PRD (Product Requirements Document) slices.
- **Parallel Execution**: Workers run simultaneously rather than sequentially.
- **Message Exchange**: Agents broadcast findings or request assistance via structured messaging.

## How Swarm Coordination Is Triggered

Teams are created only when an agent outputs the exact phrase **"create an agent team"**. This activates the experimental `TeamCreate` tool, which requires the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be set.

According to the source documentation in [`Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md) at line 801, this trigger phrase is the critical invocation point. Without this specific output, the system treats the request as a standard single-agent task.

## The Agent Team Lifecycle

The lifecycle follows a deterministic sequence defined in the Algorithm component:

1. **Lead Agent Calls `TeamCreate`**: The primary agent identifies the need for parallelization and triggers team creation.
2. **Workers Spawn with Task Tool**: Child agents are spawned using the standard `Task` tool calls that include a `team_name` parameter.
3. **Independent Algorithm Iteration**: Each worker runs its own iteration of the Algorithm against a child PRD or a slice of the parent PRD.
4. **Result Aggregation**: The lead agent aggregates results, updates the parent PRD, and marks the team as complete.

This process is documented in [`Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md) at line 805 under the section "When decomposing into child PRDs".

## Parallel Agent Orchestration and Load Balancing

When running in loop mode, the `‑a <N>` CLI flag tells the algorithm how many agents to run concurrently. The runtime partitions failing criteria among agents using a greedy load-balancer implemented in the `partitionCriteria` function.

### State Management

The system maintains shared state in `MEMORY/STATE/algorithms/<session>.json`. This file stores:

- The list of active agents
- Assigned criteria per agent
- Current progress and phase history

The `LoopAlgorithmState` interface defined in [`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts) at line 80 structures this data, containing `parallelAgents`, an `agents[]` array, and `phaseHistory`.

### The partitionCriteria Algorithm

The `partitionCriteria` function at line 545 of [`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts) implements greedy load-balancing:

- It filters for failing criteria
- Groups criteria by ISC domain (e.g., `ISC-API-1` → "API")
- Assigns the largest domain groups to the least-loaded agents
- Ensures domain cohesion by keeping related criteria together on the same agent

## Code Examples

### Running the Algorithm with a Swarm of 4 Agents

```bash

# Run a PRD in loop mode using four parallel agents

algorithm -m loop -p PRD-20260213-feature -n 30 -a 4

```

The `‑a 4` flag instructs the core engine to create a team of four workers. The partitioning logic in `partitionCriteria` distributes failing criteria across the agents while maintaining domain cohesion.

### Minimal TypeScript Snippet for Manual Team Creation

```ts
import { spawnSync } from "child_process";

// 1️⃣ Tell the model to create a team (must include the exact trigger phrase)
const createTeamPrompt = `Please create an agent team to audit security.`;
spawnSync("claude", [
  "-p", createTeamPrompt,
  "--allowedTools", "TeamCreate,SendMessage"
]);

// 2️⃣ Spawn three workers that belong to the team
const teamName = "security-audit";
["pentester", "recon", "qatester"].forEach(role => {
  spawnSync("claude", [
    "-p", `Run ${role} tasks on the PRD.`,
    "--allowedTools", "Task", // Task tool will inherit `team_name`
    "--env", `TEAM_NAME=${teamName}`
  ]);
});

```

The first call must contain the mandatory phrase *"create an agent team"* to trigger the experimental tool. Subsequent calls inherit the `TEAM_NAME` environment variable so the algorithm registers them under the same team.

### The partitionCriteria Implementation

```ts
function partitionCriteria(criteriaInfo: CriteriaInfo, agentCount: number): AgentAssignment[] {
  const failing = criteriaInfo.criteria.filter(c => c.status === "failing");
  if (failing.length === 0) return [];

  // Group by ISC domain (e.g., ISC‑API‑1 → "API")
  function getDomain(id: string) {
    const m = id.match(/^ISC-(.+)-\d+$/);
    return m ? m[1] : id;
  }

  const domainGroups = new Map<string, typeof failing>();
  for (const c of failing) {
    const d = getDomain(c.id);
    if (!domainGroups.has(d)) domainGroups.set(d, []);
    domainGroups.get(d)!.push(c);
  }

  // Greedy load‑balancing: assign the biggest domain to the least‑loaded agent
  const sorted = [...domainGroups.entries()].sort((a, b) => b[1].length - a[1].length);
  const effective = Math.min(agentCount, sorted.length);
  const agents: AgentAssignment[] = Array.from({ length: effective }, (_, i) => ({
    agentId: i + 1,
    criteriaIds: [],
    criteriaDetails: []
  }));

  for (const [, group] of sorted) {
    let min = agents[0];
    for (const a of agents) if (a.criteriaIds.length < min.criteriaIds.length) min = a;
    for (const c of group) {
      min.criteriaIds.push(c.id);
      min.criteriaDetails.push(c);
    }
  }
  return agents.filter(a => a.criteriaIds.length);
}

```

This function guarantees that criteria belonging to the same domain (e.g., all API-related items) stay together on the same agent, minimizing context switching while balancing workload.

## Key Files and Implementation References

- **[`Releases/v3.0/README.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/README.md)** (line 73): High-level user documentation for the Agent Teams / Swarm feature.
- **[`Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md)** (line 801): Defines the critical trigger phrase and `TeamCreate` invocation requirements.
- **[`Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Components/Algorithm/v1.6.0.md)** (line 805): Documents the team lifecycle and child PRD decomposition.
- **[`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts)** (line 80): `LoopAlgorithmState` interface defining shared state structure.
- **[`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts)** (line 545): `partitionCriteria` load-balancing implementation.
- **[`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts)** (line 166): CLI entry point handling the `‑a` flag.
- **[`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts)** (line 44): `writeAlgorithmState` persistence logic.

## Summary

- **Agent teams** (swarms) enable parallel execution of complex tasks by coordinating multiple autonomous agents around shared criteria and PRDs.
- **Team creation** requires the exact trigger phrase "create an agent team" and the experimental environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
- **Workload distribution** uses the `partitionCriteria` function to group failing criteria by domain and balance them across agents using a greedy algorithm.
- **State synchronization** occurs through the `LoopAlgorithmState` JSON structure stored in `MEMORY/STATE/algorithms/<session>.json`, enabling real-time dashboard monitoring.
- **Lifecycle management** follows a four-phase process: lead creation, worker spawning, parallel execution, and result aggregation.

## Frequently Asked Questions

### What triggers the creation of an agent team in PAI?

An agent team is created only when an agent outputs the exact phrase **"create an agent team"**. This specific trigger phrase activates the experimental `TeamCreate` tool, which requires the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` to be set. Without this exact phrase, the system processes the request as a standard single-agent task.

### How does PAI distribute work among parallel agents?

PAI uses the `partitionCriteria` function defined in [`Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts`](https://github.com/danielmiessler/Personal_AI_Infrastructure/blob/main/Releases/v3.0/.claude/skills/PAI/Tools/algorithm.ts) to distribute failing criteria across agents. The function groups criteria by their ISC domain (e.g., grouping all API-related items together), then applies a greedy load-balancing algorithm that assigns the largest domain groups to the least-loaded agents. This ensures domain cohesion while maximizing parallel efficiency.

### What is the difference between using the `-a` CLI flag and the `TeamCreate` tool?

The `‑a <N>` CLI flag runs the algorithm in **loop mode** with multiple parallel agents managed by the core engine, automatically partitioning criteria and managing state through the `LoopAlgorithmState` object. In contrast, the `TeamCreate` tool is an **experimental, trigger-based mechanism** that allows an agent to dynamically spawn a team during execution, requiring the specific phrase "create an agent team" and manual worker spawning via the `Task` tool with `team_name` parameters.

### How do agents in a swarm communicate and share state?

Agents communicate through a shared state file stored at `MEMORY/STATE/algorithms/<session>.json`, which contains the `LoopAlgorithmState` object with `parallelAgents`, an `agents[]` array, and `phaseHistory`. Additionally, agents can use the `SendMessage` tool to broadcast findings or request assistance by specifying the `team_name` parameter, enabling real-time coordination while the dashboard reads the JSON state to display per-agent status and overall progress.