@erclx/aitk 3.15.0 → 3.17.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/bash-script/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bash-script
-description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked to write an interactive or human-facing bash or shell script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `cli-script`.
+description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked for "a human-facing shell tool", an interactive bash script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `cli-script`.
 ---
 
 # Bash script

package/claude/skills/ci-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci-workflow
-description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to write a CI workflow, add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to "write a CI workflow", add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
 ---
 
 # CI workflow

package/claude/skills/cli-script/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli-script
-description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for an automation script, a CI or cron script, a pipeline helper, or a non-interactive shell script. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
+description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for "a non-interactive shell script", an automation script, a CI or cron script, or a pipeline helper. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
 ---
 
 # CLI script

package/claude/skills/create-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-skill
-description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to create a skill, add a skill, or make a new skill.
+description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
 disable-model-invocation: true
 ---
 

package/claude/skills/create-snippet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-snippet
-description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to create a snippet, add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
+description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to "create a snippet", add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
 ---
 
 # Create snippet

package/claude/skills/create-standard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-standard
-description: Creates a new standard file in `standards/`. Use when asked to create a standard, add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+description: Creates a new standard file in `standards/`. Use when asked to "create a standard", add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
 ---
 
 # Create standard

package/claude/skills/decision-escalate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: decision-escalate
-description: Collects every open decision whose answer turns on the operator's preference, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
+description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
 disable-model-invocation: true
 ---
 

package/claude/skills/git-branch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-branch
-description: Generates and validates conventional branch names. Use for any branch naming or renaming.
+description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
 ---
 
 # Git branch

package/claude/skills/git-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-pr
-description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update.
+description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update, such as when asked to "open a pull request".
 ---
 
 # Git PR

package/claude/skills/git-stage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-stage
-description: Groups staged files by concern and generates one conventional commit per group. Use when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
+description: Groups staged files by concern and generates one conventional commit per group. Use when asked to "group these changes into commits", or when staged changes span multiple concerns and need to ship as separate commits. Do NOT use on a single-concern staged set. That is `git-commit`, which also preserves a hunk-level selection this skill's unstage and restage over whole files would widen.
 ---
 
 # Git stage

package/claude/skills/youtube-transcripts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: youtube-transcripts
-description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `aitk transcripts`. Use when the user pastes a YouTube URL and asks to grab the transcript, pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
+description: Fetches a YouTube video transcript with metadata frontmatter into the current repo via `aitk transcripts`. Use when the user pastes a YouTube URL and asks to "grab the transcript", pull captions, or save a transcript for context. Do NOT use for downloading the video file, summarizing a transcript that already exists, or non-YouTube links.
 ---
 
 # YouTube transcripts

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Eighteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Nineteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
 The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
 
-Fifteen of the eighteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads three such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
+Sixteen of the nineteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads three such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 
@@ -57,7 +57,7 @@ The verdict is published as a field as well as an exit code. A reader branching
 
 A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
 
-Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora and the citation reach check for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
+Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. Several tracked audits override that default too, wherever the corpus not being there is the ordinary state of a target rather than a broken checkout: the secret scan for a project that publishes nothing, the skill corpora, the citation reach check, and the routing measure for a project holding no skills tree, and the context audit for a project that adopted none of the folders it measures.
 
 Everything else stays `unmeasured`. That covers a tree git cannot list, which is a broken checkout, and a package declaring no `files` field, where a publish would pack the whole tree and the scan read none of it. Both are a corpus that exists and went unread, so softening either would report a pass over a shipped tree nobody measured.
 

package/docs/agents/commands.md

@@ -37,6 +37,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                          |
 | `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                            |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                   |
+| `aitk records migrate`     | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                 |
 | `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                   |
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                     |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                        |
@@ -47,6 +48,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                 |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
 | `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                    |
+| `aitk claude skills rank`  | Score the shipped catalog's descriptions against a hand-authored case corpus by TF-IDF cosine similarity, reporting rank-one and top-three     |
 | `aitk claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
