wp-skills 1.0.0

package/shared/scripts/skillpack-cli.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const buildScript = path.join(scriptDir, "skillpack-build.mjs");
+const installScript = path.join(scriptDir, "skillpack-install.mjs");
+const packageRoot = path.resolve(scriptDir, "..", "..");
+
+function printUsage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  wp-skills <command> [options]",
+      "",
+      "Commands:",
+      "  install   Install skills into a target repository (default command)",
+      "  list      List available skills",
+      "  build     Build dist layout for selected targets",
+      "",
+      "Examples:",
+      "  npx wp-skills install --dest=. --targets=codex,vscode,claude,cursor,antigravity",
+      "  npx wp-skills list",
+      "  npx wp-skills build --out=dist --clean",
+      "",
+    ].join("\n")
+  );
+}
+
+function runNode(scriptPath, args) {
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0) {
+  runNode(installScript, [`--from=${packageRoot}`]);
+}
+
+const [command, ...rest] = argv;
+if (command === "--help" || command === "-h" || command === "help") {
+  printUsage();
+  process.exit(0);
+}
+
+if (command === "build") {
+  runNode(buildScript, rest);
+}
+
+if (command === "install") {
+  const args = rest.some((a) => a.startsWith("--from=")) ? rest : [`--from=${packageRoot}`, ...rest];
+  runNode(installScript, args);
+}
+
+if (command === "list") {
+  const args = rest.some((a) => a.startsWith("--from=")) ? rest : [`--from=${packageRoot}`, ...rest];
+  runNode(installScript, ["--list", ...args]);
+}
+
+const looksLikeFlag = command.startsWith("-");
+if (looksLikeFlag) {
+  // Backward-compatible shorthand: treat bare flags as install args.
+  const args = argv.some((a) => a.startsWith("--from=")) ? argv : [`--from=${packageRoot}`, ...argv];
+  runNode(installScript, args);
+}
+
+process.stderr.write(`Unknown command: ${command}\n\n`);
+printUsage();
+process.exit(2);

package/shared/scripts/skillpack-install.mjs

