[g-husam]

Adds a code-walkthrough skill that produces self-contained, local interactive HTML walkthroughs of this repository at the current checked out commit. This includes things like an architecture map with import wires, a guided tour, one flow per CLI command, deep-dive guides with code excerpts, a per-language table with an exported-hooks matrix, and findings.

It is just a skill with some templates to fill out.

Triggered by prompting "walk me through the code", or narrowed to one area, for example "walk me through rust bump". If you ask for multiple walkthroughs in the same session, they'll get added as tabs in the generated site.

All output goes in .walkthrough/ at the repo root, which is gitignored as a whole. Each walkthrough is a pair named after its scope (architecture.{json,html}, rust-bump.{json,html}, ...), so several can coexist, and every page has a "Walkthroughs" bar linking to the others.

Note: this skill takes some time to generate the site - up to 15 min depending on your model.

Main things to review

walkthrough prompt and the actual walkthrough output site itself.

Agent description

Details

How it works

render.go -init -out .walkthrough/<name>.json   skeleton: every package + doc synopsis
agent reads the code → .walkthrough/<name>.json layers, tour, flows, guides, findings
render.go -in .walkthrough/<name>.json          → .walkthrough/<name>.html: facts from go list + validation + template

<name> is architecture for a whole-codebase request, or the focus in kebab case (rust-bump, python-generate). The renderer refuses any -out outside .walkthrough/.

Authored by the agent (JSON)	Computed by the renderer
layer per package, tour, flows, guides, findings, table columns	packages, imports, non-test LOC, Go files, doc synopses, module, Go version, commit
cited paths via <a data-src="…">	existence of every cited path and package; cited allowlist for the page
	the list of sibling walkthroughs in .walkthrough/ for the "Walkthroughs" bar

.agents/skills/code-walkthrough/
├── SKILL.md              # workflow, output location, required sections, JSON reference
└── scripts/
    ├── render.go         # go list facts, validation, CSP pinning, HTML output, sibling links
    ├── render_test.go    # validate, merge, output directory, sibling links, -init → -check round-trip
    └── template.html     # repo-agnostic page, embedded into render.go

Nothing under .agents/ is matched by ./..., so the skill never affects CI builds.

Generating a walkthrough

From the repository root, in Jetski or any agent that loads .agents/skills/:

Walk me through the code.

or, equivalently, "Generate an interactive walkthrough of this repository."

The skill takes the skeleton from the renderer, reads the code, writes the narrative into .walkthrough/<name>.json, iterates until -check is clean, and surfaces .walkthrough/<name>.html (opens from file://, no server). Narrow it with a subject ("…of the release pipeline", "walk me through rust bump"), which sets focus and writes a separate pair. Asking for more on an existing walkthrough edits its JSON and re-renders it instead of starting a new pair.

Design points

• No hardcoding. The template has no repository names, package lists or table columns; SKILL.md tells the agent how to find each section in the checkout (CLI registration for flows, dispatch switch for the extension-point guides, -facts for import claims).
• Required content. A whole-architecture request must have flows, five named guide kinds and findings; -check exits non-zero while any warning remains. A single-subsystem request sets focus.
• One ignored output directory. Every file goes under .walkthrough/, and the renderer rejects any other -out, so no walkthrough name ever shows up in git status.
• Linked walkthroughs. Rendering a page lists every sibling page in .walkthrough/ and rewrites the list in the pages rendered earlier. Only their JSON data block changes, so their pinned CSP script hashes stay valid.
• Security. CSP script-src is the sha256 of the template's own script, computed at render time. Author markup keeps only data-src; script/resource elements are dropped with their subtrees, other tags unwrapped, all other attributes stripped. data-src is validated in every quoting/casing form, and the page drops any path the renderer did not validate. Sibling links are restricted to plain NAME.html file names, checked by both the renderer and the page.
• Links match the page. GitHub links use the commit SHA, not main; tabs, steps, guides and flows are deep-linkable (#guides/<id>/N).

Verification

• gofmt, goimports, go vet, golangci-lint and go test -race ./.agents/skills/code-walkthrough/scripts/ are clean.
• Regenerated the full walkthrough against main: 13 tour steps, 4 flows, 6 guides (incl. generation and sidekick pipelines), 9 languages × 7 columns, 19-row hooks matrix, 5 findings. Three stale claims from docs: add interactive walkthroughs and site generator #7771 were corrected rather than ported (dependency_test.go is gone; the swift annotator is annotate_model.go; counts removed from prose).
• Headless Chromium over the DevTools protocol drove every tab, step, flow stage, guide step, table row, source link, modal control, prompt button and keyboard shortcut on the generated page, a full-feature fixture and a hostile fixture (javascript: hrefs, img onerror, svg onload, iframe, base, form, </script> breakout, DOM clobbering), plus wire visibility by hit-testing, 800 px / 390 px layouts, AA contrast in both themes and deep links. 261/261 checks pass with no console errors, exceptions, CSP reports or navigations.
• Re-ran the review scenario ("walk me through the code", then "walk me through rust bump", then "walk me through python generate"), both as separate agents and in one session. Every file landed in .walkthrough/, git status stayed empty, git check-ignore attributes each file to .gitignore, and each page's "Walkthroughs" bar links to the others.

[gemini-code-assist]

Code Review

This pull request introduces a new walkthrough skill to generate interactive HTML architecture walkthroughs for the repository. It adds SKILL.md for documentation, template.html for the interactive UI, and render.go to handle Go package fact extraction and validation. The review feedback highlights a validation bug in render.go where the "other" layer is omitted during skeleton initialization, suggests strictly enforcing trailing slashes for directory citations, and recommends refactoring the link hydration logic in template.html to use DOM-based sanitization instead of a regular expression.

[noahdietz]

Personally I would put the dependency_test.go and CI change in a different PR unless it is strictly related to the skill primarily bc we share this codebase and if it produces a dev regression, it's easier to revert an isolated CL :) but LGTM otherwise

[g-husam]

@noahdietz done: dependency_test.go and the linter.yaml job are now their own PR, #7809, and this PR is stacked on it (base test/dependency-rules), so this diff is the skill only. Merge #7809 first.