vouchington-tooling 0.1.9 → 0.2.0

package/README.md

@@ -199,8 +199,16 @@ process-group probe and bounded-drain semantics outside a browser session.
 
 ## Workflow skills outside plugins
 
-The package ships the canonical Vouchington workflow skill tree at
-`skills/<skill>/SKILL.md`. This stable installed path supports agents that do not
-load Claude or Codex plugins. The Claude and Codex plugin manifests continue to reference the same
-canonical source tree under `plugins/vouchington-workflow/skills`; package build materializes that tree
-without hand-copying skill content.
+The package ships a flat union of canonical workflow, testing, and database skills at
+`skills/<skill>/SKILL.md`. This stable installed path supports agents that do not load Claude or
+Codex plugins. The package build materializes plugin source trees without hand-copying skill content
+and writes sorted schema-v1 provenance to `skills/manifest.json`.
+Each manifest entry may declare its ordered `prerequisites`; ordinary Markdown links remain
+cross-references and never cause additional skills to be linked.
+
+Use `readSkillManifest(skillsRoot)` to discover installed skills or
+`linkSkill({ name, sourceRoot, targetRoot })` to link one into an explicit consumer directory. The
+CLI equivalent is `vouchington link-skill <name> --source-root <skills-dir> --target-root <dir>`.
+It rejects unknown names, paths outside either root, and existing non-matching destinations.
+`targetRoot` must already exist as a physical directory path: symlinked target roots or ancestors are
+rejected.

package/dist/cli/commands/link-skill.d.mts

@@ -0,0 +1,5 @@
+export declare function runLinkSkill(options: {
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
+}): Promise<number>;

package/dist/cli/commands/link-skill.mjs

@@ -0,0 +1,6 @@
+import { linkSkill } from '../../skill-discovery/index.mjs';
+export async function runLinkSkill(options) {
+    const result = await linkSkill(options);
+    process.stdout.write(`${result.created ? 'linked' : 'already-linked'} ${result.path}\n`);
+    return 0;
+}

package/dist/cli/index.mjs

@@ -15,6 +15,7 @@ import { runStageReviewPayloadCommand } from './commands/stage-review-payload.mj
 import { runSwiftSemanticEqualCommand } from './commands/swift-semantic-equal.mjs';
 import { runVitestBlobManifestCommand } from './commands/vitest-blob-manifest.mjs';
 import { runRetrospectiveTranscriptCommand } from './commands/retrospective-transcript.mjs';
