How the Tour-Builder Agent Generates Dependency-Ordered Learning Tours in Understand Anything

The tour-builder agent creates pedagogical learning paths by analyzing the codebase's knowledge graph to compute dependency rankings, then mapping breadth-first traversal depths into sequential tour steps while weaving in documentation and architectural layers.

The tour-builder agent in the Egonex-AI/Understand-Anything repository transforms raw project graphs into structured educational experiences. By processing the JSON knowledge graph produced by the core analysis engine, it generates dependency-ordered learning tours that guide users from foundational concepts to complex implementations. This automated approach ensures learners encounter code in the order it actually depends on, rather than alphabetical or arbitrary file listings.

Two-Phase Tour Generation Workflow

The agent operates through a distinct two-phase pipeline defined in understand-anything-plugin/agents/tour-builder.md, separating structural analysis from pedagogical assembly.

Phase 1: Graph Topology Analysis

First, the agent generates and executes a Node.js analysis script (saved as ua-tour-analyze.js) that computes critical dependency metrics from the input graph containing nodes, edges, and layers. According to the source documentation, this script calculates:

• Fan-In ranking (lines 55-58): Counts incoming edges to identify highly-depended-upon files that should appear early in the learning path
• Fan-Out ranking (lines 59-62): Counts outgoing edges to spot broad-scope modules that impact many other components
• Entry-point candidates (lines 63-71): Scores potential starting locations based on filename patterns, directory location, and fan-out/in ratios
• BFS traversal (lines 79-88): Performs a breadth-first walk from the top code entry point following imports and calls edges to establish dependency depth
• Non-code inventory (lines 88-95): Groups documentation, services, data, and configuration files for later integration
• Tightly-coupled clusters (lines 98-104): Identifies bidirectional edge groups that should be taught as unified concepts
• Layer architecture (lines 106-108): Preserves the project's architectural layer definitions for narrative structure
• Node-summary index (lines 110-114): Creates a quick lookup table mapping node IDs to their names, types, and summaries

The script writes these computed structures to ua-tour-results.json (format example at lines 118-176), creating the foundation for tour assembly.

Phase 2: Pedagogical Tour Design

Using only the analysis output, the agent constructs the final learning path without re-analyzing the source code. The design process follows specific heuristics:

1. Starting point selection (lines 12-18): Prefers README.md if present in entry-point candidates, otherwise selects the top-ranked code entry point
2. Depth-to-step mapping (lines 22-30): Translates BFS depth levels into tour order—depth 0 becomes the first code step, depth 1 the subsequent steps, ensuring dependency order is maintained
3. Non-code integration (lines 34-57): Inserts documentation, Dockerfiles, CI configurations, and schema files at logical pedagogical points rather than grouping them separately
4. Cluster consolidation (lines 59-61): Merges nodes from tightly-coupled clusters into single tour steps to prevent fragmented learning
5. Layer-driven narrative (lines 63-66): Uses the architectural layer descriptions to guide the overall story arc, ensuring foundational layers precede dependent ones
6. Step composition (lines 68-75): For each step, pulls summaries from the nodeSummaryIndex to craft 2-4 sentence descriptions and optional languageLesson fields

Key Graph Metrics for Dependency Ordering

The dependency ordering relies on specific graph algorithms that identify which files learners must understand first.

Fan-In and Fan-Out Analysis

Files with high fan-in (many incoming edges) represent critical dependencies that many other modules rely on—these appear early. High fan-out files (many outgoing edges) indicate broad utility modules that warrant early explanation.

Breadth-First Traversal

The BFS algorithm (lines 79-88) walks from the entry point following only imports and calls edge types, assigning each node a depth value. This depth directly determines the tour step order, ensuring learners never encounter a file before its dependencies.

Tightly-Coupled Clusters

Bidirectional edge analysis (lines 98-104) identifies clusters where modules mutually depend on each other. Rather than splitting these across multiple steps, the agent groups them into single conceptual units.

Output Format and File Structure

The final artifact is written to .understand-anything/intermediate/tour.json as a JSON array containing 5-15 ordered steps. Each step object includes:

• order: Sequential integer determining position
• title: Human-readable step name
• description: 2-4 sentence pedagogical explanation
• nodeIds: Array of graph node identifiers included in this step
• languageLesson: Optional educational context about specific programming concepts

The agent then reports a concise summary of the generated tour (lines 74-78) to complete the workflow.

Running the Tour-Builder Analysis

To execute the tour generation manually or integrate it into custom workflows:

# 1️⃣ Create the input JSON (example excerpt)

cat > .understand-anything/tmp/ua-tour-input.json <<'EOF'
{
  "nodes": [
    {"id":"file:src/index.ts","type":"file","name":"index.ts","filePath":"src/index.ts","summary":"Main entry"},
    {"id":"document:README.md","type":"document","name":"README.md","filePath":"README.md","summary":"Project overview"}
  ],
  "edges": [
    {"source":"file:src/index.ts","target":"file:src/utils.ts","type":"imports"},
    {"source":"document:README.md","target":"file:src/index.ts","type":"documents"}
  ],
  "layers": [{"id":"layer:core","name":"Core","description":"Core logic"}]
}
EOF

# 2️⃣ Execute the auto-generated script (the agent writes it to

#    .understand-anything/tmp/ua-tour-analyze.js)

node .understand-anything/tmp/ua-tour-analyze.js \
     .understand-anything/tmp/ua-tour-input.json \
     .understand-anything/tmp/ua-tour-results.json

The script produces ua-tour-results.json, which the tour-builder agent consumes to emit the final ordered tour.

Summary

• The tour-builder agent generates dependency-ordered learning tours through a two-phase process: graph topology analysis followed by pedagogical assembly
• Fan-in ranking identifies critical dependencies that must be taught first, while BFS traversal establishes the dependency depth hierarchy
• Tightly-coupled clusters are merged into single steps to prevent fragmented learning experiences
• Non-code artifacts like READMEs and configurations are integrated at pedagogically logical points rather than appended to the end
• The final output is written to .understand-anything/intermediate/tour.json as an ordered array of 5-15 educational steps

Frequently Asked Questions

What input data does the tour-builder agent require?

The agent requires a JSON knowledge graph containing three top-level keys: nodes (file and document entities), edges (relationships like imports, calls, and documents), and layers (architectural layer definitions). This data is typically produced by the Understand Anything core analysis engine and passed to the generated ua-tour-analyze.js script.

How does the agent determine where to start the learning tour?

According to understand-anything-plugin/agents/tour-builder.md lines 12-18, the agent first checks for README.md in the entry-point candidates. If found, it becomes the starting point. Otherwise, the agent selects the top-ranked code entry point based on the scoring algorithm that considers filename patterns, directory depth, and fan-out/in metrics.

Why does the agent use BFS traversal instead of DFS?

The breadth-first approach (lines 79-88) ensures that all dependencies at the same depth level are taught before moving to deeper, more dependent code. This creates a breadth-first learning experience where learners understand the immediate dependencies of the entry point before exploring transitive dependencies, maintaining a logical dependency order throughout the tour.

Can the tour-builder handle non-code files like documentation and configuration?

Yes. During Phase 2 (lines 34-57), the agent specifically inventories non-code items including documentation, Dockerfiles, CI configurations, and schema files. These are inserted at strategic points in the tour—for example, a Dockerfile might appear after the entry point is introduced but before implementation details, rather than being grouped arbitrarily at the beginning or end.

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