# How the Multi-Agent Pipeline Orchestrates Analysis Phases in Understand-Anything

> Learn how the multi-agent pipeline in Understand-Anything orchestrates analysis phases. Discover how specialized agents transform codebases into knowledge graphs for robust insights.

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

---

**The Understand-Anything repository executes a deterministic five-stage multi-agent pipeline that transforms raw codebases into validated knowledge graphs by chaining specialized agents—project-scanner, file-analyzer, architecture-analyzer, tour-builder, and graph-reviewer—each feeding JSON artifacts to the next.**

The Egonex-AI/Understand-Anything project implements a declarative multi-agent pipeline to turn repository files into interactive knowledge graphs. This system uses discrete agents defined as markdown prompt templates under `understand-anything-plugin/agents/`, orchestrated by the top-level `/understand` skill to analyze codebases progressively. Understanding how these agents orchestrate analysis phases reveals the deterministic architecture behind automated codebase comprehension.

## The Five-Stage Pipeline Architecture

The multi-agent pipeline processes code through five distinct phases, with each agent consuming the output of its predecessor and emitting structured JSON for the next stage. The skill definition in `understand-anything-plugin/skills/understand/` concatenates agent prompts and feeds intermediate results forward, ensuring deterministic execution.

### Stage 1: Project-Scanner – Discovery Phase

The **project-scanner** agent initiates the pipeline with a three-step Discovery phase defined in **[project-scanner.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md)**.

- **Step A (LLM-driven)** – Analyzes top-level manifests (`README`, [`package.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/package.json), [`pyproject.toml`](https://github.com/Egonex-AI/Understand-Anything/blob/main/pyproject.toml)) to extract `name`, `rawDescription`, `frameworks`, and `languages`.
- **Step B (Script)** – Executes the bundled `scan-project.mjs` to enumerate every file, apply `.understandignore` rules, and output a deterministic JSON inventory (see lines 62-82 of the agent specification).
- **Step C (Script)** – Runs `extract-import-map.mjs` to resolve imports and build a global import graph.

The agent emits [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json), which serves as the foundation for all subsequent analysis phases.

### Stage 2: File-Analyzer – Node Creation

The **file-analyzer** agent consumes the inventory from Stage 1 and creates a graph node for every file-level entity. According to the source code in **[store.ts](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/store.ts)**, the agent maps file categories to specific node types using the `ALL_NODE_TYPES` constant, which includes types like `pipeline` for CI/CD definitions, `service` for Dockerfiles, and `file` for generic resources.

This stage transforms the flat file inventory into a partial graph with typed nodes, preparing the data for architectural aggregation.

### Stage 3: Architecture-Analyzer – Layer Building

The **architecture-analyzer** agent groups file-level nodes by their assigned types to construct higher-level layers. As specified in **[architecture-analyzer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/architecture-analyzer.md)** (lines 67-85), the agent aggregates node IDs by category—such as `file`, `config`, `document`, `service`, and `pipeline`—to create domain layers like the "CI/CD layer."

For each layer, the agent records:
- The complete set of `nodeIds`
- A human-readable `description`
- Special edge types, such as `triggers` edges from `pipeline` nodes to `service` nodes

### Stage 4: Tour-Builder – Guided Walkthrough Generation

The **tour-builder** agent walks the layered graph to generate interactive UI tours. Defined in **[tour-builder.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/tour-builder.md)**, this agent selects a representative subset of nodes from each layer to create a concise, step-by-step walkthrough.

The agent respects the `nodeTypeCounts` produced in earlier stages and generates [`tour.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour.json), which the dashboard consumes to render guided navigation through the knowledge graph.

### Stage 5: Graph-Reviewer – Schema Validation

The **graph-reviewer** agent executes the final validation pipeline: `sanitizeGraph → normalizeGraph → autoFixGraph → validate`. According to **[graph-reviewer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md)** (lines 45-110), this agent enforces two critical constraints:

1. **Uniqueness**: Every file-level node must appear in exactly one layer's `nodeIds` array.
2. **Edge Completeness**: Every `pipeline` node must have at least one `triggers` edge; missing triggers generate warnings.

Upon successful validation, the final knowledge graph is written to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), ready for dashboard visualization with color-coded node types—including the rose-tinted (`#fda4af`) `pipeline` nodes defined in **[presets.ts](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/themes/presets.ts)**.