+import { runLinkSkill } from './commands/link-skill.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
@@ -99,6 +100,8 @@ export function runCli(argv = process.argv) {
             return runGhaArtifactsCleanup(parsed);
         case 'retrospective-transcript':
             return runRetrospectiveTranscriptCommand(parsed.args);
+        case 'link-skill':
+            return runLinkSkill(parsed);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse.d.mts

@@ -43,6 +43,11 @@ export type ParsedCli = {
 } | {
     kind: 'retrospective-transcript';
     args: string[];
+} | {
+    kind: 'link-skill';
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
 export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -50,6 +50,8 @@ export function parseCli(argv) {
         return parseHttpOrigin(rest);
     if (command === 'retrospective-transcript')
         return { kind: 'retrospective-transcript', args: rest };
+    if (command === 'link-skill')
+        return parseLinkSkill(rest);
     if (command === 'gha-artifacts-cleanup')
         return parseGhaArtifactsCleanup(rest);
     if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
@@ -57,6 +59,29 @@ export function parseCli(argv) {
     }
     return { kind: 'error', message: `unknown command: ${command}` };
 }
+function parseLinkSkill(args) {
+    const [name, ...flags] = args;
+    if (name === undefined || name.startsWith('-'))
+        return { kind: 'error', message: 'link-skill requires a skill name' };
+    let sourceRoot;
+    let targetRoot;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (flag !== '--source-root' && flag !== '--target-root')
+            return { kind: 'error', message: `unknown link-skill option: ${flag}` };
+        if (value === undefined)
+            return { kind: 'error', message: `${flag} requires a path` };
+        if (flag === '--source-root')
+            sourceRoot = value;
+        else
+            targetRoot = value;
+        index += 1;
+    }
+    if (sourceRoot === undefined || targetRoot === undefined)
+        return { kind: 'error', message: 'link-skill requires --source-root and --target-root' };
+    return { kind: 'link-skill', name, sourceRoot, targetRoot };
+}
 function parseRunnerPortPolicy(args) {
     let file;
     let reserved;

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -32,6 +32,7 @@ Commands:
   post-review                   Post one COMMENT review from a staged payload file
   stage-review-payload          Validate a review payload file into a staging directory
   retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts
+  link-skill                    Link one packaged skill into an explicit consumer directory
 
 Options:
   -h, --help       Show this help
@@ -86,6 +87,7 @@ swift-semantic-equal <base> <head> <file.swift>
 post-review
 stage-review-payload optional|required <source> <destination>
 retrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]
+link-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+export { linkSkill, readSkillManifest } from './skill-discovery/index.mts';
+export type { LinkSkillOptions, LinkSkillResult, SkillManifest, SkillManifestEntry, } from './skill-discovery/index.mts';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mts';
 export type { ResolveOptions, TokenTotals, TranscriptFacts, } from './retrospective-transcript/index.mts';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mts';

package/dist/index.mjs

@@ -1,4 +1,5 @@
 /* eslint-disable max-lines -- package entry point enumerates the supported public API. */
+export { linkSkill, readSkillManifest } from './skill-discovery/index.mjs';
 export { codexChildren, codexIdentity, computeTranscriptFacts, formatTranscriptFacts, formatUnavailable, resolveTranscriptFile, runRetrospectiveTranscript, } from './retrospective-transcript/index.mjs';
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from './session-friction/index.mjs';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mjs';

package/dist/skill-discovery/index.d.mts

@@ -0,0 +1,12 @@
+export { readSkillManifest, type SkillManifest, type SkillManifestEntry } from './manifest.mts';
+export type LinkSkillOptions = {
+    name: string;
+    sourceRoot: string;
+    targetRoot: string;
+};
+export type LinkSkillResult = {
+    created: boolean;
+    path: string;
+    source: string;
+};
+export declare function linkSkill(options: LinkSkillOptions): Promise<LinkSkillResult>;

package/dist/skill-discovery/index.mjs

@@ -0,0 +1,64 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { linkDirectoryEntry, resolveTargetDirectory, } from './target-directory.mjs';
+import { assertContained, isContained, isSafeSkillName, readSkillManifest, } from './manifest.mjs';
+export { readSkillManifest } from './manifest.mjs';
+export async function linkSkill(options) {
+    if (!isSafeSkillName(options.name))
+        throw new Error(`Invalid skill name: ${options.name}`);
+    const sourceRoot = resolve(options.sourceRoot);
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const manifest = await readSkillManifest(sourceRoot);
+    const entry = manifest.skills.find((candidate) => candidate.name === options.name);
+    if (entry === undefined)
+        throw new Error(`Unknown skill: ${options.name}`);
+    const targetRoot = await resolveTargetDirectory(options.targetRoot);
+    const linked = new Set();
+    const linking = new Set();
+    return linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking);
+}
+async function linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking) {
+    if (linked.has(entry.name))
+        return linkResult(targetRoot, entry.name, sourceRoot, canonicalSourceRoot, entry.path);
+    if (linking.has(entry.name))
+        throw new Error(`Circular skill prerequisite: ${entry.name}`);
+    linking.add(entry.name);
+    try {
+        for (const prerequisite of prerequisitesFor(manifest, entry)) {
+            await linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, prerequisite, linked, linking);
+        }
+        const result = await linkResult(targetRoot, entry.name, sourceRoot, canonicalSourceRoot, entry.path);
+        linked.add(entry.name);
+        return result;
+    }
+    finally {
+        linking.delete(entry.name);
+    }
+}
+async function linkResult(targetRoot, name, sourceRoot, canonicalSourceRoot, skillPath) {
+    const source = await resolveSkillSource(sourceRoot, canonicalSourceRoot, skillPath);
+    const path = assertContained(targetRoot.path, name);
+    return { created: await linkDirectoryEntry(source, targetRoot, name), path, source };
+}
+function prerequisitesFor(manifest, entry) {
+    const entriesByName = new Map(manifest.skills.map((candidate) => [candidate.name, candidate]));
+    return (entry.prerequisites ?? []).map((name) => entriesByName.get(name));
+}
+async function resolveSkillSource(sourceRoot, canonicalSourceRoot, skillPath) {
+    const candidate = assertContained(sourceRoot, skillPath);
+    let skill;
+    try {
+        skill = await realpath(candidate);
+    }
+    catch {
+        /* v8 ignore next 2 -- only an attacker replacing a validated source can reach this. */
+        throw new Error(`Invalid skill source: ${skillPath}`);
+    }
+    /* v8 ignore next 2 -- only an attacker replacing a validated source can reach this. */
+    if (!isContained(canonicalSourceRoot, skill) || !(await lstat(skill)).isFile())
+        throw new Error(`Skill source escapes root: ${skillPath}`);
+    // Validate through the canonical path, but retain the caller's logical root in
+    // the link target. Package managers replace their physical store paths during
+    // upgrades while the logical installed path remains stable.
+    return dirname(candidate);
+}

package/dist/skill-discovery/manifest.d.mts

