# What Is the Tour-Builder Agent? Purpose and Implementation in Understand-Anything

> Understand the tour-builder agent's purpose: transforming codebase graphs into structured learning journeys. Guide newcomers through project architecture and key concepts with logical steps.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: deep-dive
- Published: 2026-06-08

---

**The tour-builder agent transforms raw codebase graphs into structured 5-15 step learning journeys that guide newcomers through project architecture and key concepts in logical pedagogical order.**

The **tour-builder agent** serves as the pedagogical engine within the [Understand-Anything](https://github.com/Lum1104/Understand-Anything) repository, bridging the gap between static code analysis and interactive learning. By processing the nodes, edges, and layers that represent a project's structure, this agent synthesizes educational narratives that make complex codebases approachable for new contributors. According to the agent specification in [`agents/tour-builder.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/tour-builder.md), it specifically "Designs guided learning tours through codebases, creating 5-15 pedagogical steps that teach project architecture and key concepts in logical order."

## Core Purpose and Functionality

The primary function of the **tour-builder agent** is to convert abstract graph data into a concrete, step-by-step educational experience. Rather than presenting users with an overwhelming map of files and dependencies, the agent curates a narrative path that emphasizes *what* the project does, *why* each component matters, and *how* the pieces interconnect.

This process begins with a raw graph representation of the codebase—complete with file nodes, dependency edges, and architectural layers—and culminates in a JSON array of tour steps. Each step includes metadata such as `order`, `title`, `description`, `nodeIds`, and optional `languageLesson` fields that provide contextual programming insights.

## The Two-Phase Workflow

The **tour-builder agent** operates through a structured two-phase pipeline that separates structural analysis from educational design.

### Phase 1: Graph-Topology Analysis

In the first phase, the agent generates and executes an analysis script (written in Node.js or Python) that computes critical structural metrics from the codebase graph. This script performs:

- **Fan-in/fan-out rankings** to identify highly connected components
- **Entry-point detection** to locate where execution begins
- **BFS (Breadth-First Search) traversals** to map dependency chains
- **Non-code file inventories** to surface configuration files, Dockerfiles, and CI/CD pipelines
- **Cluster analysis** to identify tightly-coupled modules
- **Layer summarization** to understand architectural boundaries

The script reads from [`.understand-anything/tmp/ua-tour-input.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/tmp/ua-tour-input.json) and writes its analysis to [`.understand-anything/tmp/ua-tour-results.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/tmp/ua-tour-results.json).

### Phase 2: Pedagogical Design

Using the structural signals from Phase 1, the agent constructs the actual learning sequence:

1. **Starting point selection**: Typically begins at [`README.md`](https://github.com/Lum1104/Understand-Anything/blob/main/README.md) or the top entry-point file
2. **Depth mapping**: Translates BFS traversal depth into sequential tour steps
3. **Non-code integration**: Inserts stops at infrastructure files (Dockerfile, CI/CD config, schema files) to explain deployment and configuration
4. **Cluster grouping**: Bundles related nodes to maintain narrative coherence
5. **Layer hierarchy adherence**: Follows architectural layers to build conceptual understanding progressively

## Input and Output Format

The **tour-builder agent** consumes a comprehensive graph JSON containing all nodes, edges, and layer definitions. It produces a standardized JSON array where each object represents a tour stop:

```json
{
  "order": 2,
  "title": "Application Entry Point",
  "description": "The main entry point bootstraps the application, importing core modules, setting up configuration, and starting the server. This file gives you a bird's-eye view of the runtime structure.",
  "nodeIds": ["file:src/index.ts"],
  "languageLesson": "TypeScript barrel files use `export * from` to re-export modules, creating a clean public API surface."
}

```

This structured output allows the Understand-Anything dashboard to render interactive tours with consistent formatting and educational context.

## Integration with the Understand-Anything System

The **tour-builder agent** is invoked as a sub-agent from the main `/understand` skill defined in [`skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/SKILL.md). The dispatch configuration passes the full graph context and references a specialized prompt template:

```yaml

# inside the /understand skill definition

dispatch:
  subagent:
    name: tour-builder            # ← invokes the tour-builder agent

    prompt: ./tour-builder-prompt.md   # prompt template that drives the agent

    context: |
      # Provide the full graph JSON (nodes, edges, layers)

      {{graphJson}}

```

The prompt template located at [`skills/understand/tour-builder-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/tour-builder-prompt.md) drives the agent's reasoning process, ensuring consistent pedagogical output across different codebases.

## Executing the Tour-Analysis Script

During operation, the agent generates a temporary analysis script that must be executed to process the graph topology. Run the generated script from the project root:

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

```

This execution writes the topology analysis to [`ua-tour-results.json`](https://github.com/Lum1104/Understand-Anything/blob/main/ua-tour-results.json), which the agent then consumes to craft the final pedagogical sequence.

## Summary

- The **tour-builder agent** converts raw codebase graphs into 5-15 step guided learning tours for newcomers.
- It operates in two distinct phases: **graph-topology analysis** (computing structural metrics via Node.js/Python scripts) and **pedagogical design** (curating educational narratives).
- Key inputs include graph JSON with nodes, edges, and layers; output is a structured JSON array of tour steps with metadata.
- The agent is dispatched from [`skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/SKILL.md) and defined in [`agents/tour-builder.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/tour-builder.md).
- Non-code files like Dockerfiles and CI/CD configurations are intentionally included as tour stops to explain infrastructure and deployment context.

## Frequently Asked Questions

### What is the tour-builder agent?

The **tour-builder agent** is an AI component within the Understand-Anything system that automatically generates guided learning tours from codebase graphs. It synthesizes 5-15 pedagogical steps that teach project architecture and key concepts in a logical sequence, making unfamiliar codebases approachable for new developers.

### How does the tour-builder agent select which files to include in a tour?

The agent uses **graph-topology analysis** to compute fan-in/fan-out rankings, identify entry points, and detect tightly-coupled clusters. It prioritizes highly connected components and follows BFS traversal patterns to ensure the tour covers architecturally significant files while maintaining a coherent narrative flow from entry points outward.

### What is the output format of the tour-builder agent?

The agent produces a JSON array where each element contains `order`, `title`, `description`, `nodeIds`, and an optional `languageLesson` field. This structured data is consumed by the Understand-Anything dashboard to render interactive, step-by-step learning experiences with embedded educational context.

### Where is the tour-builder agent defined in the Understand-Anything repository?

The agent's specification resides in [`agents/tour-builder.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/tour-builder.md), while its integration point is in [`skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/SKILL.md) at line 509. The prompt template that drives its behavior is located at [`skills/understand/tour-builder-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/tour-builder-prompt.md), and design documentation exists in [`docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md`](https://github.com/Lum1104/Understand-Anything/blob/main/docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md).