continuous-improvement 3.20.0 → 3.20.4

package/scripts/git-state-snapshot.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# scripts/git-state-snapshot.sh
+#
+# Emit a single-line JSON envelope describing the current git working-tree
+# state. Composability primitive used by skills that need to baseline or check
+# git state without each restating the same 3-command triple.
+#
+# Fields:
+#   - head:     short SHA returned by `git rev-parse --short HEAD`
+#   - upstream: short SHA of `@{u}` if the branch tracks an upstream, else "none"
+#   - dirty:    integer count of lines from `git status --porcelain` (0 == clean)
+#   - root:     absolute path from `git rev-parse --show-toplevel`
+#   - branch:   `git symbolic-ref --short HEAD`, else "detached"
+#
+# Outside a git repository the script prints `{"error":"not-a-git-repo"}` and
+# exits 1. All other failures are treated as a non-git-repo condition rather
+# than emitting a partial envelope.
+#
+# Cited by:
+#   - skills/gateguard.md            (Parallel-Actor Gate baseline + divergence)
+#   - skills/worktree-safety.md      (Root + branch alignment)
+#   - skills/workspace-surface-audit.md (Environment Grain — parallel-actor row)
+
+set -u
+
+head=$(git rev-parse --short HEAD 2>/dev/null) || {
+  printf '{"error":"not-a-git-repo"}\n'
+  exit 1
+}
+
+if upstream=$(git rev-parse --short '@{u}' 2>/dev/null); then
+  upstream_field=$(printf '"%s"' "$upstream")
+else
+  upstream_field='"none"'
+fi
+
+dirty=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+root=$(git rev-parse --show-toplevel 2>/dev/null || printf 'unknown')
+
+if branch=$(git symbolic-ref --short HEAD 2>/dev/null); then
+  branch_field=$(printf '"%s"' "$branch")
+else
+  branch_field='"detached"'
+fi
+
+printf '{"head":"%s","upstream":%s,"dirty":%s,"root":"%s","branch":%s}\n' \
+  "$head" "$upstream_field" "$dirty" "$root" "$branch_field"