@@ -0,0 +1,15 @@
+export type SkillManifestEntry = {
+    name: string;
+    plugin: string;
+    pluginVersion: string;
+    path: string;
+    prerequisites?: string[];
+};
+export type SkillManifest = {
+    version: 1;
+    skills: SkillManifestEntry[];
+};
+export declare function readSkillManifest(sourceRoot: string): Promise<SkillManifest>;
+export declare function assertContained(root: string, child: string): string;
+export declare function isSafeSkillName(name: string): boolean;
+export declare function isContained(root: string, path: string): boolean;

package/dist/skill-discovery/manifest.mjs

@@ -0,0 +1,85 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve, join } from 'node:path';
+export async function readSkillManifest(sourceRoot) {
+    const root = await realpath(resolve(sourceRoot));
+    const parsed = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'));
+    if (!isManifest(parsed))
+        throw new Error('Invalid skills manifest');
+    await validateManifestEntries(root, parsed.skills);
+    return parsed;
+}
+export function assertContained(root, child) {
+    if (isAbsolute(child))
+        throw new Error(`Skill path escapes root: ${child}`);
+    const path = resolve(root, child);
+    if (!isContained(root, path))
+        throw new Error(`Skill path escapes root: ${child}`);
+    return path;
+}
+export function isSafeSkillName(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+export function isContained(root, path) {
+    const pathRelative = relative(root, path);
+    return !pathRelative.startsWith('..') && !isAbsolute(pathRelative);
+}
+async function validateManifestEntries(root, entries) {
+    const names = new Set();
+    const lexicalPaths = new Set();
+    const canonicalPaths = new Set();
+    for (const entry of entries) {
+        if (!isSafeSkillName(entry.name))
+            throw new Error(`Invalid skill name: ${entry.name}`);
+        if (names.has(entry.name))
+            throw new Error(`Duplicate skill name: ${entry.name}`);
+        names.add(entry.name);
+        const prerequisites = entry.prerequisites ?? [];
+        if (new Set(prerequisites).size !== prerequisites.length)
+            throw new Error(`Duplicate skill prerequisite: ${entry.name}`);
+        for (const prerequisite of prerequisites) {
+            if (!isSafeSkillName(prerequisite))
+                throw new Error(`Invalid skill prerequisite: ${prerequisite}`);
+        }
+        if (basename(entry.path) !== 'SKILL.md')
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        const path = assertContained(root, entry.path);
+        if (lexicalPaths.has(path))
+            throw new Error(`Duplicate skill path: ${entry.path}`);
+        lexicalPaths.add(path);
+        let canonicalPath;
+        try {
+            canonicalPath = await realpath(path);
+        }
+        catch {
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        }
+        if (!isContained(root, canonicalPath))
+            throw new Error(`Skill source escapes root: ${entry.path}`);
+        if (!(await lstat(canonicalPath)).isFile())
+            throw new Error(`Invalid skill source: ${entry.path}`);
+        if (canonicalPaths.has(canonicalPath))
+            throw new Error(`Duplicate skill path: ${entry.path}`);
+        canonicalPaths.add(canonicalPath);
+    }
+    for (const entry of entries) {
+        for (const prerequisite of entry.prerequisites ?? []) {
+            if (!names.has(prerequisite))
+                throw new Error(`Missing prerequisite skill: ${prerequisite}`);
+        }
+    }
+}
+function isManifest(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    return manifest.version === 1 && Array.isArray(manifest.skills) && manifest.skills.every(isEntry);
+}
+function isEntry(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return ([entry.name, entry.plugin, entry.pluginVersion, entry.path].every((field) => typeof field === 'string' && field.length > 0) &&
+        (entry.prerequisites === undefined ||
+            (Array.isArray(entry.prerequisites) &&
+                entry.prerequisites.every((name) => typeof name === 'string'))));
+}

package/dist/skill-discovery/target-directory.d.mts

@@ -0,0 +1,10 @@
+export type TargetDirectory = {
+    path: string;
+    dev: bigint;
+    ino: bigint;
+};
+export declare function resolveTargetDirectory(targetRoot: string, beforeRevalidate?: () => Promise<void>): Promise<TargetDirectory>;
+export declare function linkDirectoryEntry(source: string, target: TargetDirectory, name: string, beforeWorker?: () => Promise<void>, worker?: DirectoryLinkWorker, afterWorker?: () => Promise<void>): Promise<boolean>;
+type DirectoryLinkWorker = (source: string, target: TargetDirectory, name: string) => Promise<string>;
+export declare function snapshotTargetDirectory(path: string): Promise<TargetDirectory>;
+export {};

package/dist/skill-discovery/target-directory.mjs

@@ -0,0 +1,126 @@
+import { execFile } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import { parse, relative, resolve, sep, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function resolveTargetDirectory(targetRoot, beforeRevalidate) {
+    const path = resolve(targetRoot);
+    const ancestors = await snapshotTargetAncestors(path);
+    await beforeRevalidate?.();
+    await assertTargetAncestorsUnchanged(ancestors);
+    return ancestors.at(-1);
+}
+export async function linkDirectoryEntry(source, target, name, beforeWorker, worker = runDirectoryLinkWorker, afterWorker) {
+    await beforeWorker?.();
+    const stdout = await worker(source, target, name);
+    await afterWorker?.();
+    await assertTargetUnchanged(target);
+    if (stdout === 'created')
+        return true;
+    if (stdout === 'existing')
+        return false;
+    throw new Error('Skill link worker returned an invalid result');
+}
+async function runDirectoryLinkWorker(source, target, name) {
+    try {
+        const { stdout } = await execFileAsync(process.execPath, [
+            '--input-type=module',
+            '--eval',
+            LINK_WORKER,
+            source,
+            name,
+            String(target.dev),
+            String(target.ino),
+        ], { cwd: target.path, windowsHide: true });
+        return stdout;
+    }
+    catch (error) {
+        if (error.stderr?.includes('Target root changed during skill linking'))
+            throw new Error('Target root changed during skill linking');
+        throw error;
+    }
+}
+export async function snapshotTargetDirectory(path) {
+    const stat = await lstat(path, { bigint: true });
+    if (stat.isSymbolicLink())
+        throw new Error(`Target root contains symlink: ${path}`);
+    if (!stat.isDirectory())
+        throw new Error(`Invalid target root: ${path}`);
+    return { path, dev: stat.dev, ino: stat.ino };
+}
+async function assertTargetUnchanged(target) {
+    try {
+        const current = await snapshotTargetDirectory(target.path);
+        if (current.dev === target.dev && current.ino === target.ino)
+            return;
+    }
+    catch { }
+    throw new Error('Target root changed during skill linking');
+}
+async function snapshotTargetAncestors(path) {
+    const parsed = parse(path);
+    let ancestor = parsed.root;
+    const ancestors = [];
+    for (const component of relative(parsed.root, path).split(sep)) {
+        ancestor = join(ancestor, component);
+        try {
+            ancestors.push(await snapshotTargetDirectory(ancestor));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new Error(`Target root must exist: ${path}`);
+            throw error;
+        }
+    }
+    return ancestors;
+}
+async function assertTargetAncestorsUnchanged(ancestors) {
+    try {
+        for (const target of ancestors) {
+            const current = await snapshotTargetDirectory(target.path);
+            if (current.dev !== target.dev || current.ino !== target.ino)
+                throw new Error('Target root changed while resolving');
+        }
+    }
+    catch {
+        throw new Error('Target root changed while resolving');
+    }
+}
+const LINK_WORKER = String.raw `
+import { lstat, readlink, symlink } from 'node:fs/promises'
+
+const [source, name, dev, ino] = process.argv.slice(1)
+const directory = await lstat('.', { bigint: true })
+if (!directory.isDirectory() || directory.isSymbolicLink() || directory.dev !== BigInt(dev) || directory.ino !== BigInt(ino))
+  throw new Error('Target root changed during skill linking')
+async function assertExistingMatchesSource() {
+  const destination = await lstat(name)
+  if (!destination.isSymbolicLink() || (await readlink(name)) !== source)
+    throw new Error('Destination already exists: ' + name)
+}
+
+let created = false
+try {
+  await assertExistingMatchesSource()
+} catch (error) {
+  if (error?.code !== 'ENOENT') throw error
+  try {
+    await symlink(source, name, 'dir')
+    created = true
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      await assertExistingMatchesSource()
+    } else {
+      if (process.platform !== 'win32' || !['EACCES', 'EPERM'].includes(error?.code)) throw error
+      try {
+        await symlink(source, name, 'junction')
+        created = true
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error
+        await assertExistingMatchesSource()
+      }
+    }
+  }
+}
+process.stdout.write(created ? 'created' : 'existing')
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -31,6 +31,11 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./skill-discovery": {
+      "types": "./dist/skill-discovery/index.d.mts",
+      "import": "./dist/skill-discovery/index.mjs",
+      "default": "./dist/skill-discovery/index.mjs"
+    },
     "./runner-port-policy": {
       "types": "./dist/runner-port-policy/index.d.mts",
       "import": "./dist/runner-port-policy/index.mjs",

package/scripts/build.mjs

@@ -1,7 +1,10 @@
 import { execFileSync } from 'node:child_process'
 import { chmod, copyFile, cp, mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import skillManifest from '../skill-manifest.json' with { type: 'json' }
+
 const packageRoot = new URL('..', import.meta.url)
 const dist = new URL('../dist', import.meta.url)
 
@@ -16,9 +19,18 @@ await copyFile(
   new URL('../src/runner-port-policy/runner-port-policy.json', import.meta.url),
   new URL('../dist/runner-port-policy/runner-port-policy.json', import.meta.url),
 )
-await cp(
-  new URL('../../../plugins/vouchington-workflow/skills', import.meta.url),
-  new URL('../skills', import.meta.url),
-  { recursive: true },
+const pluginRoot = fileURLToPath(new URL('../../../plugins', import.meta.url))
+const skillsRoot = fileURLToPath(new URL('../skills/', import.meta.url))
+const seenSkills = new Set()
+for (const skill of skillManifest.skills) {
+  if (seenSkills.has(skill.name)) throw new Error(`Duplicate skill: ${skill.name}`)
+  seenSkills.add(skill.name)
+  await cp(join(pluginRoot, skill.plugin, 'skills', skill.name), join(skillsRoot, skill.name), {
+    recursive: true,
+  })
+}
+await copyFile(
+  new URL('../skill-manifest.json', import.meta.url),
+  new URL('../skills/manifest.json', import.meta.url),
 )
 await chmod(new URL('../dist/cli/index.mjs', import.meta.url), 0o755)

package/skills/agent-workflow/SKILL.md

@@ -23,5 +23,10 @@ branching, review, and release policy.
 6. Review the diff for accidental files, secrets, generated output, broken documentation links,
    and assumptions that belong in local instructions instead.
 
+For portable implementation and review checks, read [implementation](references/implementation.md),
+[review](references/review.md), and [evidence sweep](references/evidence-sweep.md). The older
+[implementation and review](references/implementation-and-review.md) remains a compact overview.
+Local instructions remain authoritative for commands, commits, review systems, and release policy.
+
 Do not invent a default branch, runner class, documentation root, review system, merge policy, or
 command catalog. A consumer wrapper or local instruction file owns those choices.

package/skills/agent-workflow/references/evidence-sweep.md

@@ -0,0 +1,8 @@
+# Evidence sweep
+
+Map every acceptance criterion to a focused test, inspection, or manual verification with a concrete
+result. Run the required broader checks after focused validation. Treat skipped validation as a
+finding: state the blocker, affected surface, and remaining risk.
+
+Before handoff, compare the final diff to the accepted decision ledger and verify documentation,
+generated output, and public contracts agree with the implementation.

package/skills/agent-workflow/references/implementation-and-review.md

@@ -0,0 +1,9 @@
+# Implementation and review
+
+Before editing, map callers, tests, configuration, and documentation that own the behavior. Keep the
+change within the accepted boundary; record a new dependency or product decision before widening it.
+
+After focused validation, inspect the complete diff for accidental generated files, secret exposure,
+dead paths, and documentation drift. Validate the public interface and failure paths, not only the
+happy path. Before a reviewable commit, run the repository-required checks and state any skipped
+checks with their concrete blocker.

package/skills/agent-workflow/references/implementation.md

@@ -0,0 +1,8 @@
+# Implementation
+
+Keep an accepted-decision ledger for interfaces, data boundaries, validation, and ownership choices
+that could otherwise be lost during coding. Start from a failing behavioral test when practical and
+complete the real path rather than adding placeholders or compatibility shims without a requirement.
+
+When behavior changes, update the public contract, documentation, fixtures, and generated artifacts
+that describe it. Keep local commands, branch policy, and release mechanics in the consumer wrapper.

package/skills/agent-workflow/references/review.md

@@ -0,0 +1,7 @@
+# Review
+
+Review the complete diff, not only changed implementation lines. Check premise and scope, public
+contract compatibility, failure paths, authorization, untrusted input, secrets, and security
+boundaries. Remove dead paths and stale documentation rather than labeling them as legacy.
+
+Record unresolved risk as an explicit accepted decision or follow-up, never as an unnoticed gap.

package/skills/backend-vitest-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: backend-vitest-test-authoring
+description: Apply backend Vitest patterns for service, provider, persistence, and queue boundaries.
+---
+
+# Backend Vitest test authoring
+
+Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first. Exercise real integration
+boundaries only when their lifecycle is controlled by the test environment; otherwise mock the
+network or provider edge. Randomize fixture identities where shared stores can collide, assert
+authorization and retry behavior at boundaries, and clean up resources deterministically.
+
+Consumer wrappers own database setup, queue providers, test projects, and rate-limit policy.
+
+Read [integration boundaries](references/integration-boundaries.md) for fixture and collision safety.

package/skills/backend-vitest-test-authoring/references/integration-boundaries.md

@@ -0,0 +1,10 @@
+# Integration boundaries
+
+Use real persistence, queue, and internal-service boundaries when the test environment controls
+their lifecycle. Mock only external provider edges. Create collision-safe fixture identities and
+register event listeners before the mutation that produces them. Cleanup must be ownership-scoped;
+never broadly reset shared state used by concurrent tests.
+
+Assert persisted state, emitted work, or externally visible results at the boundary. A mock-only
+test is insufficient when import wiring, serialization, transaction behavior, or retries are part
+of the contract.

package/skills/dotnet-test-authoring/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dotnet-test-authoring
+description: Add maintainable .NET tests with appropriate unit, app, and integration boundaries.
+---
+
+# .NET test authoring
+
+Place tests at the narrowest layer that proves the behavior. Batch native or external selection
+where the project requires it, isolate process and filesystem state, and assert serialized contracts
+instead of private implementation details. Keep test helpers typed and reusable only when they remove
+repeated setup without hiding important expectations.
+
+Consumer wrappers own solution layout, test frameworks, native dependencies, and coverage policy.
+
+Keep portable library tests separate from rendered application tests; batch compatible native targets
+in one selection pass so a shared build validates the same source set.

package/skills/manifest.json

@@ -0,0 +1,158 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "agent-workflow",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "agent-workflow/SKILL.md"
+    },
+    {
+      "name": "backend-vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "backend-vitest-test-authoring/SKILL.md",
+      "prerequisites": ["vitest-test-authoring"]
+    },
+    {
+      "name": "blackboard",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "blackboard/SKILL.md"
+    },
+    {
+      "name": "dotnet-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "dotnet-test-authoring/SKILL.md"
+    },
+    {
+      "name": "git-commit-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "git-commit-checklist/SKILL.md"
+    },
+    {
+      "name": "github-actions-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "github-actions-checklist/SKILL.md"
+    },
+    {
+      "name": "github-issue",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "github-issue/SKILL.md"
+    },
+    {
+      "name": "nextjs-vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "nextjs-vitest-test-authoring/SKILL.md",
+      "prerequisites": ["vitest-test-authoring"]
+    },
+    {
+      "name": "organize-github-issues",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "organize-github-issues/SKILL.md"
+    },
+    {
+      "name": "package-json-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "package-json-checklist/SKILL.md"
+    },
+    {
+      "name": "planning",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "planning/SKILL.md"
+    },
+    {
+      "name": "playwright-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "playwright-authoring/SKILL.md"
+    },
+    {
+      "name": "postgres-node-performance-tuning",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.1.0",
+      "path": "postgres-node-performance-tuning/SKILL.md"
+    },
+    {
+      "name": "postgres-partitioning-uuid-v7",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.1.0",
+      "path": "postgres-partitioning-uuid-v7/SKILL.md"
+    },
+    {
+      "name": "pr-description",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "pr-description/SKILL.md"
+    },
+    {
+      "name": "retrospective",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "retrospective/SKILL.md"
+    },
+    {
+      "name": "retrospective-distill",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "retrospective-distill/SKILL.md"
+    },
+    {
+      "name": "review-ci-logs",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "review-ci-logs/SKILL.md"
+    },
+    {
+      "name": "review-github-issue-taxonomy",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "review-github-issue-taxonomy/SKILL.md"
+    },
+    {
+      "name": "revisit-followups",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "revisit-followups/SKILL.md"
+    },
+    {
+      "name": "static-analysis-checklist",
+      "plugin": "vouchington-workflow",
+      "pluginVersion": "0.3.0",
+      "path": "static-analysis-checklist/SKILL.md"
+    },
+    {
+      "name": "storybook-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "storybook-authoring/SKILL.md"
+    },
+    {
+      "name": "swift-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "swift-test-authoring/SKILL.md"
+    },
+    {
+      "name": "test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "test-authoring/SKILL.md"
+    },
+    {
+      "name": "vitest-test-authoring",
+      "plugin": "vouchington-testing",
+      "pluginVersion": "0.1.0",
+      "path": "vitest-test-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
+    }
+  ]
+}

package/skills/nextjs-vitest-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: nextjs-vitest-test-authoring
+description: Apply Vitest patterns for Next.js components, routes, and server-side modules.
+---
+
+# Next.js Vitest test authoring
+
+Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first. Mock framework navigation,
+headers, and server-only boundaries at the framework edge, then test component behavior through
+rendered output and user-visible state. Keep API-response fixtures representative and avoid testing
+framework internals. Use browser tests for behavior that cannot be represented in the test runtime.
+
+Consumer wrappers own framework mock helpers, render libraries, and route fixture conventions.
+
+Read [framework boundaries](references/framework-boundaries.md) for module shape and server-only cases.

package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md

@@ -0,0 +1,9 @@
+# Framework boundaries
+
+Mock framework navigation, headers, cookies, and server-only APIs at the framework edge, not inside
+the component or route under test. Preserve typed module shape and use the consumer's shared mocks
+when they exist. Build API responses with typed factories rather than inline partial objects.
+
+Use direct rendering for component behavior. If request scope, hydration, browser APIs, or server
+module resolution cannot be represented faithfully, move the assertion to an integration or browser
+test instead of widening a unit-test mock.

package/skills/planning/SKILL.md

@@ -19,5 +19,8 @@ Use before implementation work that needs a durable plan. Repository-local `AGEN
 5. Validate and save the plan using the repository's required issue or document workflow before
    implementation when local policy requires one.
 
+For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
+tests or concluding that a surface has no dependents.
+
 Do not invent a plan template, default repository, issue taxonomy, dependency graph tool, or
 approval workflow. A consumer wrapper owns those choices.

package/skills/planning/references/impact-discovery.md

@@ -0,0 +1,9 @@
+# Impact discovery
+
+Start from the changed surface and trace imports, callers, configuration, generated artifacts, and
+tests. Use the repository's graph or search tools where available; otherwise record the evidence
+used and the uncertainty that remains. Select focused tests from real dependents, then include
+broader validation when a shared contract, package boundary, or generated artifact changes.
+
+Do not treat a tool's incomplete graph as proof that no dependent exists. Escalate uncertain
+high-risk boundaries for independent review or a broader test selection.

package/skills/playwright-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: playwright-authoring
+description: Author reliable Playwright browser tests, fixtures, selectors, and user flows.
+---
+
+# Playwright authoring
+
+Use stable, accessible locators and assert user-observable outcomes. Establish data, authentication,
+and server state through supported fixtures or APIs; do not rely on test ordering or arbitrary waits.
+Keep each scenario independently repeatable, use auto-waiting assertions, and capture diagnostics on
+failure. Prefer browser coverage for real browser interactions rather than duplicating unit tests.
+
+Consumer wrappers own environments, credentials, personas, fixtures, and suite commands.
+
+Read [browser reliability](references/browser-reliability.md) for locator, waiting, state, and network rules.

package/skills/playwright-authoring/references/browser-reliability.md

@@ -0,0 +1,9 @@
+# Browser reliability
+
+Use the browser only for browser-owned behavior. Prefer stable accessibility or test-id locators,
+scope repeated content, and assert visible outcomes. Never use arbitrary sleeps; wait for a precise
+URL, request, response, DOM state, or user-visible completion signal.
+
+Seed deterministic data and establish authentication through supported fixtures. Mock network only
+for third-party behavior, fault injection, streaming, or conditions impossible to seed. Register
+response waits before triggering mutations, and make each scenario independent of prior state.

package/skills/postgres-node-performance-tuning/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: postgres-node-performance-tuning
+description: Diagnose and improve PostgreSQL performance in Node.js applications with large data volumes.
+---
+
+# PostgreSQL and Node.js performance
+
+Measure query plans and workload shape before changing code. Select only required columns, bound
+result sets, paginate or stream large reads, batch writes within explicit transaction limits, and
+keep connection-pool usage bounded. Validate query changes with representative cardinality and
+watch latency, memory, lock time, and connection pressure together.
+
+Consumer wrappers own schema ownership, operational thresholds, pooling configuration, and rollout.
+
+Read [performance patterns](references/performance-patterns.md) before changing high-volume paths.

package/skills/postgres-node-performance-tuning/references/performance-patterns.md

@@ -0,0 +1,14 @@
+# Performance patterns
+
+Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
+Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
+transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
+
+For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
+For writes, prefer set-based batches such as UNNEST or COPY when they preserve validation and error
+handling. Measure query plans with representative cardinality before changing an index or query.
+
+Check query predicates, joins, ordering, and selected columns against index shape. Use EXPLAIN
+evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
+correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
+data, but it does not replace suitable local indexes or predicates that permit pruning.

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: postgres-partitioning-uuid-v7
+description: Design PostgreSQL partitions and indexes that use time-ordered UUIDv7 identifiers efficiently.
+---
+
+# PostgreSQL partitioning with UUIDv7
+
+Partition only after confirming lifecycle, retention, and query predicates benefit from it. Treat a
+UUIDv7 as time ordered but not as a replacement for explicit business timestamps where semantics
+matter. Align partition keys, primary keys, indexes, constraints, and query predicates so partition
+pruning is observable. Plan creation, retention, migration, and verification as one deployable
+lifecycle, including rollback and independent-reader compatibility.
+
+Consumer wrappers own partition intervals, migration tooling, retention policy, and deploy sequencing.
+
+Read [partition lifecycle](references/partition-lifecycle.md) before a schema or retention migration.

package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md

@@ -0,0 +1,14 @@
+# Partition lifecycle
+
+UUIDv7 ordering supports range bounds and index-friendly time windows. Generate bounds from time
+instead of extracting timestamps in predicates; use a generated timestamp only when application
+semantics require one. Partition on the range key that queries and retention actually constrain.
+
+Create future ranges before writes need them and maintain a default partition only with an explicit
+attachment plan. Before attaching a populated range, prove the default partition excludes that range
+or move conflicting rows; otherwise attachment can scan and lock the default partition.
+
+Every primary or unique constraint on a partitioned table must include its partition key. Verify
+pruning with predicates on that key, including joins whose other side needs an equivalent range
+condition. UUIDv7 values are time ordered, not a promise that independently generated identifiers
+have a strict ordering relationship.

package/skills/storybook-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: storybook-authoring
+description: Add maintainable Storybook stories and browser-mode component coverage.
+---
+
+# Storybook authoring
+
+Create stories that show meaningful supported states with realistic args and fixtures. Keep story
+data local and deterministic, expose important visual or interaction variants, and add browser-mode
+coverage where it catches behavior unavailable to unit tests. Do not use stories as a substitute for
+end-to-end setup or production data handling.
+
+Consumer wrappers own Storybook configuration, exclusions, visual baselines, and commands.
+
+Read [component coverage](references/component-coverage.md) for direct stories and browser isolation.

package/skills/storybook-authoring/references/component-coverage.md

@@ -0,0 +1,9 @@
+# Component coverage
+
+Keep a direct story for each supported reusable component state. When a component needs server-only
+modules, request context, or browser-hostile imports, isolate the presentational surface or alias the
+boundary to a deterministic fixture. Test interactive story behavior in browser mode when it owns
+the component contract.
+
+Allow story discovery to follow the consumer's module graph and glob configuration. Do not hand
+maintain duplicate registration lists or make module-top-level browser assumptions.

package/skills/swift-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: swift-test-authoring
+description: Add Swift and SwiftUI tests with deterministic state, networking, and view inspection.
+---
+
+# Swift test authoring
+
+Test public behavior with deterministic inputs and injected dependencies. For SwiftUI, inspect or
+interact through the project's supported test approach; for networking, use a protocol-level test
+double and keep request/response synchronization explicit. Avoid sleeps and global state, and keep
+fixtures small enough to make failures readable.
+
+Consumer wrappers own test targets, coverage thresholds, view-inspection libraries, and fixture APIs.
+
+Read [network test doubles](references/network-test-doubles.md) for cancellation and shared-state safety.

package/skills/swift-test-authoring/references/network-test-doubles.md

@@ -0,0 +1,9 @@
+# Network test doubles
+
+Delayed URLProtocol callbacks must honor `stopLoading()`: guard delivery with synchronized stopped
+state so cancellation cannot call a released client. Keep shared response and captured-request state
+private behind one synchronization boundary, reset related fields atomically, and expose coherent
+snapshots for assertions.
+
+Avoid sleeping to coordinate tests. Inject scheduling or await explicit completion so networking,
+view state, and cancellation remain deterministic under parallel execution.

package/skills/test-authoring/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: test-authoring
+description: Write focused, maintainable tests and test fixtures for application or library behavior.
+---
+
+# Test authoring
+
+Use the repository's test conventions and runner skill. Test observable behavior, boundary failures,
+and regressions rather than implementation details. Build fixtures through public constructors or
+documented helpers; keep data minimal, explicit, and representative. Add a focused failing test
+before a behavior change when practical, then run the narrowest relevant test and required checks.
+
+Do not invent project test commands, coverage targets, mock libraries, or integration environments.
+A consumer wrapper owns those choices.
+
+Read [core practice](references/core-practice.md) for the shared boundary, completion, and evidence
+rules before choosing a runner-specific approach.

package/skills/test-authoring/references/core-practice.md

@@ -0,0 +1,10 @@
+# Core test practice
+
+Choose the lowest realistic boundary that can observe the contract. Mock external systems and
+uncontrolled infrastructure; exercise internal module composition where practical. Test behavior,
+failure paths, authorization, and security-relevant validation rather than private calls.
+
+Start with a failing test when the behavior is testable. Finish only when the production path, its
+public contract, documentation, and generated artifacts move together. Do not leave placeholders or
+test-only production branches. For every acceptance criterion, retain evidence from a focused test,
+review, or explicitly justified manual check.

package/skills/vitest-test-authoring/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: vitest-test-authoring
+description: Apply Vitest-specific patterns when adding or changing Vitest tests, mocks, or fixtures.
+---
+
+# Vitest test authoring
+
+Apply [test-authoring](../test-authoring/SKILL.md) first. Keep tests isolated with Vitest lifecycle
+hooks, restore spies and globals after each test, and prefer deterministic async assertions over
+timing waits. Mock external boundaries rather than modules under test, and use typed factories when
+the project supplies them. Run the selected file or project before broader validation.
+
+Consumer wrappers own project selection, mock boundaries, fixture names, and coverage policy.
+
+Read [mock boundaries](references/mock-boundaries.md) when adding module mocks or changing exports.

package/skills/vitest-test-authoring/references/mock-boundaries.md

@@ -0,0 +1,9 @@
+# Mock boundaries
+
+Mock providers, transports, clocks, and environment boundaries rather than application modules.
+When a module mock is necessary, preserve its runtime export shape, type the factory against the
+real module, and spread actual exports unless omission is intentional. Update static factories when
+the mocked module gains an export.
+
+Prefer spies or dependency injection for a narrow seam. Restore mocks, environment, and globals
+after each test so a test cannot alter another test's module graph or process state.