portawhip 0.1.0

package/adapters/instructions/generate.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Phase 2 step 3: idempotent insert/remove of a one-liner instruction block
+// into a host's instruction file (CLAUDE.md / AGENTS.md / GEMINI.md), so the
+// model knows to call the harness-router MCP server before starting a task.
+// Marker comments make this reversible — never touches the rest of the file.
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+
+const START = "<!-- harness-router:start -->";
+const END = "<!-- harness-router:end -->";
+
+// Plain wording — safe default for hosts with no lazy tool-loading concept
+// (Codex/AGENTS.md verified 8/8 route() calls with this text alone).
+export const GENERIC_BLOCK = `${START}
+Before starting a task, call \`route(task summary)\` on the harness-router MCP
+server and follow any returned pointers. Pass only the positively requested action
+and its direct object; do not copy the raw prompt. Drop chit-chat, venting,
+background, and any rejected, negated, or hypothetical option. If a request is
+buried in chat, route only the request; if the message names several distinct
+actions, call route once per action.
+Example: "ugh CI is flaky again, anyway find where we parse the auth token" ->
+route("find the code that parses the auth token").
+An empty result is normal and means nothing relevant is installed — proceed without it.
+${END}`;
+
+// Claude Code defers MCP tool schemas behind ToolSearch until looked up by
+// name — confirmed live: harness-router's route/list_all showed as deferred
+// at session start and were never called (0/8 in Phase 2 verify), because
+// the generic wording never told the model to look them up first.
+export const CLAUDE_CODE_BLOCK = `${START}
+Before starting a task, call \`route(task summary)\` on the harness-router MCP
+server and follow any returned pointers. Pass only the positively requested action
+and its direct object; do not copy the raw prompt. Drop chit-chat, venting,
+background, and any rejected, negated, or hypothetical option. If a request is
+buried in chat, route only the request; if the message names several distinct
+actions, call route once per action.
+Example: "ugh CI is flaky again, anyway find where we parse the auth token" ->
+route("find the code that parses the auth token").
+If \`route\`/\`list_all\` show up as deferred/pending tools rather than directly
+callable, first call ToolSearch with query
+"select:mcp__harness-router__route,mcp__harness-router__list_all" to load them,
+then call route(). An empty result from route() is normal and means nothing
+relevant is installed — proceed without it.
+${END}`;
+
+export const CURSOR_RULE_BLOCK = `---
+description: Route tasks through the project harness-router before starting work
+alwaysApply: true
+---
+
+${GENERIC_BLOCK}`;
+
+// Windsurf workspace rules live under .windsurf/rules/*.md and pick an
+// activation mode via the `trigger` frontmatter field; always_on = injected
+// into every request in the workspace. This is a dedicated harness-owned
+// file (see owned:true in connector-targets), so it is written whole, not
+// marker-upserted — the frontmatter must stay the first bytes of the file.
+export const WINDSURF_RULE_BLOCK = `---
+trigger: always_on
+---
+
+${GENERIC_BLOCK}`;
+
+export function blockForVariant(variant = "generic") {
+  if (variant === "claude-code") return CLAUDE_CODE_BLOCK;
+  if (variant === "cursor-rule") return CURSOR_RULE_BLOCK;
+  if (variant === "windsurf-rule") return WINDSURF_RULE_BLOCK;
+  return GENERIC_BLOCK;
+}
+
+export function upsertBlock(targetPath, block = GENERIC_BLOCK) {
+  const before = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+  const startIdx = before.indexOf(START);
+  const endIdx = before.indexOf(END);
+  const after =
+    startIdx !== -1 && endIdx !== -1
+      ? before.slice(0, startIdx) + block + before.slice(endIdx + END.length)
+      : before.length > 0
+        ? `${before.trimEnd()}\n\n${block}\n`
+        : `${block}\n`;
+  writeFileSync(targetPath, after);
+  return after !== before;
+}
+
+export function removeBlock(targetPath) {
+  if (!existsSync(targetPath)) return false;
+  const content = readFileSync(targetPath, "utf8");
+  const startIdx = content.indexOf(START);
+  const endIdx = content.indexOf(END);
+  if (startIdx === -1 || endIdx === -1) return false;
+  const before = content.slice(0, startIdx).replace(/\n+$/, "\n");
+  const after = content.slice(endIdx + END.length).replace(/^\n+/, "");
+  writeFileSync(targetPath, `${before}${after}`);
+  return true;
+}
+
+function main() {
+  const [, , command, targetPath, variant] = process.argv;
+  if (!targetPath || !["install", "remove"].includes(command)) {
+    console.error(
+      "usage: generate.mjs <install|remove> <path-to-CLAUDE.md-or-similar> [claude-code|generic]",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const block = blockForVariant(variant);
+  const changed = command === "install" ? upsertBlock(targetPath, block) : removeBlock(targetPath);
+  console.log(`${command} ${targetPath}: ${changed ? "changed" : "no-op"}`);
+}
+
+import { pathToFileURL } from "node:url";
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();

package/core/fixtures/bad-recipe.yaml

@@ -0,0 +1,5 @@
+- id: broken-entry
+  type: skill
+  source: github:example/example
+  route:
+    description: "missing triggers array"

package/core/fixtures/capability-graph.json

@@ -0,0 +1,10 @@
+{
+  "edges": [
+    {
+      "from": "database-migrations",
+      "to": "postgres-patterns",
+      "type": "related_skill",
+      "weight": 1
+    }
+  ]
+}

package/core/fixtures/skill-with-metadata/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: viewport-audit
+description: Inspect responsive viewport failures and layout overflow.
+---
+
+# Viewport Audit
+
+## When to Use
+
+Use this skill when a task mentions clipped labels, mobile toolbar wrapping,
+responsive overflow, or viewport-specific layout checks.
+
+## Related
+
+Pair with Playwright visual checks when browser rendering is available.

package/core/registry/capability-docs.mjs

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+function uniq(values) {
+  return [...new Set(values.filter((v) => typeof v === "string" && v.trim() !== ""))];
+}
+
+function skillFileFor(path) {
+  if (!path || !existsSync(path)) return null;
+  const stat = statSync(path);
+  if (stat.isFile()) return path;
+  if (!stat.isDirectory()) return null;
+  const skillFile = join(path, "SKILL.md");
+  return existsSync(skillFile) ? skillFile : null;
+}
+
+function parseFrontmatter(text) {
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { data: {}, body: text };
+  const data = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!field) continue;
+    data[field[1]] = field[2].replace(/^["']|["']$/g, "").trim();
+  }
+  return { data, body: text.slice(match[0].length) };
+}
+
+function extractHeadings(body, max = 12) {
+  const headings = [];
+  for (const line of String(body ?? "").split(/\r?\n/)) {
+    const match = line.match(/^#{1,3}\s+(.+)$/);
+    if (!match) continue;
+    headings.push(match[1].replace(/\s+#$/, "").trim());
+    if (headings.length >= max) break;
+  }
+  return headings;
+}
+
+function sectionByHeading(body, patterns, maxChars = 1200) {
+  const lines = String(body ?? "").split(/\r?\n/);
+  const chunks = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const heading = lines[i].match(/^(#{1,3})\s+(.+)$/);
+    if (!heading) continue;
+    const title = heading[2].toLowerCase();
+    if (!patterns.some((pattern) => pattern.test(title))) continue;
+    const level = heading[1].length;
+    const collected = [];
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const nextHeading = lines[j].match(/^(#{1,3})\s+/);
+      if (nextHeading && nextHeading[1].length <= level) break;
+      collected.push(lines[j]);
+    }
+    const text = collected
+      .join("\n")
+      .replace(/```[\s\S]*?```/g, " ")
+      .replace(/[`*_>\[\]()]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (text) chunks.push(text);
+  }
+  return chunks.join("\n").slice(0, maxChars);
+}
+
+function readSkillMetadata(path) {
+  try {
+    const skillFile = skillFileFor(path);
+    if (!skillFile) return {};
+    const text = readFileSync(skillFile, "utf8");
+    const { data, body } = parseFrontmatter(text);
+    return {
+      skillFile,
+      frontmatterName: data.name ?? null,
+      frontmatterDescription: data.description ?? null,
+      headings: extractHeadings(body),
+      activation: sectionByHeading(body, [
+        /when to use/,
+        /when to activate/,
+        /activation/,
+        /use when/,
+        /trigger/,
+        /routing/,
+      ]),
+      related: sectionByHeading(body, [/related/, /coordination/, /handoff/], 600),
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function pointerFor(entry) {
+  // Every type:cli entry in this project installs via mise (scripts/load.mjs's
+  // loadCli always dispatches through it), so a bare command name only
+  // resolves if the invoking shell happens to have `mise activate` wired in
+  // - not guaranteed, and not something this project can set up on someone
+  // else's machine (VISION.md: cross-OS by detection, not a per-machine
+  // setup step). `mise exec --` always works, on every OS, with zero setup.
+  // Found live 2026-07-05: a bundle-installed CLI worked via mise but the
+  // bare command was "not found" in a shell with no mise activation.
+  if (entry.type === "cli" && entry.source) return `mise exec -- ${entry.source}`;
+  return entry.path ?? entry.source ?? null;
+}
+
+export function buildCapabilityDocs(index) {
+  return index.entries
+    .filter((entry) => entry.route)
+    .map((entry) => {
+      const triggers = Array.isArray(entry.route.triggers) ? entry.route.triggers : [];
+      const metadata = entry.type === "skill" ? readSkillMetadata(entry.path) : {};
+      const fields = {
+        id: entry.id,
+        type: entry.type,
+        origin: entry.origin,
+        pointer: pointerFor(entry),
+        source: entry.source ?? null,
+        path: entry.path ?? null,
+        description: entry.route.description,
+        triggers,
+        frontmatterName: metadata.frontmatterName ?? null,
+        frontmatterDescription: metadata.frontmatterDescription ?? null,
+        headings: metadata.headings ?? [],
+        activation: metadata.activation ?? null,
+        related: metadata.related ?? null,
+        readyMarker: entry.route.readyMarker ?? null,
+        readyHint: entry.route.readyHint ?? null,
+        action: entry.route.action ?? null,
+      };
+      const text = uniq([
+        entry.id,
+        entry.type,
+        entry.origin,
+        entry.route.description,
+        ...triggers,
+        entry.source,
+        entry.path,
+        metadata.frontmatterName,
+        metadata.frontmatterDescription,
+        ...(metadata.headings ?? []),
+        metadata.activation,
+        metadata.related,
+      ]).join("\n");
+      return { ...fields, text };
+    });
+}

package/core/registry/capability-graph-compiler.mjs

@@ -0,0 +1,90 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { buildCapabilityDocs } from "./capability-docs.mjs";
+import { capabilityKind } from "./capability-kind.mjs";
+import { tokenize } from "../router/tokenize.mjs";
+
+const GRAPH_STOPWORDS = new Set([
+  "agent",
+  "agents",
+  "code",
+  "data",
+  "file",
+  "files",
+  "project",
+  "task",
+  "tool",
+  "tools",
+  "use",
+  "user",
+  "workflow",
+]);
+
+function tokenSet(doc) {
+  const tokens = new Set(tokenize(doc.text).filter((token) => !GRAPH_STOPWORDS.has(token)));
+  for (const token of tokenize(doc.id)) tokens.add(token);
+  return tokens;
+}
+
+function overlapScore(left, right) {
+  let score = 0;
+  for (const token of left.tokens) {
+    if (right.tokens.has(token)) score += 1;
+  }
+  const rightId = right.doc.id.toLowerCase();
+  const leftId = left.doc.id.toLowerCase();
+  if (String(left.doc.text ?? "").toLowerCase().includes(rightId)) score += 4;
+  if (String(right.doc.text ?? "").toLowerCase().includes(leftId)) score += 4;
+  return score;
+}
+
+function edgeType(from, to) {
+  const fromKind = capabilityKind(from.type);
+  const toKind = capabilityKind(to.type);
+  if (fromKind === "skill" && toKind === "tool") return "skill_uses_tool";
+  if (fromKind === "tool" && toKind === "skill") return "tool_supports_skill";
+  if (fromKind === "skill" && toKind === "skill") return "related_skill";
+  return "related_tool";
+}
+
+export function compileCapabilityGraph(
+  index,
+  { maxEdgesPerNode = 3, minScore = 3 } = {},
+) {
+  const docs = buildCapabilityDocs(index);
+  const prepared = docs.map((doc) => ({ doc, tokens: tokenSet(doc) }));
+  const edges = [];
+
+  for (const source of prepared) {
+    const scored = [];
+    for (const target of prepared) {
+      if (source.doc.id === target.doc.id) continue;
+      const score = overlapScore(source, target);
+      if (score >= minScore) {
+        scored.push({
+          from: source.doc.id,
+          to: target.doc.id,
+          type: edgeType(source.doc, target.doc),
+          weight: Math.min(1, Number((score / 8).toFixed(3))),
+          score,
+        });
+      }
+    }
+    scored
+      .sort((a, b) => b.score - a.score || a.to.localeCompare(b.to))
+      .slice(0, maxEdgesPerNode)
+      .forEach(({ score, ...edge }) => edges.push(edge));
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    nodeCount: docs.length,
+    edgeCount: edges.length,
+    edges,
+  };
+}
+
+export function writeCapabilityGraph(path, graph) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(graph, null, 2)}\n`);
+}

package/core/registry/capability-graph.mjs

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export function loadCapabilityGraph(path) {
+  if (!path || !existsSync(path)) return { edges: [] };
+  const graph = JSON.parse(readFileSync(path, "utf8"));
+  return { edges: Array.isArray(graph.edges) ? graph.edges : [] };
+}
+
+function edgeWeight(edge) {
+  return typeof edge.weight === "number" ? edge.weight : 1;
+}
+
+function buildNeighborMap(graph) {
+  const neighbors = new Map();
+  for (const edge of graph.edges ?? []) {
+    if (!edge.from || !edge.to) continue;
+    const list = neighbors.get(edge.from) ?? [];
+    list.push({ id: edge.to, type: edge.type ?? "related", weight: edgeWeight(edge) });
+    neighbors.set(edge.from, list);
+  }
+  return neighbors;
+}
+
+export function expandWithGraph(candidates, docs, graph, { boost = 0.25 } = {}) {
+  if (!candidates.length || !graph?.edges?.length) return candidates;
+
+  const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+  const neighbors = buildNeighborMap(graph);
+  const merged = new Map(candidates.map((candidate) => [candidate.id, { ...candidate }]));
+
+  for (const candidate of candidates) {
+    for (const neighbor of neighbors.get(candidate.id) ?? []) {
+      const doc = docsById.get(neighbor.id);
+      if (!doc) continue;
+      const score = candidate.score * boost * neighbor.weight;
+      const current = merged.get(neighbor.id);
+      if (current) {
+        current.graphSeen = true;
+      } else {
+        merged.set(neighbor.id, {
+          id: neighbor.id,
+          doc,
+          score,
+          graphBoosted: true,
+          graphSource: candidate.id,
+          graphEdgeType: neighbor.type,
+        });
+      }
+    }
+  }
+
+  return [...merged.values()].sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}

package/core/registry/capability-kind.mjs

@@ -0,0 +1,9 @@
+export function capabilityKind(type) {
+  if (type === "mcp" || type === "cli") return "tool";
+  return type;
+}
+
+export function matchesSuggestKind(type, suggest = "any") {
+  if (!suggest || suggest === "any") return true;
+  return capabilityKind(type) === suggest;
+}