package/scripts/resolve-verify-ladder.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// scripts/resolve-verify-ladder.mjs
+//
+// Resolve the per-project verification ladder for `verification-loop` Phase 0.
+// Encodes the four-step resolution priority — manifest > package.json sniff >
+// per-language toolchain > ask-operator — so the skill body cites this script
+// instead of restating the 80+ lines of priority prose inline.
+//
+// Usage:
+//   node scripts/resolve-verify-ladder.mjs              # pretty fenced block, cwd
+//   node scripts/resolve-verify-ladder.mjs <repo-root>  # pretty, explicit root
+//   node scripts/resolve-verify-ladder.mjs --json       # JSON for machines
+//   node scripts/resolve-verify-ladder.mjs --json <repo-root>
+//
+// Output (default — pretty fenced block):
+//
+//   verify-ladder (resolved):
+//     build:            npm run build  (sniff:package.json:scripts.build)
+//     typecheck:        npx tsc --noEmit  (manifest)
+//     ...
+//
+// Output (--json — single JSON object on stdout):
+//
+//   { "build": { "command": "npm run build", "source": "sniff:..." }, ... }
+//
+// Phases: build, typecheck, lint, test, security, deploy_receipt, synthetic_checks.
+// Sources: "manifest", "manifest:null" (explicitly skipped), "sniff:package.json:<key>",
+//          "sniff:Cargo.toml" | "sniff:go.mod" | "sniff:pyproject.toml" | "sniff:Gemfile",
+//          "ask-operator" (nothing matched).
+//
+// Cited by:
+//   - skills/verification-loop.md Phase 0
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit, stdout } from "node:process";
+
+const PHASES = [
+  "build",
+  "typecheck",
+  "lint",
+  "test",
+  "security",
+  "deploy_receipt",
+  "synthetic_checks",
+];
+
+function parseArgs() {
+  const args = argv.slice(2);
+  let json = false;
+  let root = cwd();
+  for (const a of args) {
+    if (a === "--json") {
+      json = true;
+    } else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: resolve-verify-ladder.mjs [--json] [<repo-root>]\n",
+      );
+      exit(0);
+    } else {
+      root = a;
+    }
+  }
+  return { json, root };
+}
+
+function safeReadJson(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readManifest(root) {
+  return safeReadJson(join(root, ".claude", "verify-ladder.json"));
+}
+
+function readPackageJson(root) {
+  return safeReadJson(join(root, "package.json"));
+}
+
+function sniffPackageJsonScript(pkg, phase) {
+  if (!pkg || !pkg.scripts) return null;
+  const scripts = pkg.scripts;
+  // Priority: verify:<phase> > <phase> > <phase>:* (wildcard tail).
+  // Phase aliases:
+  //   typecheck also matches `tsc` (common in repos that just use `tsc`).
+  //   security also matches `audit` (common in npm projects).
+  const candidates = [`verify:${phase}`, phase];
+  if (phase === "typecheck") candidates.push("tsc");
+  if (phase === "security") candidates.push("audit");
+
+  for (const name of candidates) {
+    if (typeof scripts[name] === "string") {
+      const cmd = name === "test" ? "npm test" : `npm run ${name}`;
+      return {
+        command: cmd,
+        source: `sniff:package.json:scripts.${name}`,
+      };
+    }
+  }
+
+  // Last resort: <phase>:* wildcard tail.
+  const wildcardKey = Object.keys(scripts).find((k) => k.startsWith(`${phase}:`));
+  if (wildcardKey) {
+    return {
+      command: `npm run ${wildcardKey}`,
+      source: `sniff:package.json:scripts.${wildcardKey}`,
+    };
+  }
+
+  return null;
+}
+
+const PER_LANGUAGE = [
+  {
+    marker: "Cargo.toml",
+    commands: {
+      build: "cargo build",
+      typecheck: "cargo check --all-targets",
+      lint: "cargo clippy --all-targets -- -D warnings",
+      test: "cargo test",
+      security: "cargo audit",
+    },
+  },
+  {
+    marker: "go.mod",
+    commands: {
+      build: "go build ./...",
+      typecheck: "go vet ./...",
+      lint: "go vet ./...",
+      test: "go test ./...",
+    },
+  },
+  {
+    marker: "pyproject.toml",
+    commands: {
+      typecheck: "pyright",
+      lint: "ruff check .",
+      test: "pytest",
+    },
+  },
+  {
+    marker: "Gemfile",
+    commands: {
+      lint: "bundle exec rubocop",
+      test: "bundle exec rspec",
+    },
+  },
+];
+
+function sniffPerLanguage(root, phase) {
+  for (const lang of PER_LANGUAGE) {
+    if (!existsSync(join(root, lang.marker))) continue;
+    if (lang.commands[phase]) {
+      return { command: lang.commands[phase], source: `sniff:${lang.marker}` };
+    }
+  }
+  return null;
+}
+
+function resolve(root) {
+  const manifest = readManifest(root);
+  const pkg = readPackageJson(root);
+  const ladder = {};
+
+  for (const phase of PHASES) {
+    // 1. Manifest layer. Underscore-prefixed keys in the manifest are
+    //    documentation/examples — verify-ladder.example.json uses keys like
+    //    "_doc", "_node_example" — so PHASES never starts with "_" and we
+    //    can rely on hasOwn for an exact phase match.
+    if (
+      manifest &&
+      Object.prototype.hasOwnProperty.call(manifest, phase) &&
+      !phase.startsWith("_")
+    ) {
+      const value = manifest[phase];
+      if (value === null) {
+        ladder[phase] = { command: null, source: "manifest:null" };
+      } else if (typeof value === "string") {
+        ladder[phase] = { command: value, source: "manifest" };
+      } else {
+        ladder[phase] = { command: null, source: "manifest:invalid" };
+      }
+      continue;
+    }
+
+    // 2. package.json scripts sniff.
+    const pkgHit = sniffPackageJsonScript(pkg, phase);
+    if (pkgHit) {
+      ladder[phase] = pkgHit;
+      continue;
+    }
+
+    // 3. Per-language toolchain sniff.
+    const langHit = sniffPerLanguage(root, phase);
+    if (langHit) {
+      ladder[phase] = langHit;
+      continue;
+    }
+
+    // 4. Nothing matched — operator must declare or set to null.
+    ladder[phase] = { command: null, source: "ask-operator" };
+  }
+
+  return ladder;
+}
+
+function pretty(ladder) {
+  const widest = Math.max(...Object.keys(ladder).map((k) => k.length));
+  const lines = ["verify-ladder (resolved):"];
+  for (const [phase, entry] of Object.entries(ladder)) {
+    const label = `${phase}:`.padEnd(widest + 2);
+    let line;
+    if (entry.command === null && entry.source === "ask-operator") {
+      line = `  ${label} (ask operator — no marker found)`;
+    } else if (entry.command === null && entry.source === "manifest:null") {
+      line = `  ${label} (skipped — manifest set this field to null)`;
+    } else if (entry.command === null) {
+      line = `  ${label} (skipped — ${entry.source})`;
+    } else {
+      line = `  ${label} ${entry.command}  (${entry.source})`;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const { json, root } = parseArgs();
+  const ladder = resolve(root);
+  if (json) {
+    stdout.write(JSON.stringify(ladder, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(ladder));
+  }
+}
+
+main();

package/scripts/route-recommendation.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// scripts/route-recommendation.mjs
+//
+// Route a single recommendation item to its preferred-skill chain + inline
+// fallback, using the data-driven routing table in
+// `scripts/route-recommendation.routes.json`.
+//
+// Replaces the 26-row Phase 3 routing table that `proceed-with-the-recommendation`
+// would otherwise re-derive every list walk. The skill body cites this script
+// once instead of restating the table inline; the routes.json file is the
+// programmatic source of truth.
+//
+// Usage:
+//   node scripts/route-recommendation.mjs "<recommendation item>"
+//   node scripts/route-recommendation.mjs --json "<recommendation item>"
+//   node scripts/route-recommendation.mjs --list           # all rows
+//   node scripts/route-recommendation.mjs --list --json    # all rows as JSON
+//
+// Output (default):
+//   Match: <row name>
+//   Preferred: <skill1> → <skill2>
+//   Fallback: <inline-fallback text>
+//   Marker: (Reference behavior — does not require <plugin>.)
+//
+// Output (--json):
+//   { "input": "...", "match": { name, preferred, fallback, marker }, "candidates": [...] }
+//
+// Cited by:
+//   - skills/proceed-with-the-recommendation.md Phase 3 routing table
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const ROUTES_PATH = join(SCRIPT_DIR, "route-recommendation.routes.json");
+
+function loadRoutes() {
+  if (!existsSync(ROUTES_PATH)) {
+    stderr.write(`routes file not found: ${ROUTES_PATH}\n`);
+    exit(3);
+  }
+  const raw = readFileSync(ROUTES_PATH, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || !Array.isArray(parsed.rows)) {
+    stderr.write(`routes file is malformed (expected { rows: [...] })\n`);
+    exit(3);
+  }
+  return parsed.rows;
+}
+
+function parseArgs() {
+  const args = argv.slice(2);
+  const out = { json: false, list: false, input: null };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--list") out.list = true;
+    else if (a === "-h" || a === "--help") {
+      stdout.write(
+        "usage: route-recommendation.mjs [--json] <recommendation item>\n" +
+          "       route-recommendation.mjs --list [--json]\n",
+      );
+      exit(0);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (!out.list) {
+    if (positional.length === 0) {
+      stderr.write("usage: route-recommendation.mjs [--json] <recommendation item>\n");
+      stderr.write("input required: pass the recommendation text as the positional arg\n");
+      exit(2);
+    }
+    out.input = positional.join(" ").trim();
+  }
+  return out;
+}
+
+function compileRow(row) {
+  const patterns = Array.isArray(row.patterns) ? row.patterns : [];
+  const compiled = [];
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p, "i"));
+    } catch {
+      // skip malformed pattern — surface via warning, don't crash
+      stderr.write(`warning: bad regex in routes.json (${row.name}): ${p}\n`);
+    }
+  }
+  return { ...row, _compiled: compiled };
+}
+
+function matchRow(row, input) {
+  for (const re of row._compiled) {
+    if (re.test(input)) return true;
+  }
+  return false;
+}
+
+function asciiArrow(preferred) {
+  return preferred.join(" -> ");
+}
+
+function pretty(matchResult) {
+  if (!matchResult.match) {
+    return [
+      `No routing match for input: "${matchResult.input}"`,
+      `ask-operator: this recommendation doesn't fit any known routing row.`,
+      `Either pick a row from --list manually, or surface to the operator.`,
+      "",
+    ].join("\n");
+  }
+  const m = matchResult.match;
+  const lines = [
+    `Match: ${m.name}`,
+    `Preferred: ${asciiArrow(m.preferred)}`,
+    `Fallback: ${m.fallback}`,
+  ];
+  if (m.marker) {
+    lines.push(`Marker: (Reference behavior — does not require ${m.marker}.)`);
+  }
+  if (matchResult.candidates.length > 1) {
+    lines.push("");
+    lines.push(`Other candidates (top match wins):`);
+    for (const c of matchResult.candidates.slice(1, 4)) {
+      lines.push(`  - ${c.name}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main() {
+  const args = parseArgs();
+  const rawRows = loadRoutes();
+  const rows = rawRows.map(compileRow);
+
+  if (args.list) {
+    if (args.json) {
+      const stripped = rows.map(({ _compiled, ...row }) => row);
+      stdout.write(JSON.stringify({ rows: stripped }, null, 2) + "\n");
+      return;
+    }
+    for (const row of rows) {
+      stdout.write(`- ${row.name}\n`);
+      stdout.write(`    preferred: ${asciiArrow(row.preferred)}\n`);
+    }
+    return;
+  }
+
+  const candidates = rows.filter((r) => matchRow(r, args.input));
+  const result = {
+    input: args.input,
+    match: candidates.length > 0 ? stripCompiled(candidates[0]) : null,
+    candidates: candidates.map(stripCompiled),
+  };
+
+  if (args.json) {
+    stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    stdout.write(pretty(result));
+  }
+  // Surface the ask-operator hint on stderr regardless of mode, so callers
+  // that read stderr can detect no-match without re-parsing stdout.
+  if (!result.match) {
+    stderr.write("ask-operator: no routing row matched the input\n");
+  }
+}
+
+function stripCompiled(row) {
+  const { _compiled, ...rest } = row;
+  return rest;
+}
+
+main();

package/scripts/route-recommendation.routes.json

@@ -0,0 +1,213 @@
+{
+  "_doc": [
+    "Routing table for proceed-with-the-recommendation Phase 3.",
+    "scripts/route-recommendation.mjs reads this file; the skill body cites the script.",
+    "Each row maps a recommendation TYPE to a preferred-skill chain + inline fallback.",
+    "Patterns are case-insensitive regexes. First-match-wins; the script preserves row order on ties."
+  ],
+  "rows": [
+    {
+      "name": "Long-running / PRD-style autonomous execution",
+      "patterns": ["\\bprd\\b", "\\bautonomous\\b", "long.running", "iterati(ve|on) loop", "ralph"],
+      "preferred": ["ralph"],
+      "fallback": "Break into sub-recommendations, run proceed-with-the-recommendation recursively per sub-item.",
+      "marker": null
+    },
+    {
+      "name": "Implement feature / add capability",
+      "patterns": ["implement.*feature", "add.*(capability|feature|endpoint)", "build.*feature", "new feature"],
+      "preferred": ["superpowers:brainstorming", "superpowers:writing-plans"],
+      "fallback": "Restate goal → list 3 design options → pick one → outline files to touch → build.",
+      "marker": "superpowers"
+    },
+    {
+      "name": "Fix bug / investigate failure",
+      "patterns": ["fix.*bug", "investigat(e|ion).*(failure|issue|bug)", "debug", "broken", "root.cause"],
+      "preferred": ["superpowers:systematic-debugging"],
+      "fallback": "Hypothesis → add logs/tests → reproduce → smallest fix → verify with the failing repro.",
+      "marker": "superpowers:systematic-debugging"
+    },
+    {
+      "name": "Write tests / add coverage",
+      "patterns": ["write tests?", "add (test|coverage)", "tdd", "test-driven", "unit test"],
+      "preferred": ["superpowers:test-driven-development", "tdd-workflow"],
+      "fallback": "RED (failing test) → GREEN (minimal code) → REFACTOR; one test, one behavior.",
+      "marker": null
+    },
+    {
+      "name": "Refactor / dead code cleanup",
+      "patterns": ["refactor", "dead code", "cleanup", "remove (duplicat|unused)", "simplify"],
+      "preferred": ["simplify"],
+      "fallback": "Find dupes/unused exports, delete in place, re-run type check and smallest test.",
+      "marker": "simplify"
+    },
+    {
+      "name": "Security review / auth audit",
+      "patterns": ["security review", "auth audit", "vulnerab", "owasp", "secret(s|.scan)"],
+      "preferred": ["security-review"],
+      "fallback": "Scan for hardcoded secrets, unsanitized input, missing authz, SQL string concat, open CORS.",
+      "marker": "security-review"
+    },
+    {
+      "name": "Code review before merge",
+      "patterns": ["code review", "review (the )?(diff|pr|change)", "pre-merge review"],
+      "preferred": ["superpowers:requesting-code-review", "code-review"],
+      "fallback": "Read diff top-to-bottom, flag CRITICAL / HIGH / MEDIUM.",
+      "marker": "code-review"
+    },
+    {
+      "name": "Verify before shipping",
+      "patterns": ["verify (before|that)", "verification", "pre.ship", "before (the )?(merge|ship|push)"],
+      "preferred": ["superpowers:verification-before-completion"],
+      "fallback": "Smallest check that proves correctness: typecheck + one test + one curl.",
+      "marker": "superpowers:verification-before-completion"
+    },
+    {
+      "name": "Multiple independent tasks",
+      "patterns": ["multiple (independent )?tasks", "parallel(ize)? (tasks|agents)", "fan out"],
+      "preferred": ["superpowers:dispatching-parallel-agents"],
+      "fallback": "Launch N parallel `Agent` tool calls in one message; reconcile results after.",
+      "marker": "superpowers:dispatching-parallel-agents"
+    },
+    {
+      "name": "Merge / close branch",
+      "patterns": ["merge (the )?branch", "close.*branch", "finish.*branch", "open (the )?pr", "ship (the )?pr"],
+      "preferred": ["superpowers:finishing-a-development-branch"],
+      "fallback": "Verify clean tree, rebase on main, green CI, open PR with summary + test plan.",
+      "marker": "superpowers:finishing-a-development-branch"
+    },
+    {
+      "name": "Post-merge deploy receipt (auto-deploy projects)",
+      "patterns": ["deploy receipt", "post.merge.*deploy", "deployed sha", "auto.deploy", "merge.*deployed"],
+      "preferred": ["deploy-receipt"],
+      "fallback": "Confirm deployed SHA == merge SHA via provider CLI, GitHub Deployments API, or version-endpoint curl, plus a 200 from a documented healthcheck. INCOMPLETE receipt blocks the merge from being reported as done.",
+      "marker": null
+    },
+    {
+      "name": "Schedule a follow-up",
+      "patterns": ["schedule (a )?(follow.up|task|run)", "remind me", "later today", "tomorrow"],
+      "preferred": ["schedule"],
+      "fallback": "Tell user the exact action + cadence; if no scheduler, write a dated TODO/memory entry.",
+      "marker": "schedule"
+    },
+    {
+      "name": "Recurring poll / interval task",
+      "patterns": ["recurring", "every (\\d+|few) (minute|hour|day)", "poll (every|until)", "loop (every|until)"],
+      "preferred": ["loop"],
+      "fallback": "Tell user the cadence + how to re-run manually.",
+      "marker": "loop"
+    },
+    {
+      "name": "Library / API docs lookup",
+      "patterns": ["lookup (the )?(docs|api)", "documentation (for|on)", "api docs", "library docs"],
+      "preferred": ["documentation-lookup"],
+      "fallback": "Use `WebFetch` against the official docs URL, cite what changed.",
+      "marker": "documentation-lookup"
+    },
+    {
+      "name": "Frontend / UI design work",
+      "patterns": ["frontend (work|design)", "ui design", "(landing|marketing) page", "redesign.*ui"],
+      "preferred": ["frontend-design:frontend-design"],
+      "fallback": "Build smallest vertical slice first, verify in browser before styling.",
+      "marker": "frontend-design"
+    },
+    {
+      "name": "Settings / hooks / permission change",
+      "patterns": ["settings\\.json", "hooks?\\.json", "permission(s)?( change)?", "update.*(setting|config)"],
+      "preferred": ["update-config"],
+      "fallback": "Edit `~/.claude/settings.json` with a minimal patch; restart session.",
+      "marker": "update-config"
+    },
+    {
+      "name": "Commit and push",
+      "patterns": ["commit and push", "commit (the )?(change|fix)", "push (the )?(commit|branch)", "git push"],
+      "preferred": ["commit-commands:commit", "commit-commands:commit-push-pr"],
+      "fallback": "`git add <specific files>` → commit with `type(scope): outcome` → push when asked.",
+      "marker": "commit-commands"
+    },
+    {
+      "name": "Continuous-improvement analysis / instinct update",
+      "patterns": ["continuous.improvement", "7 laws", "seven laws", "instinct (update|capture)", "reflect.*session"],
+      "preferred": ["continuous-improvement"],
+      "fallback": "Run the 7-Laws Reflection block manually; append to `observations.jsonl`.",
+      "marker": null
+    },
+    {
+      "name": "Spec-first contract before code",
+      "patterns": ["spec-first", "spec.driven", "write (a )?spec (before|for)", "contract first"],
+      "preferred": ["agent-skills:spec-driven-development"],
+      "fallback": "Restate the contract as a testable spec; downstream tests/code regenerate from it.",
+      "marker": "agent-skills"
+    },
+    {
+      "name": "Source-first reading before writing",
+      "patterns": ["source.first", "read (the )?(source|implementation) first", "read before writ"],
+      "preferred": ["agent-skills:source-driven-development"],
+      "fallback": "Read the existing implementation top-to-bottom first; never write blind.",
+      "marker": "agent-skills"
+    },
+    {
+      "name": "Curate context window before answering",
+      "patterns": ["context (window|budget)", "trim (the )?context", "context engineering"],
+      "preferred": ["agent-skills:context-engineering", "context-budget"],
+      "fallback": "Trim irrelevant context; keep only the load-bearing files in scope.",
+      "marker": "agent-skills"
+    },
+    {
+      "name": "Slice atomic increment with safe deploy",
+      "patterns": ["atomic (increment|change)", "smallest reviewable", "incremental implementation", "feature flag"],
+      "preferred": ["agent-skills:incremental-implementation"],
+      "fallback": "Smallest reviewable change; ship behind a flag if the full scope is too big.",
+      "marker": "agent-skills"
+    },
+    {
+      "name": "Refine vague request into ranked options",
+      "patterns": ["refine (the )?(idea|request)", "rank (the )?option", "brainstorm", "explore (alternatives|options)"],
+      "preferred": ["agent-skills:idea-refine", "superpowers:brainstorming"],
+      "fallback": "Compress N ideas to 1 with explicit scoring criteria.",
+      "marker": "agent-skills"
+    },
+    {
+      "name": "Fan out N agents on isolated worktrees with shared contract",
+      "patterns": ["swarm", "worktree.*shared contract", "fan out.*worktree", "provider migration"],
+      "preferred": ["superpowers:dispatching-parallel-agents", "ruflo-swarm:swarm-init"],
+      "fallback": "Use the swarm contract: fixed roles + base ref + shared contract test; reconcile results after.",
+      "marker": "ruflo-swarm"
+    },
+    {
+      "name": "Stream live observation of long agent runs",
+      "patterns": ["stream.*observation", "live observation", "monitor.*long run", "monitor-stream"],
+      "preferred": ["ruflo-swarm:monitor-stream"],
+      "fallback": "Push-based event log; poll fallback if the MCP server is offline.",
+      "marker": "ruflo-swarm"
+    },
+    {
+      "name": "Visual regression / browser-level diff",
+      "patterns": ["visual (regression|diff)", "screenshot diff", "browser.*regression", "visual-verdict"],
+      "preferred": ["oh-my-claudecode:visual-verdict"],
+      "fallback": "Playwright screenshot diff against staging baseline.",
+      "marker": "oh-my-claudecode"
+    },
+    {
+      "name": "Multi-session retrospective across a sprint",
+      "patterns": ["retrospective", "sprint review", "multi.session review", "what worked.*what failed"],
+      "preferred": ["oh-my-claudecode:retrospective", "learn-eval"],
+      "fallback": "What worked / what failed / what to do differently / 3 ranked next moves.",
+      "marker": "oh-my-claudecode"
+    },
+    {
+      "name": "Long autonomous run with quality gates",
+      "patterns": ["long autonomous", "ultrawork", "quality gates? (between|per) iteration"],
+      "preferred": ["oh-my-claudecode:ultrawork", "ralph"],
+      "fallback": "PRD-shaped autonomous loop with verify-between-iterations.",
+      "marker": "oh-my-claudecode"
+    },
+    {
+      "name": "Product-management work",
+      "patterns": ["\\bprd\\b.*(write|draft)", "okrs?", "personas?", "jtbd", "lean canvas", "market siz", "competitive analysis", "user stor(y|ies)", "acceptance criteria", "launch checklist"],
+      "preferred": ["phuryn/pm-skills (out-of-band install)"],
+      "fallback": "Keep the work shape (problem → user → goal → metric → scope; Given/When/Then per story; objective + 3-5 measurable KRs; we-believe / we'll-know hypothesis; TAM/SAM/SOM bottom-up) without depending on a specific routing target.",
+      "marker": "phuryn/pm-skills"
+    }
+  ]
+}