@@ -66,27 +68,27 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                                                            |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                 |
-| `snippets`  | `list`, `install`, `sync`, `create`                                                                                    |
-| `standards` | `list`, `<name>`                                                                                                       |
-| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                |
-| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |
-| `demo`      | `compile`, `run`                                                                                                       |
-| `wiki`      | `init`                                                                                                                 |
-| `design`    | `render`                                                                                                               |
-| `slides`    | `render`, `list`                                                                                                       |
-| `tasks`     | `archive`, `validate`                                                                                                  |
-| `intake`    | `list`, `answer`                                                                                                       |
-| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                 |
-| `comments`  | `scan`                                                                                                                 |
-| `context`   | `audit`                                                                                                                |
-| `markdown`  | `audit`                                                                                                                |
-| `secrets`   | `scan`                                                                                                                 |
-| `deps`      | `audit`                                                                                                                |
-| `labels`    | `audit`                                                                                                                |
-| `audits`    | `run`, `list`                                                                                                          |
+| Domain      | Subcommands                                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                                                                |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                                                                   |
+| `standards` | `list`, `<name>`                                                                                                                      |
+| `gov`       | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded`                                                               |
+| `claude`    | `init`, `sync`, `routing`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `skills rank`, `setup [dest]` |
+| `demo`      | `compile`, `run`                                                                                                                      |
+| `wiki`      | `init`                                                                                                                                |
+| `design`    | `render`                                                                                                                              |
+| `slides`    | `render`, `list`                                                                                                                      |
+| `tasks`     | `archive`, `validate`                                                                                                                 |
+| `intake`    | `list`, `answer`                                                                                                                      |
+| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                                |
+| `comments`  | `scan`                                                                                                                                |
+| `context`   | `audit`                                                                                                                               |
+| `markdown`  | `audit`                                                                                                                               |
+| `secrets`   | `scan`                                                                                                                                |
+| `deps`      | `audit`                                                                                                                               |
+| `labels`    | `audit`                                                                                                                               |
+| `audits`    | `run`, `list`                                                                                                                         |
 
 Common patterns:
 

package/docs/agents/index.md

@@ -24,7 +24,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -72,6 +72,28 @@ aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)
 
 For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, `.claude/standards/intake.md`, `.claude/standards/memory.md`, and `.claude/standards/standard.md`.
 
+## Migrate
+
+`aitk records migrate <kind>` rewrites the records a `validate` finding names a transform for. A standard that redefines its own required frontmatter breaks every record already written to the old shape, and this is the repair `validate` could only report until now.
+
+```bash
+aitk records migrate memory
+aitk records migrate memory --write
+aitk records migrate memory --json
+```
+
+| Option          | Behavior                                                            |
+| --------------- | ------------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                             |
+| `--write`       | Rewrite every record a transform can repair                         |
+| `--root <path>` | Project root, defaulting to the main worktree except on `standards` |
+
+It writes nothing until `--write` is passed, matching the write-flag contract `aitk tooling sync` carries: a session record has no history to undo a wrong repair from, so naming a kind is not consent to rewrite every record inside it. A dry run reports which records it would touch and exits non-zero either way, headless or not, since there is nothing to prompt for.
+
+A transform runs only where the missing value is recoverable from the file itself. The one shipped today repairs a memory record missing `category` alone, deriving it from the same filename prefix `checkMemory` already reads it from. `title` and `description` are prose nobody wrote down, so a finding naming either carries no transform and stays for a session to fix by hand, and `validate` keeps reporting it. The transform re-reads the file rather than trusting a value captured at validate time, so a check and its repair cannot disagree about the same record.
+
+Exit codes: `0` nothing carried a known transform, or `--write` repaired everything it found. `1` refused for a reason `validate` shares, every candidate it found failed to repair, or `--write` repaired only some of them. `2` a record carries a known transform and `--write` was not passed.
+
 ## Size
 
 `aitk records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus `.claude/.tmp`, and it gates nothing.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/audits/catalog.ts

@@ -1,4 +1,5 @@
 import type { SkillsAuditRefusal } from '@/claude/skills-audit'
+import type { RankRefusal } from '@/claude/skills-rank'
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { ContextAuditRefusal } from '@/context/audit'
 import type { AuditRefusal } from '@/deps/audit'
@@ -306,6 +307,24 @@ function reachCounts(record: unknown): Record<string, number> | undefined {
   return allOf({ unqualifiedCitations: lengthOf(root.unqualified) })
 }
 
+/**
+ * Reads the routing measure's miss and unmeasurable counts, leaving `rank1`
+ * and `top3` out. Both move in lockstep with `misses` over a fixed-size
+ * corpus, so carrying them would report one movement three times, the same
+ * reasoning `restatedCounts` already takes over its own pair of derived
+ * totals. `unmeasurable` is retained separately, since it counts a defect in
+ * the instrument rather than a collision the catalog itself carries.
+ */
+function rankCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  return allOf({
+    misses: lengthOf(root.misses),
+    unmeasurable: lengthOf(root.unmeasurable),
+  })
+}
+
 function boardCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -518,6 +537,22 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-skills'] satisfies ReachRefusal[],
     counts: reachCounts,
   },