@@ -0,0 +1,338 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_FROM = path.resolve(SCRIPT_DIR, "..", "..");
+
+function usage() {
+  process.stderr.write(
+    [
+      "Usage:",
+      "  node shared/scripts/skillpack-install.mjs --dest=<repo-root> [options]",
+      "",
+      "Options:",
+      "  --dest=<path>       Destination repo root (required, unless using --global)",
+      "  --from=<path>       Source directory (default: package root, supports source or dist layout)",
+      "  --targets=<list>    Comma-separated targets: codex, vscode, claude, claude-global, cursor, cursor-global, antigravity (default: codex,vscode)",
+      "  --skills=<list>     Comma-separated skill names to install (default: all)",
+      "  --mode=<mode>       'replace' (default) or 'merge'",
+      "  --global            Shorthand for --targets=claude-global (installs to ~/.claude/skills)",
+      "  --dry-run           Show what would be installed without making changes",
+      "  --list              List available skills and exit",
+      "",
+      "Targets:",
+      "  codex               Install to <dest>/.codex/skills/",
+      "  vscode              Install to <dest>/.github/skills/",
+      "  claude              Install to <dest>/.claude/skills/ (project-level)",
+      "  claude-global       Install to ~/.claude/skills/ (user-level, ignores --dest)",
+      "  cursor              Install to <dest>/.cursor/skills/",
+      "  cursor-global       Install to ~/.cursor/skills/ (user-level, ignores --dest)",
+      "  antigravity         Install to <dest>/.agent/skill/",
+      "",
+      "Examples:",
+      "  # Install directly from source layout",
+      "  node shared/scripts/skillpack-install.mjs --dest=../my-wp-repo --targets=codex,vscode,claude,cursor,antigravity",
+      "",
+      "  # Install from dist layout",
+      "  node shared/scripts/skillpack-build.mjs --clean",
+      "  node shared/scripts/skillpack-install.mjs --from=dist --dest=../my-wp-repo --targets=codex,vscode,claude,cursor,antigravity",
+      "",
+      "  # Install globally for Claude Code (all skills)",
+      "  node shared/scripts/skillpack-install.mjs --global",
+      "",
+      "  # Install globally for Cursor (all skills)",
+      "  node shared/scripts/skillpack-install.mjs --targets=cursor-global",
+      "",
+      "  # Install specific skills globally",
+      "  node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-development",
+      "",
+      "  # Install to project with specific skills",
+      "  node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,cursor --skills=wp-wpcli-and-ops",
+      "",
+    ].join("\n")
+  );
+}
+
+function parseArgs(argv) {
+  const args = {
+    from: DEFAULT_FROM,
+    dest: null,
+    targets: ["codex", "vscode"],
+    skills: [],
+    mode: "replace",
+    dryRun: false,
+    global: false,
+    list: false,
+  };
+
+  for (const a of argv) {
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--dry-run") args.dryRun = true;
+    else if (a === "--global") args.global = true;
+    else if (a === "--list") args.list = true;
+    else if (a.startsWith("--from=")) args.from = a.slice("--from=".length);
+    else if (a.startsWith("--dest=")) args.dest = a.slice("--dest=".length);
+    else if (a.startsWith("--targets=")) args.targets = a.slice("--targets=".length).split(",").filter(Boolean);
+    else if (a.startsWith("--skills=")) args.skills = a.slice("--skills=".length).split(",").filter(Boolean);
+    else if (a.startsWith("--mode=")) args.mode = a.slice("--mode=".length);
+    else {
+      process.stderr.write(`Unknown arg: ${a}\n`);
+      args.help = true;
+    }
+  }
+
+  // --global is shorthand for --targets=claude-global
+  if (args.global) {
+    args.targets = ["claude-global"];
+  }
+
+  return args;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function copyFileSyncPreserveMode(src, dest) {
+  const st = fs.statSync(src);
+  fs.copyFileSync(src, dest);
+  fs.chmodSync(dest, st.mode);
+}
+
+function copyDir({ srcDir, destDir }) {
+  if (isSymlink(srcDir)) throw new Error(`Refusing to copy symlink dir: ${srcDir}`);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const ent of entries) {
+    if (ent.name === ".DS_Store") continue;
+    const src = path.join(srcDir, ent.name);
+    const dest = path.join(destDir, ent.name);
+
+    if (isSymlink(src)) throw new Error(`Refusing to copy symlink: ${src}`);
+
+    if (ent.isDirectory()) {
+      copyDir({ srcDir: src, destDir: dest });
+      continue;
+    }
+    if (ent.isFile()) {
+      copyFileSyncPreserveMode(src, dest);
+      continue;
+    }
+  }
+}
+
+function listSkillDirs(skillsRoot) {
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs
+    .readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(skillsRoot, d.name))
+    .filter((d) => fs.existsSync(path.join(d, "SKILL.md")));
+}
+
+const VALID_TARGETS = ["codex", "vscode", "claude", "claude-global", "cursor", "cursor-global", "antigravity"];
+
+function detectSourceLayout(fromDir) {
+  const sourceSkillsDir = path.join(fromDir, "skills");
+  if (listSkillDirs(sourceSkillsDir).length > 0) {
+    return "source";
+  }
+
+  const distCandidates = [
+    path.join(fromDir, "codex", ".codex", "skills"),
+    path.join(fromDir, "vscode", ".github", "skills"),
+    path.join(fromDir, "claude", ".claude", "skills"),
+    path.join(fromDir, "cursor", ".cursor", "skills"),
+    path.join(fromDir, "antigravity", ".agent", "skill"),
+  ];
+  if (distCandidates.some((p) => listSkillDirs(p).length > 0)) {
+    return "dist";
+  }
+
+  throw new Error(
+    `Could not detect source layout from: ${fromDir}. Expected either <from>/skills/* or dist-like target directories.`
+  );
+}
+
+// Map target to source directory
+function getSourceDir(fromDir, target, sourceLayout) {
+  if (sourceLayout === "source") {
+    return path.join(fromDir, "skills");
+  }
+
+  // dist layout: claude-global uses same source as claude; cursor-global uses same as cursor
+  const sourceTarget =
+    target === "claude-global" ? "claude" : target === "cursor-global" ? "cursor" : target;
+  const targetDirMap = {
+    codex: path.join(fromDir, "codex", ".codex", "skills"),
+    vscode: path.join(fromDir, "vscode", ".github", "skills"),
+    claude: path.join(fromDir, "claude", ".claude", "skills"),
+    cursor: path.join(fromDir, "cursor", ".cursor", "skills"),
+    antigravity: path.join(fromDir, "antigravity", ".agent", "skill"),
+  };
+  return targetDirMap[sourceTarget];
+}
+
+// Map target to destination directory
+function getDestDir(destRepoRoot, target) {
+  // claude-global and cursor-global don't need destRepoRoot
+  if (target === "claude-global") {
+    return path.join(os.homedir(), ".claude", "skills");
+  }
+  if (target === "cursor-global") {
+    return path.join(os.homedir(), ".cursor", "skills");
+  }
+
+  // Other targets require destRepoRoot
+  const destDirMap = {
+    codex: path.join(destRepoRoot, ".codex", "skills"),
+    vscode: path.join(destRepoRoot, ".github", "skills"),
+    claude: path.join(destRepoRoot, ".claude", "skills"),
+    cursor: path.join(destRepoRoot, ".cursor", "skills"),
+    antigravity: path.join(destRepoRoot, ".agent", "skill"),
+  };
+  return destDirMap[target];
+}
+
+function installTarget({ fromDir, destRepoRoot, target, skillsFilter, mode, dryRun, sourceLayout }) {
+  const srcSkillsRoot = getSourceDir(fromDir, target, sourceLayout);
+  const destSkillsRoot = getDestDir(destRepoRoot, target);
+
+  assert(srcSkillsRoot, `Unknown target: ${target}`);
+  assert(fs.existsSync(srcSkillsRoot), `Missing source skillpack dir: ${srcSkillsRoot}`);
+
+  let skillDirs = listSkillDirs(srcSkillsRoot);
+  assert(skillDirs.length > 0, `No skills found in: ${srcSkillsRoot}`);
+
+  // Filter skills if requested
+  if (skillsFilter.length > 0) {
+    const requested = new Set(skillsFilter);
+    const available = skillDirs.map((d) => path.basename(d));
+
+    // Validate requested skills exist
+    for (const s of requested) {
+      assert(available.includes(s), `Unknown skill: ${s}. Available: ${available.join(", ")}`);
+    }
+
+    skillDirs = skillDirs.filter((d) => requested.has(path.basename(d)));
+  }
+
+  if (dryRun) {
+    process.stdout.write(`[DRY-RUN] Would install ${skillDirs.length} skill(s) to ${destSkillsRoot}:\n`);
+    for (const d of skillDirs) {
+      process.stdout.write(`  - ${path.basename(d)}\n`);
+    }
+    return;
+  }
+
+  fs.mkdirSync(destSkillsRoot, { recursive: true });
+
+  for (const srcSkillDir of skillDirs) {
+    const name = path.basename(srcSkillDir);
+    const destSkillDir = path.join(destSkillsRoot, name);
+
+    if (mode === "replace") {
+      fs.rmSync(destSkillDir, { recursive: true, force: true });
+    }
+
+    copyDir({ srcDir: srcSkillDir, destDir: destSkillDir });
+  }
+
+  const isGlobal = target === "claude-global" || target === "cursor-global";
+  const location = isGlobal ? destSkillsRoot : path.relative(destRepoRoot, destSkillsRoot) || ".";
+  process.stdout.write(`OK: installed ${skillDirs.length} skill(s) to ${location}\n`);
+}
+
+function listAvailableSkills(fromDir) {
+  const sourceLayout = detectSourceLayout(fromDir);
+  if (sourceLayout === "source") {
+    const skillDirs = listSkillDirs(path.join(fromDir, "skills"));
+    process.stdout.write("Available skills:\n");
+    for (const d of skillDirs) {
+      process.stdout.write(`  - ${path.basename(d)}\n`);
+    }
+    return;
+  }
+
+  // dist layout
+  const sources = ["codex", "vscode", "claude", "cursor", "antigravity"]
+    .map((t) => getSourceDir(fromDir, t, "dist"))
+    .filter((p) => fs.existsSync(p));
+
+  if (sources.length === 0) {
+    process.stderr.write("No built skills found. Run skillpack-build.mjs first.\n");
+    process.exit(1);
+  }
+
+  const skillDirs = listSkillDirs(sources[0]);
+  process.stdout.write("Available skills:\n");
+  for (const d of skillDirs) {
+    process.stdout.write(`  - ${path.basename(d)}\n`);
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(2);
+  }
+
+  const repoRoot = process.cwd();
+  const fromDir = path.isAbsolute(args.from) ? args.from : path.join(repoRoot, args.from);
+
+  // Handle --list
+  if (args.list) {
+    listAvailableSkills(fromDir);
+    process.exit(0);
+  }
+
+  // Validate targets
+  const targets = [...new Set(args.targets)];
+  for (const t of targets) {
+    assert(VALID_TARGETS.includes(t), `Invalid target: ${t}. Valid targets: ${VALID_TARGETS.join(", ")}`);
+  }
+
+  // --dest is required unless only using global targets (claude-global, cursor-global)
+  const needsDest = targets.some((t) => t !== "claude-global" && t !== "cursor-global");
+  if (needsDest && !args.dest) {
+    process.stderr.write("Error: --dest is required for non-global targets.\n\n");
+    usage();
+    process.exit(1);
+  }
+
+  const destRepoRoot = args.dest
+    ? path.isAbsolute(args.dest)
+      ? args.dest
+      : path.join(repoRoot, args.dest)
+    : null;
+
+  assert(args.mode === "replace" || args.mode === "merge", "mode must be 'replace' or 'merge'");
+
+  const sourceLayout = detectSourceLayout(fromDir);
+
+  for (const target of targets) {
+    installTarget({
+      fromDir,
+      destRepoRoot,
+      target,
+      skillsFilter: args.skills,
+      mode: args.mode,
+      dryRun: args.dryRun,
+      sourceLayout,
+    });
+  }
+}
+
+main();

