---
name: gen-code-tour
description: "Use when onboarding developers to an unfamiliar codebase, documenting a complex architectural flow across multiple files, or creating guided walkthroughs for code reviews. Generates VSCode CodeTour JSON files with progressive disclosure — starting from high-level architecture and drilling into implementation details. Domain: Documentation, Onboarding. Level: Intermediate. Tags: code-tour, onboarding, walkthrough, documentation, progressive-disclosure, vscode."
---

# Code Tour Generation

## Problem

New developers joining a project face a steep learning curve. Documentation describes
*what* the system does but rarely provides a guided path through *how* the code
implements it. Reading files in alphabetical order or random discovery leads to
fragmented understanding. Developers need a curated path through the codebase that
builds understanding progressively.

## When to Use

- A new developer is joining the team and needs to understand the architecture
- A complex feature spans 5+ files and benefits from a guided walkthrough
- A code review involves changes across multiple modules that reviewers need context for
- The project has a Clean Architecture or CQRS structure that newcomers find disorienting
- You want to document how a request flows from endpoint to database

**When NOT to use:**
- The codebase has fewer than 10 files — a README is sufficient
- You need API documentation — use the `technical-writer` agent instead
- The tour would be a single file — just add inline comments

## Instruction

Generate a VSCode CodeTour file (`.tours/{tour-name}.tour`) that guides the reader
through the codebase with progressive disclosure.

### Tour Structure

Every tour follows the **Concentric Circles** pattern — start at the outermost layer
(entry point, configuration) and spiral inward toward the core domain logic:

```
1. Entry point (Program.cs, endpoint, hub)
2. Configuration (DI registration, options)
3. Application layer (handler, pipeline)
4. Domain layer (entity, value object, domain service)
5. Infrastructure layer (repository, external service)
6. Cross-cutting (middleware, filters, interceptors)
```

### Step Types

| Step Type | Use | CodeTour Properties |
|---|---|---|
| **Directory** | Explain a folder's purpose and contents | `directory: "src/Domain/"` |
| **File** | Explain a file's role in the architecture | `file: "src/Domain/Order.cs"` |
| **Line** | Point to a specific code construct | `file` + `line` |
| **Selection** | Highlight a range of code | `file` + `selection` (start/end) |

### Step Content Guidelines

- **Title**: Short, descriptive — what this step teaches (not what the code does)
- **Description**: 2-4 sentences explaining the architectural significance
- **Progressive**: Each step builds on the previous one — never reference concepts not yet introduced
- **Actionable**: End each step with what to look for or understand before moving on

### Output Format

Generate a JSON file following the CodeTour schema:

```json
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "{Tour Title}",
  "description": "{One-sentence purpose of this tour}",
  "steps": [
    {
      "title": "Step 1: Entry Point",
      "description": "This is where requests enter the system...",
      "file": "src/WebApi/Program.cs",
      "line": 42
    },
    {
      "title": "Step 2: DI Registration",
      "description": "All services are registered here...",
      "directory": "src/WebApi/Extensions/"
    }
  ]
}
```

### Tour Categories

Generate tours for these standard scenarios:

| Category | Starting Point | Key Stops |
|---|---|---|
| **Architecture Overview** | Solution structure | Layer boundaries, dependency flow, key abstractions |
| **Request Flow** | Endpoint/Controller | Validation → Handler → Domain → Repository → Response |
| **Domain Model** | Aggregate root | Entities, value objects, domain events, invariants |
| **Testing Strategy** | Test project structure | Unit → Integration → test helpers, builders |
| **Configuration** | appsettings.json | Options classes, validation, DI wiring |

### Quality Gates

- Every tour must have ≥ 5 steps and ≤ 25 steps
- Every step must reference a real file/directory that exists in the project
- No two consecutive steps should be in the same file (vary the perspective)
- The first step must orient the reader (where are we, what will we learn)
- The last step must summarize what was learned and suggest next exploration

## Output Schema

1. The `.tour` JSON file content
2. Suggested file path: `.tours/{category}-{subject}.tour`
3. A summary of what the tour covers and its target audience

## See Also

- `scaffold-clean-arch` — Clean Architecture project structure (tour often follows this layout)
- `gen-copilot-instructions` — Documentation generation for AI context files