npm - kushi-agents - Versions diffs - 6.1.2 → 6.2.0 - Mend

kushi-agents 6.1.2 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (86) hide show

package/plugin/skills/skill-creator/generate-eval-review.ps1 ADDED Viewed

@@ -0,0 +1,101 @@
+<#
+.SYNOPSIS
+Renders an HTML side-by-side eval-review viewer for a skill.
+.DESCRIPTION
+Scans Evidence/_evals/ for the most recent per-run JSON files belonging to
+-Skill, picks the two newest (or up to -MaxRuns), and renders a static HTML page
+that shows per-case pass/fail + duration side-by-side. Output is gitignored.
+If no eval runs are found, emits a stub page noting "no runs yet — run
+`npm run eval -- <skill>` first" so the viewer command never silently fails.
+.PARAMETER Skill
+Skill name (matches plugin/skills/<name>/).
+.PARAMETER Output
+Override output path. Default: Evidence/_skill-creator/<skill>/review.html.
+.PARAMETER MaxRuns
+Maximum number of runs to include side-by-side (default 2).
+.PARAMETER Root
+Repo root (default: 3 levels above this script).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory=$true)][string]$Skill,
+    [string]$Output,
+    [int]$MaxRuns = 2,
+    [string]$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path
+)
+$ErrorActionPreference = 'Stop'
+if (-not $Output) {
+    $Output = Join-Path $Root "Evidence/_skill-creator/$Skill/review.html"
+}
+$outDir = Split-Path -Parent $Output
+New-Item -ItemType Directory -Force -Path $outDir | Out-Null
+$evalsDir = Join-Path $Root 'Evidence/_evals'
+$runs = @()
+if (Test-Path $evalsDir) {
+    $runs = Get-ChildItem -Path $evalsDir -Filter '*.json' -File -ErrorAction SilentlyContinue |
+        Sort-Object LastWriteTime -Descending |
+        Where-Object {
+            try {
+                $j = Get-Content -Raw $_.FullName | ConvertFrom-Json
+                $j.cases | Where-Object { $_.skill -eq $Skill -or $j.skill -eq $Skill }
+            } catch { $false }
+        } |
+        Select-Object -First $MaxRuns
+}
+function HtmlEncode { param([string]$s) [System.Net.WebUtility]::HtmlEncode([string]$s) }
+$sb = New-Object System.Text.StringBuilder
+[void]$sb.AppendLine('<!doctype html><html><head><meta charset="utf-8">')
+[void]$sb.AppendLine("<title>Skill review — $(HtmlEncode $Skill)</title>")
+[void]$sb.AppendLine('<style>body{font-family:system-ui,sans-serif;margin:2em;}table{border-collapse:collapse;width:100%;}th,td{border:1px solid #ccc;padding:.4em .6em;text-align:left;vertical-align:top;}.pass{background:#dfd}.fail{background:#fdd}.skip{background:#eee;color:#666}.meta{color:#666;font-size:.9em}code{background:#f4f4f4;padding:0 .2em}</style>')
+[void]$sb.AppendLine('</head><body>')
+[void]$sb.AppendLine("<h1>Skill review — <code>$(HtmlEncode $Skill)</code></h1>")
+[void]$sb.AppendLine("<p class='meta'>Generated $(Get-Date -Format o). Source: <code>Evidence/_evals/</code> (gitignored).</p>")
+if (-not $runs -or $runs.Count -eq 0) {
+    [void]$sb.AppendLine("<p><strong>No eval runs found for <code>$(HtmlEncode $Skill)</code>.</strong></p>")
+    [void]$sb.AppendLine("<p>Run <code>npm run eval -- $(HtmlEncode $Skill)</code> first, then re-render.</p>")
+} else {
+    [void]$sb.AppendLine('<table><thead><tr><th>Case</th>')
+    foreach ($r in $runs) { [void]$sb.AppendLine("<th>$(HtmlEncode $r.Name)</th>") }
+    [void]$sb.AppendLine('</tr></thead><tbody>')
+    # Build a unified case-id list across runs.
+    $parsed = $runs | ForEach-Object { Get-Content -Raw $_.FullName | ConvertFrom-Json }
+    $caseIds = @()
+    foreach ($p in $parsed) {
+        foreach ($c in $p.cases) { if ($caseIds -notcontains $c.id) { $caseIds += $c.id } }
+    }
+    foreach ($cid in $caseIds) {
+        [void]$sb.AppendLine("<tr><td><code>$(HtmlEncode $cid)</code></td>")
+        for ($i = 0; $i -lt $parsed.Count; $i++) {
+            $hit = $parsed[$i].cases | Where-Object { $_.id -eq $cid } | Select-Object -First 1
+            if (-not $hit) {
+                [void]$sb.AppendLine("<td class='skip'>—</td>")
+            } else {
+                $cls = if ($hit.skipped) { 'skip' } elseif ($hit.pass) { 'pass' } else { 'fail' }
+                $label = if ($hit.skipped) { 'skip' } elseif ($hit.pass) { 'pass' } else { 'fail' }
+                $dur = if ($hit.duration_ms) { "$($hit.duration_ms) ms" } else { '' }
+                [void]$sb.AppendLine("<td class='$cls'><strong>$label</strong> <span class='meta'>$dur</span></td>")
+            }
+        }
+        [void]$sb.AppendLine('</tr>')
+    }
+    [void]$sb.AppendLine('</tbody></table>')
+}
+[void]$sb.AppendLine('</body></html>')
+Set-Content -LiteralPath $Output -Value $sb.ToString() -Encoding UTF8
+Write-Host "skill-creator: wrote review viewer → $Output"
+exit 0