package/shared/scripts/update-upstream-indices.mjs

@@ -0,0 +1,173 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const SOURCES = {
+  wordpressCoreVersionCheck: "https://api.wordpress.org/core/version-check/1.7/",
+  gutenbergReleases: "https://api.github.com/repos/WordPress/gutenberg/releases?per_page=50",
+  wpGutenbergMapDoc:
+    "https://developer.wordpress.org/block-editor/contributors/versions-in-wordpress/",
+};
+
+function mkdirp(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeJson(filePath, value) {
+  mkdirp(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function stripTags(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function decodeHtml(text) {
+  return text
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)));
+}
+
+async function fetchText(url) {
+  const res = await fetch(url, {
+    headers: {
+      "user-agent": "wp-agent-skills-upstream-sync/0.1",
+      accept: "text/html,application/json",
+    },
+  });
+  if (!res.ok) throw new Error(`Fetch failed ${res.status} for ${url}`);
+  return await res.text();
+}
+
+async function fetchJson(url) {
+  const text = await fetchText(url);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Expected JSON from ${url}, got non-JSON response`);
+  }
+}
+
+function parseWpGutenbergMapFromHtml(html) {
+  // Best-effort HTML table parsing without dependencies:
+  // 1) find the first <table> that contains "WordPress Version" and "Gutenberg Versions"
+  // 2) extract rows, then extract cells
+  const tables = [...html.matchAll(/<table[\s\S]*?<\/table>/gi)].map((m) => m[0]);
+  const target = tables.find((t) => /WordPress\s*Version/i.test(t) && /Gutenberg\s*Versions/i.test(t));
+  if (!target) return { rows: [], note: "table-not-found" };
+
+  const rowHtml = [...target.matchAll(/<tr[\s\S]*?<\/tr>/gi)].map((m) => m[0]);
+  const rows = [];
+
+  for (const r of rowHtml) {
+    const cellHtml = [...r.matchAll(/<(td|th)[^>]*>([\s\S]*?)<\/\1>/gi)].map((m) => m[2]);
+    if (cellHtml.length < 2) continue;
+
+    const cells = cellHtml.map((c) => decodeHtml(stripTags(c)));
+    const wp = cells[0];
+    const gb = cells[1];
+
+    if (/WordPress\s*Version/i.test(wp) || /Gutenberg\s*Versions/i.test(gb)) continue;
+    if (!/^\d+\.\d+/.test(wp)) continue;
+
+    rows.push({ wordpress: wp, gutenberg: gb });
+  }
+
+  return { rows, note: null };
+}
+
+function normalizeWpVersionCheckPayload(payload) {
+  // https://api.wordpress.org/core/version-check/1.7/ returns something like:
+  // { offers: [...], translations: [...] }
+  const offers = Array.isArray(payload?.offers) ? payload.offers : [];
+
+  const candidates = offers
+    .map((o) => ({
+      version: typeof o?.version === "string" ? o.version : null,
+      current: typeof o?.current === "string" ? o.current : null,
+      download: typeof o?.download === "string" ? o.download : null,
+      phpVersion: typeof o?.php_version === "string" ? o.php_version : null,
+      mysqlVersion: typeof o?.mysql_version === "string" ? o.mysql_version : null,
+      response: typeof o?.response === "string" ? o.response : null,
+      locale: typeof o?.locale === "string" ? o.locale : null,
+    }))
+    .filter((o) => o.version || o.current);
+
+  // Keep a small, stable subset; prioritize "upgrade" offers.
+  const byVersion = new Map();
+  for (const o of candidates) {
+    const v = o.version ?? o.current;
+    if (!v) continue;
+    if (!byVersion.has(v)) byVersion.set(v, o);
+  }
+
+  const versions = [...byVersion.keys()].sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
+  return {
+    latest: versions[0] ?? null,
+    recent: versions.slice(0, 20),
+    offers: versions.slice(0, 20).map((v) => byVersion.get(v)),
+  };
+}
+
+function normalizeGutenbergReleases(payload) {
+  const releases = Array.isArray(payload) ? payload : [];
+  const stable = releases
+    .filter((r) => r && !r.draft && !r.prerelease && typeof r.tag_name === "string")
+    .map((r) => ({
+      tag: r.tag_name,
+      name: typeof r.name === "string" ? r.name : null,
+      publishedAt: typeof r.published_at === "string" ? r.published_at : null,
+      url: typeof r.html_url === "string" ? r.html_url : null,
+    }));
+  return {
+    latest: stable[0] ?? null,
+    recent: stable.slice(0, 30),
+  };
+}
+
+async function main() {
+  const repoRoot = process.cwd();
+  const outDir = path.join(repoRoot, "shared", "references");
+
+  const [wpVersionPayload, gbReleasesPayload, mapHtml] = await Promise.all([
+    fetchJson(SOURCES.wordpressCoreVersionCheck),
+    fetchJson(SOURCES.gutenbergReleases),
+    fetchText(SOURCES.wpGutenbergMapDoc),
+  ]);
+
+  const wordpress = normalizeWpVersionCheckPayload(wpVersionPayload);
+  const gutenberg = normalizeGutenbergReleases(gbReleasesPayload);
+  const map = parseWpGutenbergMapFromHtml(mapHtml);
+
+  writeJson(path.join(outDir, "wordpress-core-versions.json"), {
+    source: SOURCES.wordpressCoreVersionCheck,
+    ...wordpress,
+  });
+
+  writeJson(path.join(outDir, "gutenberg-releases.json"), {
+    source: SOURCES.gutenbergReleases,
+    ...gutenberg,
+  });
+
+  writeJson(path.join(outDir, "wp-gutenberg-version-map.json"), {
+    source: SOURCES.wpGutenbergMapDoc,
+    note: map.note,
+    rows: map.rows,
+  });
+
+  process.stdout.write("OK: updated shared/references/* upstream indices\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || String(err)}\n`);
+  process.exit(1);
+});