+  {
+    id: 'skills-rank',
+    label: 'Skill routing measure',
+    argv: ['claude', 'skills', 'rank', '--json'],
+    // Reports rather than gates. The corpus is a first run with no baseline to
+    // fail a push against, and a lexical ranker bounds a necessary condition
+    // rather than reporting real routing behavior, so a push failing on a
+    // moved rank would teach a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying no `claude/skills/` has
+    // adopted no skill convention this audit reads.
+    absentReasons: ['no-skills'] satisfies RankRefusal[],
+    counts: rankCounts,
+  },
   {
     id: 'tasks',
     label: 'Task board',

package/src/claude/cases/all.ts

@@ -0,0 +1,24 @@
+import type { SkillCase } from '@/claude/skills-rank'
+import { AUTHORING_CASES } from '@/claude/cases/authoring'
+import { CLAUDE_WORKFLOW_CASES } from '@/claude/cases/claude-workflow'
+import { GIT_CASES } from '@/claude/cases/git'
+import { MISC_CASES } from '@/claude/cases/misc'
+import { SETUP_CASES } from '@/claude/cases/setup'
+
+/**
+ * The full routing case corpus, one file per domain so a description change
+ * in one family touches only the file beside it.
+ *
+ * Bootstrapped from each skill's own quoted trigger phrases and then
+ * rephrased and supplemented rather than shipped verbatim, since a positive
+ * lifted unchanged from a trigger passes by construction and never tests a
+ * person's own words. See `.claude/groundwork/42-ai-blueprint/08-spikes.md`
+ * for the extraction arm this corpus replaces as the shipped measure.
+ */
+export const SKILL_CASES: readonly SkillCase[] = [
+  ...CLAUDE_WORKFLOW_CASES,
+  ...GIT_CASES,
+  ...SETUP_CASES,
+  ...AUTHORING_CASES,
+  ...MISC_CASES,
+]

package/src/claude/cases/authoring.ts

@@ -0,0 +1,53 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * Script, skill, snippet, standard, and doc authoring, plus the two prose
+ * skills that revise rather than generate.
+ */
+export const AUTHORING_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'I need a shell tool with prompts and a nice terminal UI for people to run by hand.',
+    expect: 'bash-script',
+  },
+  {
+    prompt:
+      'Wire up a GitHub Actions pipeline with parallel jobs for this repo.',
+    expect: 'ci-workflow',
+  },
+  {
+    prompt:
+      'Write me a headless automation script with no interactive prompts.',
+    expect: 'cli-script',
+  },
+  {
+    prompt: 'Scaffold a brand-new SKILL.md for this capability.',
+    expect: 'create-skill',
+  },
+  {
+    prompt: 'I need a new reusable prompt snippet added to the corpus.',
+    expect: 'create-snippet',
+  },
+  {
+    prompt: 'Write a fresh authoring convention as a new standard file.',
+    expect: 'create-standard',
+  },
+  {
+    prompt:
+      "The docs folder and README are stale against what's on main, refresh them.",
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Say what that dense answer actually means in plain terms.',
+    expect: 'restate',
+  },
+  {
+    prompt: 'This passage reads flat and robotic, give it some real cadence.',
+    expect: 'write-human',
+  },
+  {
+    prompt:
+      'Pull the captions off this YouTube link and save them with metadata.',
+    expect: 'youtube-transcripts',
+  },
+]

package/src/claude/cases/claude-workflow.ts

