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

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.

• Step A (LLM-driven) – Analyzes top-level manifests (README, package.json, 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, 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, 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 (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, 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, 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 (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, ready for dashboard visualization with color-coded node types—including the rose-tinted (#fda4af) pipeline nodes defined in presets.ts.

Running the Pipeline Locally

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

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 – Project scanner output
• graph.json – Assembled knowledge graph
• tour.json – UI tour definition

Start the dashboard to visualize the results:

pnpm dev:dashboard

The dashboard automatically reads .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	Defines the discovery phase with LLM-driven metadata extraction and bundled enumeration scripts.
file-analyzer.md	Maps file categories to graph node types including pipeline handling.
architecture-analyzer.md	Groups nodes into domain layers and creates high-level architectural views.
tour-builder.md	Generates the guided UI tour from the layered graph structure.
graph-reviewer.md	Performs schema validation and enforces node uniqueness and edge completeness rules.
store.ts	Declares the ALL_NODE_TYPES registry including pipeline type definitions.
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). 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 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 if critical schema violations occur, preventing corrupted data from reaching the dashboard.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}