package/plugin/skills/skill-creator/optimize-description.ps1 ADDED Viewed

@@ -0,0 +1,87 @@
+<#
+.SYNOPSIS
+Rewrites a kushi skill description per the agentskills.io optimization rules.
+.DESCRIPTION
+Applies these transforms (idempotent):
+  1. Ensure the description leads with "USE WHEN " in the first 160 chars.
+  2. Ensure a "DO NOT USE" clause is present.
+  3. Strip marketing words: powerful, comprehensive, blazing, seamless, simple,
+     effortless, robust, cutting-edge, world-class.
+  4. Collapse internal whitespace; trim to 1024 chars.
+Prints a unified diff (current → rewritten) by default; -Quiet emits only the
+rewritten string for piping into scaffold.ps1.
+.PARAMETER Description
+The description string to rewrite.
+.PARAMETER Quiet
+Suppress the diff; print only the rewritten string.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory=$true)][string]$Description,
+    [switch]$Quiet
+)
+$ErrorActionPreference = 'Stop'
+function Optimize-Description {
+    param([string]$Text)
+    if (-not $Text) { return '' }
+    $out = $Text.Trim()
+    # 1) Marketing-word strip.
+    $bad = @('powerful', 'comprehensive', 'blazing', 'seamless', 'simple',
+             'effortless', 'robust', 'cutting-edge', 'world-class', 'next-generation')
+    foreach ($w in $bad) {
+        $out = [regex]::Replace($out, "\b$w\s*", '', 'IgnoreCase')
+    }
+    # 2) Collapse whitespace.
+    $out = [regex]::Replace($out, '\s+', ' ').Trim()
+    # 3) Ensure leading USE WHEN.
+    if ($out.Substring(0, [Math]::Min(160, $out.Length)) -notmatch '\bUSE WHEN\b') {
+        # If a plain "When " is present, upgrade it; else prepend a placeholder.
+        if ($out -match '^\s*[Ww]hen\b') {
+            $out = $out -replace '^\s*[Ww]hen\b', 'USE WHEN'
+        } else {
+            $out = "USE WHEN <TODO: trigger>. $out"
+        }
+    }
+    # 4) Ensure a DO NOT USE clause.
+    if ($out -notmatch '(?i)\bDO NOT USE\b') {
+        # Insert after the first sentence terminator if any.
+        if ($out -match '^(.+?\.)\s+(.+)$') {
+            $out = "$($Matches[1]) DO NOT USE FOR <TODO: near-miss>. $($Matches[2])"
+        } else {
+            $out = "$out DO NOT USE FOR <TODO: near-miss>."
+        }
+    }
+    # 5) Re-collapse whitespace after edits.
+    $out = [regex]::Replace($out, '\s+', ' ').Trim()
+    # 6) Hard cap 1024 chars.
+    if ($out.Length -gt 1024) { $out = $out.Substring(0, 1024) }
+    return $out
+}
+$rewritten = Optimize-Description -Text $Description
+if (-not $Quiet) {
+    Write-Host "--- before"
+    Write-Host $Description
+    Write-Host "+++ after"
+    Write-Host $rewritten
+    Write-Host ""
+}
+# Always emit the rewritten string on stdout (consumed by scaffold.ps1).
+[Console]::Out.Write($rewritten)
+exit 0

