diffity-tour

Diffity Tour Skill

You are creating a guided code tour — a narrated, step-by-step walkthrough of the codebase that answers the user's question or explains how a feature works. The tour opens in the browser with a sidebar showing the narrative and highlighted code sections.

Arguments

• question (required): The user's question, topic, concept, or a GitHub PR URL. Examples:
  • /diffity-tour how does authentication work?
  • /diffity-tour explain the request lifecycle
  • /diffity-tour how are comments stored and retrieved?
  • /diffity-tour closures
  • /diffity-tour React hooks
  • /diffity-tour walk me through this branch before I merge
  • /diffity-tour https://github.com/owner/repo/pull/123

When the argument is a GitHub PR URL (matching github.com/owner/repo/pull/N), the tour is automatically locked to Review mode — the PR's diff drives the scope, and the conclusion must include a PR-flags list. See the Review tours section below.

CLI Reference

{{binary}} agent tour-start --topic "<text>" [--body "<text>"] --json
{{binary}} agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json
{{binary}} agent tour-done --tour <id> --json
{{binary}} list --json

Prerequisites

1. Check that {{binary}} is available: run which {{binary}}. If not found, {{install_hint}}.
2. If the argument is a GitHub PR URL:
   • Check gh is installed and authenticated: run gh auth status. If not authenticated, stop and ask the user to run gh auth login.
   • Verify the current repo matches the PR's repo: run gh repo view --json nameWithOwner -q .nameWithOwner and confirm it matches the owner/repo in the URL. If it doesn't, stop and tell the user they need to be inside the PR's repository clone — diffity can't tour a PR for a repo you don't have checked out.
   • Start diffity against the PR: run {{binary}} --no-open <pr-url> using the Bash tool with run_in_background: true. The --no-open flag must come BEFORE the URL — commander's passThroughOptions() will slurp any flag that appears after the positional URL into the refs array, skipping PR handling and producing an "unknown ref" error. This command checks out the PR's branch locally and starts a diff-scoped session. Wait 2 seconds, then run {{binary}} list --json to get the port. You do not also need a tree instance — the diff session supports agent tour-* commands.
3. Otherwise, ensure a tree instance is running: run {{binary}} list --json.
   • If no instance is running, start one: run {{binary}} tree --no-open using the Bash tool with run_in_background: true, wait 2 seconds, then run {{binary}} list --json to get the port.