Files
skills/public/codetour-guided-walkthroughs.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

599 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>codetour-guided-walkthroughs</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/codetour-guided-walkthroughs.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/codetour-guided-walkthroughs">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/codetour-guided-walkthroughs.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>codetour-guided-walkthroughs</h1><p class="lede">Creating and following CodeTour walkthroughs for codebase understanding</p><h1>CodeTour Guided Walkthroughs</h1>
<p><strong>Scope</strong>: Creating interactive code tours and following existing tours for codebase understanding <strong>Lines</strong>: ~380 <strong>Last Updated</strong>: 2025-10-26 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Onboarding to an unfamiliar codebase</li><li>Creating documentation for complex features or architecture</li><li>Following existing CodeTour walkthroughs for context</li><li>Documenting multi-file workflows or data flows</li><li>Creating guided bug reproduction paths</li><li>Explaining refactoring changes to team members</li><li>Building interactive tutorials for framework usage</li><li>Capturing architectural decisions with code examples</li></ul>
<h2>Core Concepts</h2>
<h3>Tour Structure</h3>
<p><strong>Tour File Format</strong>:</p>
<ul><li>Extension: <code>.tour</code> (JSON format)</li><li>Location: <code>.tours/</code>, <code>.vscode/tours/</code>, <code>.github/tours/</code>, or project root</li><li>Schema: Defined by microsoft/codetour specification</li></ul>
<p><strong>Required Properties</strong>:</p>
<pre><code class="lang-json">{
&quot;title&quot;: &quot;Tour name&quot;,
&quot;steps&quot;: [
{
&quot;description&quot;: &quot;Step explanation (required)&quot;
}
]
}</code></pre>
<p><strong>Optional Properties</strong>:</p>
<ul><li><code>description</code>: Overall tour description</li><li><code>ref</code>: Git branch/commit/tag reference</li><li><code>isPrimary</code>: Boolean for primary tour flag</li><li><code>nextTour</code>: Title of follow-up tour for chaining</li></ul>
<h3>Step Types</h3>
<p><strong>File-Based Steps</strong>: Navigate to specific code locations</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/server.ts&quot;,
&quot;line&quot;: 42,
&quot;description&quot;: &quot;# Main Server Entry\n\nThis is where the HTTP server starts...&quot;
}</code></pre>
<p><strong>Directory Steps</strong>: Show overall structure</p>
<pre><code class="lang-json">{
&quot;directory&quot;: &quot;src/api/&quot;,
&quot;description&quot;: &quot;API handlers are organized by resource type&quot;
}</code></pre>
<p><strong>Content Steps</strong>: Provide context without code</p>
<pre><code class="lang-json">{
&quot;description&quot;: &quot;# Welcome to the API\n\nThis tour covers authentication flow&quot;
}</code></pre>
<p><strong>Pattern-Based Steps</strong>: Match code dynamically</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/auth.ts&quot;,
&quot;pattern&quot;: &quot;export class AuthService&quot;,
&quot;description&quot;: &quot;The AuthService handles all authentication logic&quot;
}</code></pre>
<h3>Selection Ranges</h3>
<p><strong>Highlight Code Blocks</strong>:</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/database.ts&quot;,
&quot;selection&quot;: {
&quot;start&quot;: {&quot;line&quot;: 10, &quot;character&quot;: 0},
&quot;end&quot;: {&quot;line&quot;: 20, &quot;character&quot;: 0}
},
&quot;description&quot;: &quot;Connection pool configuration&quot;
}</code></pre>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Create Basic Onboarding Tour</h3>
<pre><code class="lang-python">import json
from pathlib import Path
def create_onboarding_tour(output_path: str = &quot;.tours/getting-started.tour&quot;):
&quot;&quot;&quot;Create a basic onboarding tour for new developers.&quot;&quot;&quot;
tour = {
&quot;title&quot;: &quot;Getting Started with the Codebase&quot;,
&quot;description&quot;: &quot;A walkthrough of key files and architecture&quot;,
&quot;steps&quot;: [
{
&quot;description&quot;: &quot;# Welcome!\n\nThis tour will guide you through the main components of our application.&quot;
},
{
&quot;file&quot;: &quot;README.md&quot;,
&quot;line&quot;: 1,
&quot;description&quot;: &quot;Start by reading the README for setup instructions&quot;
},
{
&quot;directory&quot;: &quot;src/&quot;,
&quot;description&quot;: &quot;All source code lives in the `src/` directory&quot;
},
{
&quot;file&quot;: &quot;src/main.py&quot;,
&quot;pattern&quot;: &quot;def main\\(\\):&quot;,
&quot;description&quot;: &quot;# Application Entry Point\n\nThe main() function initializes and starts the application&quot;
}
]
}
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
with open(output_path, &#x27;w&#x27;) as f:
json.dump(tour, f, indent=2)
return output_path</code></pre>
<h3>Pattern 2: Architecture Deep-Dive Tour</h3>
<pre><code class="lang-python">def create_architecture_tour(component: str, files: list[dict]):
&quot;&quot;&quot;Create a tour explaining a specific architectural component.&quot;&quot;&quot;
tour = {
&quot;title&quot;: f&quot;{component} Architecture&quot;,
&quot;description&quot;: f&quot;Deep dive into {component} design and implementation&quot;,
&quot;steps&quot;: [
{
&quot;description&quot;: f&quot;# {component} Overview\n\nThis component handles...&quot;
}
]
}
# Add file-based steps
for file_info in files:
tour[&quot;steps&quot;].append({
&quot;file&quot;: file_info[&quot;path&quot;],
&quot;line&quot;: file_info.get(&quot;line&quot;),
&quot;selection&quot;: file_info.get(&quot;selection&quot;),
&quot;description&quot;: file_info[&quot;explanation&quot;]
})
return tour</code></pre>
<h3>Pattern 3: Follow Existing Tour Programmatically</h3>
<pre><code class="lang-python">import json
from pathlib import Path
from typing import Iterator
def read_tour(tour_path: str) -&gt; dict:
&quot;&quot;&quot;Load a tour file from disk.&quot;&quot;&quot;
with open(tour_path) as f:
return json.load(f)
def iterate_tour_steps(tour: dict) -&gt; Iterator[tuple[int, dict]]:
&quot;&quot;&quot;Iterate through tour steps with indices.&quot;&quot;&quot;
for idx, step in enumerate(tour[&quot;steps&quot;], 1):
yield idx, step
def follow_tour(tour_path: str):
&quot;&quot;&quot;Follow a tour and extract insights.&quot;&quot;&quot;
tour = read_tour(tour_path)
print(f&quot;Tour: {tour[&#x27;title&#x27;]}&quot;)
if desc := tour.get(&#x27;description&#x27;):
print(f&quot;Description: {desc}\n&quot;)
for step_num, step in iterate_tour_steps(tour):
print(f&quot;Step {step_num}:&quot;)
if file_path := step.get(&#x27;file&#x27;):
line = step.get(&#x27;line&#x27;, 1)
print(f&quot; File: {file_path}:{line}&quot;)
if directory := step.get(&#x27;directory&#x27;):
print(f&quot; Directory: {directory}&quot;)
print(f&quot; Description: {step[&#x27;description&#x27;][:100]}...\n&quot;)</code></pre>
<h3>Pattern 4: Feature Workflow Tour</h3>
<pre><code class="lang-python">def create_feature_tour(feature_name: str, workflow_steps: list[str]):
&quot;&quot;&quot;Create a tour showing how a feature works end-to-end.&quot;&quot;&quot;
tour = {
&quot;title&quot;: f&quot;{feature_name} - Complete Workflow&quot;,
&quot;description&quot;: f&quot;Follow data flow through {feature_name}&quot;,
&quot;steps&quot;: [
{
&quot;description&quot;: f&quot;# {feature_name} Flow\n\nTrace how data moves through the system&quot;
}
]
}
# Add workflow steps
step_descriptions = {
&quot;api&quot;: &quot;API endpoint receives request&quot;,
&quot;validation&quot;: &quot;Request validation and schema checking&quot;,
&quot;service&quot;: &quot;Business logic processing&quot;,
&quot;database&quot;: &quot;Data persistence&quot;,
&quot;response&quot;: &quot;Response formatting and return&quot;
}
for step_type in workflow_steps:
tour[&quot;steps&quot;].append({
&quot;file&quot;: f&quot;src/{step_type}.py&quot;,
&quot;description&quot;: f&quot;## {step_type.title()}\n\n{step_descriptions[step_type]}&quot;
})
return tour</code></pre>
<h3>Pattern 5: Bug Investigation Tour</h3>
<pre><code class="lang-python">def create_bug_tour(bug_id: str, reproduction_steps: list[dict]):
&quot;&quot;&quot;Document bug reproduction path for investigation.&quot;&quot;&quot;
tour = {
&quot;title&quot;: f&quot;Bug #{bug_id} - Investigation Guide&quot;,
&quot;description&quot;: &quot;Steps to reproduce and understand the issue&quot;,
&quot;ref&quot;: f&quot;bug-{bug_id}&quot;, # Link to bug fix branch
&quot;steps&quot;: []
}
for idx, step in enumerate(reproduction_steps, 1):
tour[&quot;steps&quot;].append({
&quot;file&quot;: step[&quot;file&quot;],
&quot;line&quot;: step.get(&quot;line&quot;),
&quot;description&quot;: f&quot;## Step {idx}: {step[&#x27;action&#x27;]}\n\n{step[&#x27;explanation&#x27;]}&quot;
})
# Add final step for the fix
tour[&quot;steps&quot;].append({
&quot;description&quot;: &quot;# The Fix\n\nSee the next tour for the solution...&quot;
&quot;nextTour&quot;: f&quot;Bug #{bug_id} - Solution&quot;
})
return tour</code></pre>
<h3>Pattern 6: Multi-File Refactoring Tour</h3>
<pre><code class="lang-python">def create_refactoring_tour(refactor_name: str, before_after: list[tuple]):
&quot;&quot;&quot;Document a refactoring with before/after comparisons.&quot;&quot;&quot;
tour = {
&quot;title&quot;: f&quot;Refactoring: {refactor_name}&quot;,
&quot;description&quot;: &quot;Understanding the changes and motivations&quot;,
&quot;steps&quot;: [
{
&quot;description&quot;: f&quot;# Refactoring: {refactor_name}\n\n## Goals\n- Improve readability\n- Reduce complexity\n- Enhance maintainability&quot;
}
]
}
for file_path, old_pattern, new_pattern, reason in before_after:
tour[&quot;steps&quot;].extend([
{
&quot;file&quot;: file_path,
&quot;pattern&quot;: old_pattern,
&quot;description&quot;: f&quot;## Before\n\nOld approach: {reason[&#x27;problem&#x27;]}&quot;
},
{
&quot;file&quot;: file_path,
&quot;pattern&quot;: new_pattern,
&quot;description&quot;: f&quot;## After\n\nNew approach: {reason[&#x27;solution&#x27;]}&quot;
}
])
return tour</code></pre>
<h3>Pattern 7: Find All Tours in Repository</h3>
<pre><code class="lang-python">from pathlib import Path
from typing import List
def discover_tours(repo_path: str = &quot;.&quot;) -&gt; List[Path]:
&quot;&quot;&quot;Find all CodeTour files in a repository.&quot;&quot;&quot;
search_paths = [
&quot;.tours/**/*.tour&quot;,
&quot;.vscode/tours/**/*.tour&quot;,
&quot;.github/tours/**/*.tour&quot;,
&quot;*.tour&quot;,
&quot;.vscode/*.tour&quot;
]
tours = []
repo = Path(repo_path)
for pattern in search_paths:
tours.extend(repo.glob(pattern))
return sorted(set(tours))
def list_available_tours(repo_path: str = &quot;.&quot;):
&quot;&quot;&quot;List all available tours with metadata.&quot;&quot;&quot;
tours = discover_tours(repo_path)
for tour_path in tours:
tour = read_tour(tour_path)
primary = &quot; [PRIMARY]&quot; if tour.get(&quot;isPrimary&quot;) else &quot;&quot;
print(f&quot;- {tour[&#x27;title&#x27;]}{primary}&quot;)
print(f&quot; Path: {tour_path}&quot;)
print(f&quot; Steps: {len(tour[&#x27;steps&#x27;])}&quot;)
if desc := tour.get(&#x27;description&#x27;):
print(f&quot; Description: {desc[:60]}...&quot;)
print()</code></pre>
<h3>Pattern 8: Validate Tour Structure</h3>
<pre><code class="lang-python">def validate_tour(tour: dict) -&gt; list[str]:
&quot;&quot;&quot;Validate tour structure and return errors.&quot;&quot;&quot;
errors = []
# Required fields
if &quot;title&quot; not in tour:
errors.append(&quot;Missing required field: title&quot;)
if &quot;steps&quot; not in tour:
errors.append(&quot;Missing required field: steps&quot;)
elif not isinstance(tour[&quot;steps&quot;], list):
errors.append(&quot;Field &#x27;steps&#x27; must be an array&quot;)
else:
# Validate each step
for idx, step in enumerate(tour[&quot;steps&quot;], 1):
if &quot;description&quot; not in step:
errors.append(f&quot;Step {idx}: Missing required field &#x27;description&#x27;&quot;)
# Check for conflicting fields
if &quot;file&quot; in step and &quot;directory&quot; in step:
errors.append(f&quot;Step {idx}: Cannot have both &#x27;file&#x27; and &#x27;directory&#x27;&quot;)
# Validate selection structure
if sel := step.get(&quot;selection&quot;):
if &quot;start&quot; not in sel or &quot;end&quot; not in sel:
errors.append(f&quot;Step {idx}: Selection must have &#x27;start&#x27; and &#x27;end&#x27;&quot;)
return errors</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Tour File Locations</h3>
<pre><code>Priority Order | Path
------------------------|-------------------------
Workspace tours | .tours/*.tour
VS Code tours | .vscode/tours/*.tour
GitHub tours | .github/tours/*.tour
Root tours | *.tour, .vscode/*.tour</code></pre>
<h3>Tour Object Schema</h3>
<pre><code class="lang-json">{
&quot;title&quot;: &quot;string (required)&quot;,
&quot;description&quot;: &quot;string (optional)&quot;,
&quot;ref&quot;: &quot;git reference (optional)&quot;,
&quot;isPrimary&quot;: &quot;boolean (optional)&quot;,
&quot;steps&quot;: [&quot;array (required)&quot;],
&quot;nextTour&quot;: &quot;string (optional)&quot;
}</code></pre>
<h3>Step Object Schema</h3>
<pre><code class="lang-json">{
&quot;description&quot;: &quot;string (required)&quot;,
&quot;file&quot;: &quot;string (optional)&quot;,
&quot;directory&quot;: &quot;string (optional)&quot;,
&quot;line&quot;: &quot;number (optional)&quot;,
&quot;pattern&quot;: &quot;regex string (optional)&quot;,
&quot;selection&quot;: {
&quot;start&quot;: {&quot;line&quot;: 0, &quot;character&quot;: 0},
&quot;end&quot;: {&quot;line&quot;: 10, &quot;character&quot;: 0}
},
&quot;title&quot;: &quot;string (optional)&quot;
}</code></pre>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: Use markdown in descriptions for rich formatting
✅ DO: Prefer pattern matching over hardcoded line numbers
✅ DO: Keep tours focused (8-12 steps ideal)
✅ DO: Chain related tours with nextTour
✅ DO: Test tours by following them manually
✅ DO: Update tours when code changes significantly
❌ DON&#x27;T: Create tours with 20+ steps (split into multiple)
❌ DON&#x27;T: Use absolute file paths (use workspace-relative)
❌ DON&#x27;T: Hardcode line numbers for frequently-changing code
❌ DON&#x27;T: Leave tours without clear descriptions
❌ DON&#x27;T: Mix unrelated topics in one tour</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<h3>Critical Violations</h3>
<p>❌ <strong>Hardcoded line numbers for volatile code</strong>:</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/api.ts&quot;,
&quot;line&quot;: 147, // This line number will change frequently
&quot;description&quot;: &quot;Authentication middleware&quot;
}</code></pre>
<p>✅ <strong>Use pattern matching</strong>:</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/api.ts&quot;,
&quot;pattern&quot;: &quot;export const authMiddleware&quot;,
&quot;description&quot;: &quot;Authentication middleware&quot;
}</code></pre>
<p>❌ <strong>Tours that are too long</strong>: 25-step tour covering entire codebase ✅ <strong>Split into focused tours</strong>: &quot;Authentication Tour&quot;, &quot;Database Tour&quot;, &quot;API Tour&quot;</p>
<p>❌ <strong>Missing context in descriptions</strong>:</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/utils.ts&quot;,
&quot;line&quot;: 50,
&quot;description&quot;: &quot;Helper function&quot; // Too vague
}</code></pre>
<p>✅ <strong>Rich, helpful descriptions</strong>:</p>
<pre><code class="lang-json">{
&quot;file&quot;: &quot;src/utils.ts&quot;,
&quot;pattern&quot;: &quot;export function parseConfig&quot;,
&quot;description&quot;: &quot;# Configuration Parser\n\nParses YAML config files and validates against schema. Returns typed config object or throws ValidationError.&quot;
}</code></pre>
<h3>Common Mistakes</h3>
<p>❌ <strong>Absolute file paths</strong>: <code>&quot;file&quot;: &quot;/Users/alice/project/src/main.py&quot;</code> ✅ <strong>Workspace-relative paths</strong>: <code>&quot;file&quot;: &quot;src/main.py&quot;</code></p>
<p>❌ <strong>Stale tours</strong>: Tours never updated as code evolves ✅ <strong>Maintained tours</strong>: Review and update quarterly or after major refactors</p>
<p>❌ <strong>No tour discovery</strong>: Tours hidden in random locations ✅ <strong>Standard locations</strong>: Use <code>.tours/</code> directory, mark primary tour with <code>isPrimary: true</code></p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>skill-repo-discovery.md</code> - Discovering codebase structure and patterns</li><li><code>skill-repo-planning.md</code> - Planning repository exploration strategies</li><li><code>skill-creation.md</code> - Creating documentation and knowledge artifacts</li><li><code>beads-workflow.md</code> - Tracking documentation work with Beads</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-26 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/codetour-guided-walkthroughs.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>