package/plugin/skills/skill-creator/scaffold.ps1 ADDED Viewed

@@ -0,0 +1,180 @@
+<#
+.SYNOPSIS
+skill-creator scaffold — emits a conformant plugin/skills/<name>/ tree.
+.DESCRIPTION
+Reads templates/skill-skeleton.template.md + evals-starter.template.json + (for
+pull/writer) gotchas-stub.template.md, substitutes {{NAME}}/{{DESCRIPTION}}/
+{{TYPE_SECTION}}, and writes the new skill folder. Adds a `.created-by-skill-
+creator` marker so D34.creator-output-conforms can enforce strict lint.
+Doctrine: plugin/instructions/skill-authoring.instructions.md.
+.PARAMETER Name
+Skill directory + front-matter name. Kebab-case, verb-led.
+.PARAMETER Type
+One of: pull, writer, orchestrator, other.
+  pull         → injects ## Gotchas section
+  writer       → injects ## Validation loop section
+  orchestrator → injects ## Step checklist section
+  other        → injects ## Steps (generic) — author must add at least one of
+                 Gotchas / Validation loop / Step checklist before lint passes.
+.PARAMETER Description
+Front-matter description string. Auto-rewritten via optimize-description.ps1.
+.PARAMETER Force
+Overwrite an existing skill folder.
+.PARAMETER DryRun
+Print actions only; write nothing.
+.PARAMETER Root
+Repo root (default: 3 levels above this script).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory=$true)][string]$Name,
+    [Parameter(Mandatory=$true)][ValidateSet('pull','writer','orchestrator','other')][string]$Type,
+    [Parameter(Mandatory=$true)][string]$Description,
+    [switch]$Force,
+    [switch]$DryRun,
+    [string]$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path
+)
+$ErrorActionPreference = 'Stop'
+if ($Name -notmatch '^[a-z][a-z0-9]*(-[a-z0-9]+)*$') {
+    throw "Name '$Name' is not kebab-case. Use lowercase letters, digits, and single hyphens (e.g. 'pull-onenote')."
+}
+$templatesDir = Join-Path $PSScriptRoot 'templates'
+$optimizer    = Join-Path $PSScriptRoot 'optimize-description.ps1'
+$skillDir     = Join-Path $Root "plugin/skills/$Name"
+$skillMd      = Join-Path $skillDir 'SKILL.md'
+$evalsDir     = Join-Path $skillDir 'evals'
+$evalsJson    = Join-Path $evalsDir 'evals.json'
+$marker       = Join-Path $skillDir '.created-by-skill-creator'
+if ((Test-Path $skillDir) -and -not $Force) {
+    throw "Skill folder already exists: $skillDir. Pass -Force to overwrite."
+}
+# 1) Optimize description (best-effort; falls back to as-is on error).
+$optimized = $Description
+if (Test-Path $optimizer) {
+    try {
+        $optimized = (& pwsh -NoProfile -File $optimizer -Description $Description -Quiet).Trim()
+        if (-not $optimized) { $optimized = $Description }
+    } catch {
+        Write-Warning "optimize-description failed: $($_.Exception.Message); using as-is."
+        $optimized = $Description
+    }
+}
+# Escape double quotes for safe YAML embedding.
+$escaped = $optimized -replace '"', '\"'
+# 2) Pick type-specific section.
+function Get-TypeSection {
+    param([string]$Type, [string]$TemplatesDir)
+    switch ($Type) {
+        'pull' {
+            $g = Join-Path $TemplatesDir 'gotchas-stub.template.md'
+            return (Get-Content -Raw $g)
+        }
+        'writer' {
+            return @'
+## Validation loop
+After writing outputs:
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.
+<!-- TODO(skill-creator): replace <area> with the targeted-scope substring for this skill. -->
+'@
+        }
+        'orchestrator' {
+            return @'
+## Step checklist
+- [ ] Step 1 — <!-- TODO(skill-creator): first concrete action -->
+- [ ] Step 2 — <!-- TODO(skill-creator): second concrete action -->
+- [ ] Step 3 — <!-- TODO(skill-creator): third concrete action -->
+- [ ] Final  — Run self-check + evals; only commit on green.
+'@
+        }
+        default {
+            return @'
+## Steps
+1. <!-- TODO(skill-creator): first step -->
+2. <!-- TODO(skill-creator): second step -->
+## Validation loop
+<!-- TODO(skill-creator): describe how to verify this skill ran correctly.
+     Every kushi skill SHOULD ship one of: Gotchas / Validation loop / Step checklist.
+     Replace this block with the right section for your skill, or keep it. -->
+1. Run `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`.
+2. Fix any findings, then re-run.
+'@
+        }
+    }
+}
+$typeSection = Get-TypeSection -Type $Type -TemplatesDir $templatesDir
+# 3) Render SKILL.md.
+$skeleton = Get-Content -Raw (Join-Path $templatesDir 'skill-skeleton.template.md')
+$skillContent = $skeleton `
+    -replace '\{\{NAME\}\}', $Name `
+    -replace '\{\{DESCRIPTION\}\}', $escaped `
+    -replace '\{\{TYPE_SECTION\}\}', [regex]::Escape($typeSection)
+# Undo escape (we used [regex]::Escape to preserve $ etc — restore literal).
+$skillContent = $skillContent -replace [regex]::Escape([regex]::Escape($typeSection)), $typeSection
+# Simpler approach: do the replacement once with literal substitution.
+$skillContent = $skeleton.Replace('{{NAME}}', $Name).Replace('{{DESCRIPTION}}', $escaped).Replace('{{TYPE_SECTION}}', $typeSection)
+# 4) Render evals/evals.json.
+$evalsTemplate = Get-Content -Raw (Join-Path $templatesDir 'evals-starter.template.json')
+$nameSlug = ($Name -replace '[^a-z0-9-]', '-')
+$evalsContent = $evalsTemplate.Replace('{{NAME}}', $Name).Replace('{{NAME_SLUG}}', $nameSlug)
+# 5) Write everything (or just print under -DryRun).
+$actions = @(
+    "mkdir  $skillDir",
+    "mkdir  $evalsDir",
+    "write  $skillMd ($(($skillContent -split "`n").Count) lines)",
+    "write  $evalsJson",
+    "write  $marker"
+)
+Write-Host ""
+Write-Host "skill-creator: scaffolding '$Name' (type=$Type) under $Root"
+foreach ($a in $actions) { Write-Host "  - $a" }
+Write-Host ""
+if ($DryRun) {
+    Write-Host "skill-creator: -DryRun set; no files written."
+    exit 0
+}
+if ((Test-Path $skillDir) -and $Force) {
+    Remove-Item -LiteralPath $skillDir -Recurse -Force
+}
+New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
+New-Item -ItemType Directory -Force -Path $evalsDir | Out-Null
+Set-Content -LiteralPath $skillMd -Value $skillContent -Encoding UTF8 -NoNewline
+Set-Content -LiteralPath $evalsJson -Value $evalsContent -Encoding UTF8 -NoNewline
+Set-Content -LiteralPath $marker -Value "Created by skill-creator on $(Get-Date -Format o).`nDelete this file only if the skill is intentionally non-conformant.`n" -Encoding UTF8
+Write-Host "skill-creator: done. Next steps:"
+Write-Host "  1. grep 'TODO(skill-creator)' $skillMd  — fill in placeholders"
+Write-Host "  2. pwsh plugin/skills/skill-checker/check-skill.ps1 -Skill $Name"
+Write-Host "  3. npm run eval -- $Name"
+Write-Host ""
+exit 0