package/skills/wordpress-router/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: wordpress-router
+description: "Use when the user asks about WordPress codebases (plugins, themes, block themes, Gutenberg blocks, WP core checkouts) and you need to quickly classify the repo and route to the correct workflow/skill (blocks, theme.json, REST API, WP-CLI, performance, security, testing, release packaging)."
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
+---
+
+# WordPress Router
+
+## When to use
+
+Use this skill at the start of most WordPress tasks to:
+
+- identify what kind of WordPress codebase this is (plugin vs theme vs block theme vs WP core checkout vs full site),
+- pick the right workflow and guardrails,
+- delegate to the most relevant domain skill(s).
+
+## Inputs required
+
+- Repo root (current working directory).
+- The user’s intent (what they want changed) and any constraints (WP version targets, WP.com specifics, release requirements).
+
+## Procedure
+
+1. Run the project triage script:
+   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
+2. Read the triage output and classify:
+   - primary project kind(s),
+   - tooling available (PHP/Composer, Node, @wordpress/scripts),
+   - tests present (PHPUnit, Playwright, wp-env),
+   - any version hints.
+3. Route to domain workflows based on user intent + repo kind:
+   - For the decision tree, read: `skills/wordpress-router/references/decision-tree.md`.
+4. Apply guardrails before making changes:
+   - Confirm any version constraints if unclear.
+   - Prefer the repo’s existing tooling and conventions for builds/tests.
+
+## Verification
+
+- Re-run the triage script if you create or restructure significant files.
+- Run the repo’s lint/test/build commands that the triage output recommends (if available).
+
+## Failure modes / debugging
+
+- If triage reports `kind: unknown`, inspect:
+  - root `composer.json`, `package.json`, `style.css`, `block.json`, `theme.json`, `wp-content/`.
+- If the repo is huge, consider narrowing scanning scope or adding ignore rules to the triage script.
+
+## Escalation
+
+- If routing is ambiguous, ask one question:
+  - “Is this intended to be a WordPress plugin, a theme (classic/block), or a full site repo?”