## Running the Pipeline Locally

Execute the full multi-agent pipeline using the provided `pnpm` script:

```bash
pnpm --filter @understand-anything/skill run /understand --full .

```

This command targets the skill package and invokes the top-level skill on the current directory, triggering all five agents sequentially. The process produces:

- [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json) – Project scanner output
- [`graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph.json) – Assembled knowledge graph
- [`tour.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour.json) – UI tour definition

Start the dashboard to visualize the results:

```bash
pnpm dev:dashboard

```

The dashboard automatically reads [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) and renders the validated graph with the appropriate theme presets applied to each node type.

## Key Implementation Files

| File | Role |
|------|------|
| **[project-scanner.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/project-scanner.md)** | Defines the discovery phase with LLM-driven metadata extraction and bundled enumeration scripts. |
| **[file-analyzer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/file-analyzer.md)** | Maps file categories to graph node types including `pipeline` handling. |
| **[architecture-analyzer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/architecture-analyzer.md)** | Groups nodes into domain layers and creates high-level architectural views. |
| **[tour-builder.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/tour-builder.md)** | Generates the guided UI tour from the layered graph structure. |
| **[graph-reviewer.md](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md)** | Performs schema validation and enforces node uniqueness and edge completeness rules. |
| **[store.ts](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/store.ts)** | Declares the `ALL_NODE_TYPES` registry including `pipeline` type definitions. |
| **[presets.ts](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/themes/presets.ts)** | Provides visual theming for node types, specifically the rose tint for pipeline nodes. |

## Summary

- The **multi-agent pipeline** executes five specialized agents in strict sequence to transform raw code into knowledge graphs.
- **JSON artifacts** pass deterministically between stages, with each agent consuming the previous output and emitting structured data for the next.
- **Agent definitions** live as markdown prompt templates under `understand-anything-plugin/agents/`, making the orchestration logic transparent and versionable.
- **Validation rules** in the graph-reviewer enforce schema compliance, ensuring every file node appears exactly once and pipeline nodes maintain required trigger edges.
- The **dashboard** renders the final validated graph using type-specific themes from the presets configuration.

## Frequently Asked Questions

### What triggers the multi-agent pipeline execution?

The pipeline triggers when you invoke the `/understand` skill via the `pnpm --filter @understand-anything/skill run /understand` command. The skill orchestrates the agents by concatenating their prompts and feeding intermediate JSON results from one step to the next, ensuring deterministic execution regardless of the codebase size.

### How does the pipeline handle CI/CD pipeline files specifically?

The **file-analyzer** assigns the `pipeline` node type to CI/CD configuration files (detected via the `ALL_NODE_TYPES` constant in [`store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/store.ts)). The **architecture-analyzer** then groups these nodes into a dedicated CI/CD layer, and the **graph-reviewer** validates that each `pipeline` node has at least one `triggers` edge pointing to a service or related resource.

### Can the pipeline be run incrementally rather than full mode?

The analysis provides the `--full` flag for complete execution, but the skill architecture supports incremental passes by reusing existing [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json) artifacts. However, the **graph-reviewer** always performs full validation in the final stage to ensure global consistency across all layers and node references.

### What happens if the graph-reviewer finds validation errors?

The **graph-reviewer** runs `sanitizeGraph → normalizeGraph → autoFixGraph → validate` and emits specific warnings for missing `triggers` on `pipeline` nodes or duplicate file-level node references. The pipeline halts before writing the final [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) if critical schema violations occur, preventing corrupted data from reaching the dashboard.