package/plugin/skills/skill-creator/templates/evals-starter.template.json ADDED Viewed

@@ -0,0 +1,27 @@
+{
+  "skill": "{{NAME}}",
+  "version": "0.1.0",
+  "description": "Starter evals for {{NAME}}. Replace cases as soon as the skill has real behavior to assert.",
+  "cases": [
+    {
+      "id": "{{NAME_SLUG}}-skillmd-exists",
+      "name": "SKILL.md exists for {{NAME}}",
+      "input": "verify {{NAME}} skill artifacts",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/{{NAME}}/SKILL.md" }
+      ]
+    },
+    {
+      "id": "{{NAME_SLUG}}-description-optimized",
+      "name": "SKILL.md description leads with USE WHEN",
+      "input": "verify {{NAME}} description shape",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/{{NAME}}/SKILL.md", "value": "USE WHEN" }
+      ]
+    }
+  ]
+}

package/plugin/skills/skill-creator/templates/gotchas-stub.template.md ADDED Viewed

@@ -0,0 +1,9 @@
+## Gotchas
+<!-- TODO(skill-creator): top-5 failure modes. Each bullet starts with the concrete failure, then the correction. -->
+- **<failure mode 1>** → <correction>
+- **<failure mode 2>** → <correction>
+- **<failure mode 3>** → <correction>
+- **<failure mode 4>** → <correction>
+- **<failure mode 5>** → <correction>