package/skills/wordpress-router/references/decision-tree.md

@@ -0,0 +1,55 @@
+# Router decision tree (v1)
+
+This is a lightweight routing guide. It assumes you can run `wp-project-triage` first.
+
+## Step 1: classify repo kind (from triage)
+
+Use `triage.project.kind` and the strongest signals:
+
+- `wp-core` → treat as WordPress core checkout work (core patches, PHPUnit, build tools).
+- `wp-site` → treat as a full site repo (wp-content present; changes might be theme + plugins).
+- `wp-block-theme` → theme.json/templates/patterns workflows.
+- `wp-theme` → classic theme workflows (templates PHP, `functions.php`, `style.css`).
+- `wp-block-plugin` → Gutenberg block development in a plugin (block.json, build pipeline).
+- `wp-plugin` / `wp-mu-plugin` → plugin workflows (hooks, admin, settings, cron, REST, security).
+- `gutenberg` → Gutenberg monorepo workflows (packages, tooling, docs).
+
+If multiple kinds match, prefer the most specific:
+`gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plugin` > `wp-theme` > `wp-plugin`.
+
+## Step 2: route by user intent (keywords)
+
+Route by intent even if repo kind is broad (like `wp-site`):
+
+- **Interactivity API / data-wp-* directives / @wordpress/interactivity / viewScriptModule**
+  - Route → `wp-interactivity-api`.
+- **Abilities API / wp_register_ability / wp-abilities/v1 / @wordpress/abilities**
+  - Route → `wp-abilities-api`.
+- **Playground / run-blueprint / build-snapshot / @wp-playground/cli / playground.wordpress.net**
+  - Route → `wp-playground`.
+- **Blocks / block.json / registerBlockType / attributes / save serialization**
+  - Route → `wp-block-development`.
+- **theme.json / Global Styles / templates/*.html / patterns/**
+  - Route → `wp-block-themes`.
+- **Plugins / hooks / activation hook / uninstall / Settings API / admin pages**
+  - Route → `wp-plugin-development`.
+- **REST endpoint / register_rest_route / permission_callback**
+  - Route → `wp-rest-api`.
+- **WP-CLI / wp-cli.yml / commands**
+  - Route → `wp-wpcli-and-ops`.
+- **Build tooling / @wordpress/scripts / webpack / Vite / npm scripts**
+  - Route → `wp-build-tooling` (planned).
+- **Testing / PHPUnit / wp-env / Playwright**
+  - Route → `wp-testing` (planned).
+- **PHPStan / static analysis / phpstan.neon / phpstan-baseline.neon**
+  - Route → `wp-phpstan`.
+- **Performance / caching / query profiling / editor slowness**
+  - Route → `wp-performance`.
+- **Security / nonces / capabilities / sanitization/escaping / uploads**
+  - Route → `wp-security` (planned).
+
+## Step 3: guardrails checklist (always)
+
+- Verify detected tooling before suggesting commands (Composer vs npm/yarn/pnpm).
+- Prefer existing lint/test scripts if present.
+- If version constraints aren’t detectable, ask for target WP core and PHP versions.