.tours/

scripts/

• scripts/validate_tour.py

  — run after writing any tour. Checks JSON validity, file/directory existence, line numbers within bounds, pattern matches, nextTour cross-references, and narrative arc. Run it:

  python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

• scripts/generate_from_docs.py

  — when the user asks to generate from README/docs, run this first to extract a skeleton, then fill it in. Run it:

  python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

• references/codetour-schema.json

  — the authoritative JSON schema. Read it to verify any field name or type. Every field you use must conform to it.

• references/examples.md

  — 8 real-world CodeTour tours from production repos with annotated techniques. Read it when you want to see how a specific feature (

  commands

  ,

  selection

  ,

  view

  ,

  pattern

  ,

  isPrimary

  , multi-tour series) is used in practice.

• List the root directory, read the README, and check key config files (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
• Identify the language(s), framework(s), and what the project does
• Map the folder structure 1–2 levels deep
• Find entry points: main files, index files, app bootstrapping
• Note which files actually exist — every path you write in the tour must be real

[TODO: ...]

python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

1. Read entry points and the README first
2. Build a mental model of the top 5–7 modules
3. For the requested persona, identify the 2–3 modules that matter most and read those deeply
4. For modules you're not covering, mention them in the intro step as "out of scope for this tour"
5. Use

   directory

   steps for areas you mapped but didn't read — they orient without requiring full knowledge

uri

ref

uri

ref

isPrimary

• "bug tour" but no bug described → ask for the bug description
• "feature tour" but no feature named → ask which feature
• "specific files" explicitly requested → honor them as required stops

nextTour

commands

when

stepMarker

1. Set

   "ref"

   to the PR's branch name
2. Open with a

   uri

   step pointing to the PR itself — this gives the reviewer the full diff context
3. Add a

   uri

   step for any related issue or RFC if linked in the PR description
4. Cover changed files first — what changed and why
5. Then add steps for files not in the diff that reviewers must understand to evaluate the change correctly (call sites, dependency files, tests)
6. Flag invariants the change must preserve
7. Close with a reviewer checklist: what to verify, what tests to run, what to watch out for

[
  { "uri": "https://github.com/org/repo/pull/456",
    "title": "The PR", "description": "This PR refactors auth to use refresh tokens. Key concern: session invalidation during migration." },
  { "file": "src/auth/tokenService.ts", "line": 12, "title": "What Changed: Token Issuing", "description": "..." },
  { "file": "src/auth/middleware.ts", "line": 38, "title": "Unchanged But Critical", "description": "This file wasn't touched but depends on the token shape. Verify line 38 still matches." },
  { "title": "Reviewer Checklist", "description": "- [ ] Session invalidation tested?\n- [ ] Old tokens still rejected after migration?\n- [ ] Refresh token rotation tested?" }
]

1. Read the file
2. Find the exact line of the code you want to highlight
3. Understand it well enough to explain it to the target persona

{ "title": "Welcome", "description": "markdown..." }

{ "directory": "src/services", "title": "Service Layer", "description": "..." }

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "..." }

Path rule — always relative to repo root.

"file"

and

"directory"

values must be relative to the repository root (the directory that contains

.tours/

). Never use an absolute path (

/Users/...

) and never use a leading

./

. If the repo root is

/projects/myapp

and the file is at

/projects/myapp/src/auth.ts

, write

"src/auth.ts"

— not

./src/auth.ts

, not

/projects/myapp/src/auth.ts

, not

auth.ts