package/plugin/skills/skill-creator/templates/skill-skeleton.template.md ADDED Viewed

@@ -0,0 +1,28 @@
+---
+name: "{{NAME}}"
+version: "0.1.0"
+description: "{{DESCRIPTION}}"
+---
+# Skill: {{NAME}}
+<!-- TODO(skill-creator): one-paragraph purpose. What does this skill DO, and when does it trigger? -->
+User triggers: <!-- TODO(skill-creator): list the literal user phrases / verbs that should route here. -->
+## USE WHEN
+- <!-- TODO(skill-creator): situational trigger 1 -->
+- <!-- TODO(skill-creator): situational trigger 2 -->
+## DO NOT USE FOR
+- <!-- TODO(skill-creator): the most likely near-miss invocation -->
+{{TYPE_SECTION}}
+## References
+- `plugin/instructions/skill-authoring.instructions.md`
+- `plugin/instructions/agentskills-compliance.instructions.md`
+<!-- TODO(skill-creator): add doctrine + reference pack links relevant to this skill. -->

package/plugin/skills/teach/.created-by-skill-creator ADDED Viewed

File without changes

package/plugin/skills/teach/SKILL.md ADDED Viewed

@@ -0,0 +1,79 @@
+---
+name: "teach"
+version: "1.0.0"
+description: "USE WHEN the user asks 'explain how kushi does X', 'why does refresh do Y', 'what is the difference between A and B in kushi', 'kushi explain <topic>', or wants to understand a kushi concept. DO NOT USE for modifying state/evidence (use build-state/refresh) or for project Q&A (use ask-project). Capability: pure pedagogical output — loads relevant doctrine + genealogy, explains concepts with cross-references, never modifies any State or Evidence."
+---
+# Skill: teach
+Pure pedagogical skill. Explains kushi concepts, architecture decisions, and operational patterns by loading relevant doctrine snippets, cross-references, and genealogy entries.
+## Triggers
+- "explain how kushi does X"
+- "why does refresh do Y"
+- "what's the difference between A and B in kushi"
+- `kushi explain <topic>` (CLI verb)
+- "how does kushi handle contradictions?"
+- "teach me about the CSC format"
+## Inputs
+- `<topic>` — free-text topic (fuzzy-matched to doctrine clusters below).
+## Topic → Doctrine mapping
+| Topic keyword(s) | Primary doctrine | Supporting files |
+|------------------|-----------------|-----------------|
+| contradictions, conflicts | `living-wiki.instructions.md` | `wiki-lint.instructions.md`, `State/_review-queue.md` format |
+| refresh, pull, sources | `refresh-project/SKILL.md` | `verbatim-by-default.instructions.md`, `parallel-execution.instructions.md` |
+| state, build-state, wiki | `living-wiki.instructions.md` | `karpathy-state-layout.instructions.md`, `log-format.instructions.md` |
+| hooks, events, webhooks | `hooks.instructions.md` | `Invoke-Hooks.ps1` |
+| parallel, workers, speed | `parallel-execution.instructions.md` | `auth-and-retry.instructions.md` |
+| otel, telemetry, tracing | `otel.instructions.md` | `Emit-OtelSpan.ps1` |
+| csc, capture, weekly | `comprehensive-structured-capture.instructions.md` | `weekly-csc.instructions.md` |
+| graph, entities, links | `entity-graph.instructions.md` | `link-entities/SKILL.md` |
+| workiq, m365 | `workiq-only.instructions.md` | `workiq-input-sanitization.instructions.md` |
+| schema, conventions, remember | `schema-evolve.instructions.md` | `karpathy-state-layout.instructions.md` |
+| global, global-wiki, cross-engagement | `global-wiki.instructions.md` | `multi-wiki-routing.instructions.md` |
+| routing, --global, --project-only, promote | `multi-wiki-routing.instructions.md` | `global-wiki.instructions.md` |
+| install, setup, hosts | `multi-host-install.instructions.md` | `host-portability.instructions.md` |
+| evals, testing | `skill-evals.instructions.md` | `skill-authoring.instructions.md` |
+## Procedure
+1. **Match topic** — fuzzy-match user's topic to doctrine cluster. If no match, list available topics with one-line descriptions.
+2. **Load doctrine** — read the primary doctrine file + first 20 lines of each supporting file.
+3. **Load genealogy** — find the release that introduced the feature in `docs/genealogy.md`.
+4. **Explain** — synthesize a clear explanation with:
+   - What it does (2-3 sentences)
+   - Why it exists (the problem it solved — from genealogy)
+   - How it works (key mechanics from doctrine)
+   - Where to look (file paths)
+   - Related concepts (cross-references)
+5. **Never modify** — this skill is read-only. No writes to State/, Evidence/, or any file.
+## Gotchas
+1. **Topic not found**: List available topics with `kushi explain --list`. Don't guess.
+2. **Too broad**: If topic matches multiple clusters, ask user to narrow down.
+3. **Version-specific**: Always note which version introduced the feature.
+4. **No project context needed**: teach operates on the kushi repo itself, not on engagement evidence.
+5. **Doctrine drift**: Always read the file live — don't cache doctrine content.
+## Validation loop
+After generating explanation:
+1. Verify all cited file paths exist (glob check).
+2. Verify genealogy entry referenced is real.
+3. If a path doesn't exist, remove the citation rather than citing a phantom file.
+## References
+- `release-genealogy.instructions.md` — genealogy format
+- `skill-authoring.instructions.md` — skill structure conventions
+- `docs/genealogy.md` — release lineage
+## Issue Recovery
+When this skill exposes a reusable defect (doctrine gap, missing cross-reference, stale genealogy), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.

