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

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 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, 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 and writes its analysis to .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 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:

{
  "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. The dispatch configuration passes the full graph context and references a specialized prompt template:

# 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 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:

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, 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 and defined in 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, while its integration point is in skills/understand/SKILL.md at line 509. The prompt template that drives its behavior is located at skills/understand/tour-builder-prompt.md, and design documentation exists in docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md.

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