(unless it's actually at the root).

{
  "file": "src/core/pipeline.py",
  "selection": { "start": { "line": 15, "character": 0 }, "end": { "line": 34, "character": 0 } },
  "title": "The Request Pipeline",
  "description": "..."
}

{ "file": "src/app.ts", "pattern": "export default class Application", "title": "...", "description": "..." }

{
  "uri": "https://github.com/org/repo/pull/456",
  "title": "The PR That Introduced This Pattern",
  "description": "This design was debated in PR #456. The key tradeoff was..."
}

{ "file": "src/server.ts", "line": 1, "view": "terminal", "title": "...", "description": "..." }

{
  "file": "src/server.ts", "line": 1,
  "title": "Run It",
  "description": "Hit the play button — you'll see the server boot sequence here.",
  "commands": ["workbench.action.terminal.focus"]
}

editor.action.goToDeclaration

editor.action.showHover

references-view.findReferences

workbench.action.terminal.focus

workbench.action.tasks.runTask

workbench.view.scm

workbench.view.explorer

"This is the authentication middleware. It checks if the user is authenticated before allowing access to protected routes."

S: Every HTTP request passes through this file before reaching any controller — it's the sole auth checkpoint.

M: Notice the dual-check pattern on line 42: it validates the JWT signature and does a Redis lookup for the session. Both must pass. A valid JWT alone isn't enough if the session was revoked (logout, password reset, force-expire).

I: For a bug fixer: if a user reports being logged out unexpectedly, this is your first stop. Redis miss → 401 → silent logout is the most common failure path.

G: If Redis is down, line 53 propagates the error as a 401 — meaning a Redis outage silently logs everyone out. There's no circuit breaker here. This is tracked in ISSUE-4421, and the workaround is in

config/redis.ts

line 18.

1. Orientation — must be a

   file

   or

   directory

   step, never content-only. Use

   "file": "README.md", "line": 1

   or

   "directory": "src"

   and put your welcome text in the description. A content-only first step (no

   file

   ,

   directory

   , or

   uri

   ) renders as a blank page in VS Code CodeTour — this is a known VS Code extension behaviour, not configurable.
2. High-level map (1–3 directory or uri steps) — major modules and how they relate. Not every folder — just what this persona needs to know.
3. Core path (file/line, selection, pattern, uri steps) — the specific code that matters. This is the heart of the tour. Read and narrate. Don't skim.
4. Closing (content) — what the reader now understands, what they can do next, 2–3 suggested follow-up tours. If

   nextTour

   is set, reference it by name here.

"In this tour we covered the entry point, the middleware stack, and the database layer."

"You now know enough to safely add a new route without breaking auth or session handling. The danger zones to stay away from are

src/auth/tokenService.ts

(don't change the token shape without a migration plan) and

src/db/pool.ts

(connection limits are load-tested at current values).

What's next:

• If you're fixing a bug → jump to the Bug Fixer: Payment Flow tour for the specific path
• If you're adding a feature → the Feature Explainer: Notifications tour shows the full pattern
• If something's on fire → the RCA: Incident Guide tour maps the observability anchors"

nextTour

• A clear escalation path (broad → narrow, orientation → deep-dive)
• No duplicate steps between tours
• Each tour standalone enough to be useful on its own

1. "Orientation" → repo structure, how to run it (isPrimary: true)
2. "Core Request Flow" → entry to response, middleware chain
3. "Data Layer" → models, migrations, query patterns
4. "Testing Patterns" → how to write and run tests

1. "Happy Path" → normal flow from trigger to response
2. "Failure Modes" → where it can break and why
3. "Observability Map" → logs, metrics, traces to look at

1. "Module Boundaries" → what lives where and why
2. "Extension Points" → where to add new features
3. "Danger Zones" → what must never be changed carelessly

nextTour

title

• The main entry point — every persona needs to see this
• The central router or dispatcher — where requests branch
• The primary config loader — where behavior is controlled
• The auth boundary — the single place permissions are checked

• Every

  file

  path is relative to the repo root (no leading

  /

  or

  ./

  )
• Every

  file

  path read and confirmed to exist
• Every

  line

  number verified by reading the file (not guessed)
• Every

  directory

  is relative to the repo root and confirmed to exist
• Every

  pattern

  regex would match a real line in the file
• Every

  uri

  is a complete, real URL (https://...)

• ref

  is a real branch/tag/commit if set

• nextTour

  exactly matches the

  title

  of another

  .tour

  file if set
• Only

  .tour

  JSON files created — no source code touched
• First step has a

  file

  or

  directory

  anchor (content-only first step = blank page in VS Code)
• Tour ends with a closing content step that tells the reader what they can do next
• Every description answers SMIG — Situation, Mechanism, Implication, Gotcha
• Persona's priorities drive step selection (cut everything that doesn't serve their goal)
• Step count matches requested depth and repo size (see calibration table)
• At most 2 content-only steps (intro + closing)
• All fields conform to

  references/codetour-schema.json

python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

• JSON validity
• Every

  file

  path exists and every

  line

  is within file bounds
• Every

  directory

  exists
• Every

  pattern

  regex compiles and matches at least one line in the file
• Every

  uri

  starts with

  https://

• nextTour

  matches an existing tour title in

  .tours/

• Content-only step count (warns if > 2)
• Narrative arc (warns if no orientation or closing step)

• Content-only first step — step 1 has no

  file

  ,

  directory

  , or

  uri

  . VS Code opens to a blank page. Fix: anchor step 1 to a file or directory and put the intro text in its description.
• File path not relative to repo root — absolute paths or

  ./

  -prefixed paths silently fail to open. Fix: always use paths relative to where

  .tours/

  lives (e.g.

  src/auth.ts

  , not

  ./src/auth.ts

  ).
• Line number out of bounds — VS Code opens the file but scrolls nowhere. The validator catches this.

\n

1. Confirm step 1 has a

   file

   or

   directory

   field
2. Confirm every

   file

   path exists by reading it (relative to repo root, no leading

   ./

   )
3. Confirm every

   line

   is within the file's line count
4. Confirm every

   directory

   exists
5. Read the step titles in sequence — do they tell a coherent story?
6. Confirm

   nextTour

   matches another tour's

   title

   exactly

isPrimary: true

.vscode/settings.json

{ "codetour.promptForPrimaryTour": true }

isPrimary: true

ref

"ref": "main"

ref

.tours/

https://vscode.dev/github.com/<owner>/<repo>

.tours/

• File path (

  .tours/<name>.tour

  )
• One-paragraph summary of what the tour covers and who it's for
• The

  vscode.dev

  URL if the repo is public (so they can share it immediately)
• 2–3 suggested follow-up tours (or the next tour in the series if one was planned)
• Any user-requested files that didn't exist (be explicit — don't quietly substitute)