package/plugin/skills/teach/evals/evals.json ADDED Viewed

@@ -0,0 +1,59 @@
+{
+  "skill": "teach",
+  "cases": [
+    {
+      "id": "teach-contradictions",
+      "name": "Explain contradictions handling",
+      "input": "kushi explain contradictions",
+      "expected_assertions": [
+        { "type": "contains", "value": "living-wiki" },
+        { "type": "contains", "value": "callout" },
+        { "type": "contains", "value": "_review-queue" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-parallel",
+      "name": "Explain parallel refresh",
+      "input": "explain how parallel pulls work in kushi",
+      "expected_assertions": [
+        { "type": "contains", "value": "parallel" },
+        { "type": "contains", "value": "worker" },
+        { "type": "contains", "value": "max_workers" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-unknown-topic",
+      "name": "Unknown topic suggests alternatives",
+      "input": "kushi explain quantum-entanglement",
+      "expected_assertions": [
+        { "type": "not_contains", "value": "quantum" },
+        { "type": "contains", "value": "available" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-global-wiki",
+      "name": "Explain global wiki",
+      "input": "kushi explain global-wiki",
+      "expected_assertions": [
+        { "type": "contains", "value": "global" },
+        { "type": "contains", "value": "scope" },
+        { "type": "contains", "value": "promote" }
+      ],
+      "grader_type": "script"
+    },
+    {
+      "id": "teach-multi-wiki-routing",
+      "name": "Explain multi-wiki routing flags",
+      "input": "kushi explain routing",
+      "expected_assertions": [
+        { "type": "contains", "value": "--global" },
+        { "type": "contains", "value": "--project-only" },
+        { "type": "contains", "value": "project-first" }
+      ],
+      "grader_type": "script"
+    }
+  ]
+}

package/plugin/skills/tour/SKILL.md ADDED Viewed

@@ -0,0 +1,85 @@
+---
+name: "tour"
+version: "1.0.0"
+description: "USE WHEN refresh-project / bootstrap-project completes AND a graph exists, OR the user says \"@Kushi tour <X>\", \"give me the week-in-review for <X>\", \"what should I look at first in <X>?\". DO NOT USE before link-entities has run. Capability: renders <project>/State/tour.md, an auto-generated week-in-review walkthrough. Scores nodes by recency_weight × cross_ref_count; DFS-walks edges in priority order; default top-N = 10."
+---
+# Skill: tour
+> **v5.0.0 — Guided tour producer.** See
+> `..\..\instructions\guided-tour.instructions.md` for the scoring formula,
+> the DFS ordering, the per-stop markdown shape, and the self-check rules.
+## When to run
+- Automatically as part of `refresh-project` (after `link-entities` +
+  `build-state` + `dashboard`) and `bootstrap-project` (same chain).
+- Manually: `@Kushi tour <project> [--top N]`.
+## Inputs
+- `<project>` — already-bootstrapped project root.
+- `<project>/Evidence/_graph/project-graph.json` — REQUIRED.
+- `<project>/State/index.md` — OPTIONAL; used to resolve `[[wikilinks]]` to
+  related State pages per stop.
+## Output
+- `<project>/State/tour.md`.
+## Steps
+## Step checklist
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+- [ ] Step 1 — Verify inputs
+- [ ] Step 2 — Run the builder
+### Step 1 — Verify inputs
+If `<project>/Evidence/_graph/project-graph.json` does not exist, exit with
+"no graph — run `link-entities` first" and do NOT write `State/tour.md`.
+### Step 2 — Run the builder
+```pwsh
+pwsh plugin/skills/tour/build-tour.ps1 -ProjectRoot <project> [-TopN <int>]
+```
+`build-tour.ps1` reads the graph, scores nodes, DFS-walks, and writes
+`State/tour.md`.
+## Hard rules
+- Idempotent — fully regenerated each run.
+- Citations MUST resolve on disk (self-check D23.tour enforces this).
+- NEVER write outside `<project>/State/tour.md`.
+## Triggers
+- "tour `<X>`"
+- "build tour for `<X>`"
+- "@Kushi tour `<X>`"
+- (auto) end of `refresh-project` / `bootstrap-project`
+## References
+- `..\..\instructions\guided-tour.instructions.md`
+- `..\..\instructions\entity-graph.instructions.md`
+- `..\..\instructions\karpathy-state-layout.instructions.md`
+- `..\..\instructions\issue-recovery.instructions.md`
+## Changelog
+- **v1.0.0 (kushi v5.0.0, 2026-05-26)**: initial release.
+## Validation loop
+After writing outputs:
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted tour`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.