# How the Egonex-AI Multi-Agent Pipeline Orchestrates 6 Specialized Agents

> Discover how the Egonex-AI multi-agent pipeline orchestrates 6 specialized agents. Learn about its deterministic five-phase process and JSON payload communication for efficient task execution.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: architecture
- Published: 2026-06-14

---

**The Egonex-AI multi-agent pipeline runs a deterministic, five-phase orchestration driven by the `/understand` skill, which dispatches six specialized agents in sequence via JSON payloads passed through the temporary directory `.understand-anything/tmp`.**

The Understand-Anything plugin implements a modular, file-based coordination system where each agent performs a self-contained step in the analysis workflow. According to the Egonex-AI source code in `Egonex-AI/Understand-Anything`, the pipeline transforms raw repositories into enriched knowledge graphs without hard-coded logic in the orchestrator, instead using deterministic bundled scripts and standardized JSON interfaces to ensure reproducible results across runs.

## The Six Specialized Agents

The pipeline executes six dedicated agents in a fixed order, where each agent consumes the output of its predecessor and writes intermediate artifacts to the shared temporary folder.

### Project-Scanner

The **Project-Scanner** agent initiates the pipeline by walking the repository and enumerating every file. It detects language and category, counts lines, estimates project complexity, and produces an *import map* of internal references. According to [`understand-anything-plugin/agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md), this agent writes two critical files: [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json) containing the file list and [`ua-import-map-output.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-import-map-output.json) containing the import map. It invokes the bundled script `scan-project.mjs` to ensure deterministic file system traversal.

### File-Analyzer

The **File-Analyzer** agent splits the file list into size-limited *batches* and processes each batch independently. For every batch, it runs the bundled **tree-sitter** extraction script `extract-structure.mjs` located in `understand-anything-plugin/skills/understand/`. This yields functions, classes, metrics, and raw import data. The agent then creates **graph nodes** and **edges** (e.g., `contains`, `imports`, `calls`) for every file, writing outputs like `batch-<index>.json` or `batch-<index>-part-k.json` containing `nodes[]` and `edges[]` arrays.

### Architecture-Analyzer

The **Architecture-Analyzer** agent consumes all batch graphs from the previous step and merges them into a single unified **knowledge graph**. As implemented in [`understand-anything-plugin/agents/architecture_analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/architecture_analyzer.md), it enriches the graph with higher-level concepts such as packages, services, and pipelines while applying *deduplication* and *consistency* checks. The final output is [`graph-assembled.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-assembled.json), which represents the full knowledge graph of the codebase.

### Tour-Builder

The **Tour-Builder** agent traverses the assembled graph to generate an ordered **tour**—a linear narrative that drives the interactive dashboard. Defined in [`understand-anything-plugin/agents/tour-builder.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/tour-builder.md), this agent selects a starting node (usually the project entry-point) and computes a breadth-first path that maximizes coverage while respecting edge weights. It persists the ordered list of node IDs to [`tour-plan.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour-plan.json).

### Graph-Reviewer

The **Graph-Reviewer** agent runs a final validation pass over the assembled graph and tour plan. It checks that every edge points to an existing node, verifies that node IDs follow required prefixes, and ensures weight constraints are satisfied. This agent also prunes *dangling* edges produced by earlier processing stages. If validation fails, it reports errors back to the skill for a retry; otherwise, it writes the cleaned [`graph-final.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-final.json) to the temporary directory.

### Domain-Analyzer

The **Domain-Analyzer** (also referenced as the optional "knowledge-graph-guide") provides a **human-readable summary** of the final graph for the `/understand` command’s textual response. According to [`understand-anything-plugin/agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/domain-analyzer.md), it formats the project name, total file count, language list, and complexity hint without exposing raw JSON, delivering the final output to the LLM front-end.

## Coordination Mechanics and Data Flow

The Egonex-AI multi-agent pipeline relies on strict file-based contracts rather than in-memory message passing, enabling resilient and debuggable orchestration.

### Dispatch via SKILL.md

The top-level skill defined in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) contains a list of **sub-agent prompts**. For each phase, the skill reads the appropriate JSON from the temporary folder and injects it into the sub-agent via the prompt’s `{{INPUT_JSON}}` placeholder. This architecture keeps the orchestrator free of business logic while enforcing a declarative execution flow.

### Deterministic Script Execution

Every agent delegates computational work to **bundled scripts** rather than re-implementing logic:

- **Project-Scanner** uses `scan-project.mjs` and `extract-import-map.mjs`
- **File-Analyzer** uses `extract-structure.mjs` (tree-sitter based)
- **Architecture-Analyzer** uses [`merge-batch-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-batch-graphs.py) (Python)

This guarantees that results are reproducible across runs, as the agents merely forward deterministic outputs from these scripts.

### Error Handling and Abort Logic

If any bundled script exits with a non-zero status, the responsible agent captures `stderr`, surfaces the warning to the skill, and aborts the pipeline. This allows users to inspect the failure and retry the operation without corrupting downstream artifacts.

## Running the Pipeline

You can trigger the full six-agent pipeline via command line or programmatically through the Node API.

### CLI Execution

```bash

# Install the monorepo (requires pnpm >=10)

pnpm install

# Run the full pipeline on the current repository

pnpm --filter @understand-anything/skill run /understand --full

# Inspect generated artifacts

ls .understand-anything/intermediate/

# Output: ua-scan-files.json ua-import-map-output.json batch-0.json ... graph-final.json

```

This command triggers the sequential execution of all six agents, writing intermediate JSON files to `.understand-anything/tmp` and returning a concise human-readable summary (e.g., "Project **understand-anything**, 42 files, languages: TypeScript, Markdown, Dockerfile, estimated complexity: moderate").

### Node API Integration

```javascript
import { spawn } from 'child_process';
import path from 'path';

// Path to the plugin root
const PLUGIN_ROOT = path.resolve('understand-anything-plugin');

// Run the top-level skill
const proc = spawn('pnpm', [
  '--filter', '@understand-anything/skill',
  'run', '/understand', '--full'
], { stdio: 'inherit', cwd: PLUGIN_ROOT });

proc.on('close', (code) => {
  if (code === 0) {
    console.log('✅ Understand pipeline completed');
  } else {
    console.error(`❌ Pipeline exited with code ${code}`);
  }
});

```

## Key Source Files

| Component | Source File |
|-----------|-------------|
| Orchestrator skill entry point | [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) |
| Project-Scanner definition | [`understand-anything-plugin/agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md) |
| File-Analyzer definition | [`understand-anything-plugin/agents/file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/file-analyzer.md) |
| Architecture-Analyzer definition | [`understand-anything-plugin/agents/architecture_analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/architecture_analyzer.md) |
| Tour-Builder definition | [`understand-anything-plugin/agents/tour-builder.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/tour-builder.md) |
| Graph-Reviewer definition | [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) |
| Domain-Analyzer definition | [`understand-anything-plugin/agents/domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/domain-analyzer.md) |
| Project scan script | `understand-anything-plugin/skills/understand/scan-project.mjs` |
| Import extraction script | `understand-anything-plugin/skills/understand/extract-import-map.mjs` |
| Tree-sitter extraction | `understand-anything-plugin/skills/understand/extract-structure.mjs` |
| Graph merger utility | [`understand-anything-plugin/skills/understand/merge-batch-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/merge-batch-graphs.py) |

## Summary

- The **Egonex-AI multi-agent pipeline** coordinates six specialized agents through file-based JSON exchange in `.understand-anything/tmp`.
- Agents execute in a fixed sequence: **Project-Scanner** → **File-Analyzer** → **Architecture-Analyzer** → **Tour-Builder** → **Graph-Reviewer** → **Domain-Analyzer**.
- Each agent bundles deterministic scripts (Node.js and Python) rather than implementing logic internally, ensuring reproducible analysis.
- The `/understand` skill in [`SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/SKILL.md) dispatches agents by injecting JSON payloads into prompt templates using the `{{INPUT_JSON}}` placeholder.
- Error handling is strict: non-zero script exits abort the pipeline and surface `stderr` to the user for debugging.

## Frequently Asked Questions

### How does the Egonex-AI pipeline ensure deterministic results across different runs?

The pipeline achieves determinism by delegating all computational work to **bundled scripts** (`scan-project.mjs`, `extract-structure.mjs`, [`merge-batch-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-batch-graphs.py)) rather than allowing agents to re-implement logic. Each script produces standardized JSON outputs that subsequent agents consume, eliminating non-deterministic behavior from the orchestration layer.

### What is the role of the temporary directory `.understand-anything/tmp`?

The temporary directory serves as the **intermediate file system** for the pipeline. Agents write their outputs (e.g., [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json), [`batch-0.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/batch-0.json), [`graph-assembled.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-assembled.json)) to this folder instead of using in-memory message passing. This architecture enables debugging, allows agents to be restarted independently, and prevents data loss during failures.

### Can I run individual agents separately, or must I run the full pipeline?

While the `/understand` skill is designed to run the full six-agent sequence, you can technically execute individual agents by manually preparing their expected input JSON files in the temporary directory and invoking their specific prompts. However, the supported workflow relies on the skill's orchestration to ensure proper data dependencies and error handling between phases.

### How does the Graph-Reviewer handle inconsistencies in the knowledge graph?

The **Graph-Reviewer** agent performs a validation pass that checks for dangling edges (edges pointing to non-existent nodes), invalid node ID prefixes, and weight constraint violations. When it detects problems, it reports them back to the skill rather than writing [`graph-final.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-final.json), triggering a retry mechanism that allows the pipeline to recover from transient analysis errors.