@@ -0,0 +1,153 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/**
+ * The `claude-*` skill family: feature planning, review, and the session
+ * artifacts that coordinate work across sessions.
+ *
+ * Every positive is phrased away from its skill's own quoted trigger, since a
+ * verbatim trigger passes by construction and proves nothing about a prompt in
+ * someone's own words. Negatives target the pairs whose bodies already state
+ * an explicit `Do NOT` boundary against each other, since a boundary in a
+ * body does not reach the field a router reads.
+ */
+export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Go fix everything the reviewer flagged on my open PR.',
+    expect: 'claude-address-review',
+  },
+  {
+    prompt:
+      'Run the whole implement, verify, review, and ship pipeline for the approved plan.',
+    expect: 'claude-autoship',
+  },
+  {
+    prompt: "Pull together a design system from what's already in the app.",
+    expect: 'claude-design-extract',
+  },
+  {
+    prompt: 'Draw me a diagram of how the pieces of this system connect.',
+    expect: 'claude-diagram',
+  },
+  {
+    prompt:
+      'Bring the internal planning docs under .claude up to date with what we decided this session.',
+    expect: 'claude-docs',
+  },
+  {
+    prompt:
+      'Sketch out a plan for adding this new capability before we touch any code.',
+    expect: 'claude-feature',
+  },
+  {
+    prompt:
+      'We need to measure this properly before committing to an approach.',
+    expect: 'claude-groundwork',
+  },
+  {
+    prompt: 'Take this pile of raw notes and turn it into filed items.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt: 'Walk me through the open intake items so I can decide on each.',
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt:
+      "Draft a diff-based proposal for tightening this passage in the standard, don't just edit it.",
+    expect: 'claude-markdown-propose',
+  },
+  {
+    prompt: 'Pull the durable lessons out of this session before it ends.',
+    expect: 'claude-memory-capture',
+  },
+  {
+    prompt:
+      'Go through the memory folder and propose what to do with each entry.',
+    expect: 'claude-memory-review',
+  },
+  {
+    prompt:
+      'Take on the orchestrator role and coordinate the parallel feature builds.',
+    expect: 'claude-orchestrate',
+  },
+  {
+    prompt: 'Post a formal review with findings on that open pull request.',
+    expect: 'claude-pr-review',
+  },
+  {
+    prompt:
+      'Look over everything that changed on this branch for bugs and edge cases.',
+    expect: 'claude-review',
+  },
+  {
+    prompt: 'Draft me a script with beats for a screencast recording.',
+    expect: 'claude-screencast',
+  },
+  {
+    prompt:
+      "Check whether my installed Claude seed docs have drifted from the toolkit's.",
+    expect: 'claude-seed-sync',
+  },
+  {
+    prompt: 'Turn this topic into a slide deck I can render.',
+    expect: 'claude-slides-draft',
+  },
+  {
+    prompt:
+      'Check whether the markdown I changed violates any authoring standards.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Open a new entry on the task board for this piece of work.',
+    expect: 'claude-tasks',
+  },
+  {
+    prompt: 'Open a learning workspace so I can study this topic properly.',
+    expect: 'claude-teach',
+  },
+  {
+    prompt: 'Generate the Playwright tests I need after this UI change.',
+    expect: 'claude-ui-test',
+  },
+  {
+    prompt:
+      'Look over the interface and tell me what feels unfinished or confusing.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the paint and layout cost of this page right now.',
+    expect: 'claude-ux-measure',
+  },
+  {
+    prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
+    expect: 'claude-worktree',
+  },
+
+  // Negatives: pairs whose bodies already carry an explicit Do NOT boundary.
+  {
+    prompt:
+      'Refresh the stale sections of README and the docs folder based on what changed.',
+    expect: 'docs-sync',
+  },
+  {
+    prompt: 'Sort through this brain dump and write it up as findings.',
+    expect: 'claude-intake',
+  },
+  {
+    prompt:
+      "Go through what's still unanswered in the intake folder and decide.",
+    expect: 'claude-intake-answer',
+  },
+  {
+    prompt: 'Check this markdown against the house style rules.',
+    expect: 'claude-standards-audit',
+  },
+  {
+    prompt: 'Find the rough, unfinished-feeling spots in this interface.',
+    expect: 'claude-ux-audit',
+  },
+  {
+    prompt: 'Tell me the render cost of this page in the browser.',
+    expect: 'claude-ux-measure',
+  },
+]

package/src/claude/cases/git.ts

@@ -0,0 +1,44 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** The `git-*` skill family: branch, commit, and pull-request mechanics. */
+export const GIT_CASES: readonly SkillCase[] = [
+  {
+    prompt: 'Come up with a conventional name for this branch.',
+    expect: 'git-branch',
+  },
+  {
+    prompt: "Turn what's staged into one commit message.",
+    expect: 'git-commit',
+  },
+  {
+    prompt: "Push a quick follow-up fix onto the PR that's already open.",
+    expect: 'git-followup',
+  },
+  {
+    prompt: 'Turn this bug into a GitHub issue and file it.',
+    expect: 'git-issue',
+  },
+  {
+    prompt: 'Write the title and body for this pull request.',
+    expect: 'git-pr',
+  },
+  {
+    prompt: 'Take this finished feature all the way through to an opened PR.',
+    expect: 'git-ship',
+  },
+  {
+    prompt:
+      'This branch has unrelated commits mixed together, break it into separate branches.',
+    expect: 'git-split',
+  },
+  {
+    prompt:
+      'These staged changes cover more than one concern, commit them separately.',
+    expect: 'git-stage',
+  },
+  {
+    prompt:
+      'Show me the linked worktrees and clear out the ones already merged.',
+    expect: 'git-worktree',
+  },
+]

package/src/claude/cases/misc.ts

@@ -0,0 +1,27 @@
+import type { SkillCase } from '@/claude/skills-rank'
+
+/** Skills that share no prefix with any other domain file here. */
+export const MISC_CASES: readonly SkillCase[] = [
+  {
+    prompt:
+      'Bundle up every open call that only I can make and ask me all at once.',
+    expect: 'decision-escalate',
+  },
+  {
+    prompt: 'Fire up the dev server the way this project documents it.',
+    expect: 'project-commands',
+  },
+  {
+    prompt:
+      "We're about to hit the context limit, write the handoff before we lose state.",
+    expect: 'session-map',
+  },
+  {
+    prompt: 'Catch me up on what was in progress before this session started.',
+    expect: 'session-resume',
+  },
+  {
+    prompt: "This test just started failing and I don't know why yet.",
+    expect: 'systematic-debugging',
+  },
+]