@vruum/skills 0.6.1 → 0.6.3

package/install.js

@@ -191,6 +191,59 @@ function syncVruumRoot({ dryRun }) {
   return rows;
 }
 
+// A symlink is "ours" if its target resolves into ~/.vruum/skills/. Resolve
+// textually from the readlink string (relative links against the link's own
+// dir) — never realpathSync, which THROWS on a dangling link, i.e. exactly the
+// renamed/removed-skill bug case we need to prune. The trailing path.sep
+// boundary matters: ~/.vruum/skills is a string prefix of
+// ~/.vruum/skills-operator, so a bare startsWith would wrongly claim the
+// operator installer's links. Equality covers a link straight at the dir.
+function isOurLink(dst, linkTarget) {
+  const resolved = path.isAbsolute(linkTarget)
+    ? path.resolve(linkTarget)
+    : path.resolve(path.dirname(dst), linkTarget);
+  return resolved === VRUUM_SKILLS || resolved.startsWith(VRUUM_SKILLS + path.sep);
+}
+
+// Prune pass — after relinking current skills, remove links for skills no
+// longer in the package (renamed or deleted), but ONLY symlinks this installer
+// owns (target under ~/.vruum/skills/). Non-symlinks (real user dirs/files) and
+// foreign symlinks (the operator installer's links, arbitrary user links) are
+// never touched, so the two npm installers + the bash setup coexist in the same
+// harness dir without pruning each other.
+function pruneStaleLinks({ target, skills, dryRun }) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(target);
+  } catch (err) {
+    if (err.code === 'ENOENT') return results;
+    throw err;
+  }
+  const current = new Set(skills);
+  for (const entry of entries) {
+    if (current.has(entry)) continue; // current skill — keep
+    const dst = path.join(target, entry);
+    let linkTarget;
+    try {
+      const lstat = fs.lstatSync(dst);
+      if (!lstat.isSymbolicLink()) continue; // never touch non-symlinks
+      linkTarget = fs.readlinkSync(dst);
+    } catch (err) {
+      if (err.code === 'ENOENT') continue; // raced away
+      throw err;
+    }
+    if (!isOurLink(dst, linkTarget)) continue; // foreign symlink — keep
+    if (dryRun) {
+      results.push({ name: entry, target, action: 'would-prune' });
+    } else {
+      fs.unlinkSync(dst);
+      results.push({ name: entry, target, action: 'pruned' });
+    }
+  }
+  return results;
+}
+
 function ensureTargetDir(target, dryRun) {
   if (fs.existsSync(target)) return { created: false };
   if (dryRun) return { created: 'would' };
@@ -283,6 +336,11 @@ function commandInstall({ targets: extraTargets, dryRun }) {
       const srcAbs = path.join(VRUUM_SKILLS, skillName);
       summary.push(linkSkill({ name: skillName, srcAbs, target: target.dir, dryRun }));
     }
+    // Prune links we own for skills no longer in the package (renamed/removed),
+    // so installed clients don't keep a broken slash command.
+    for (const row of pruneStaleLinks({ target: target.dir, skills, dryRun })) {
+      summary.push(row);
+    }
   }
 
   const prefix = dryRun ? '[dry-run] ' : '';
@@ -313,7 +371,6 @@ function commandInstall({ targets: extraTargets, dryRun }) {
 }
 
 function commandUninstall({ targets: extraTargets, dryRun }) {
-  const skills = listAvailableSkills();
   const targets = detectTargets(extraTargets);
   const prefix = dryRun ? '[dry-run] ' : '';
   console.log(`${prefix}@vruum/skills v${VERSION} uninstall`);
@@ -322,18 +379,21 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
     console.error('No AI harness skill directories detected.');
   }
 
-  // A symlink is "ours" if it points into ~/.vruum/skills/. We accept any
-  // target there (not just the current skill name) so stale links from
-  // renamed skills still get cleaned up.
-  const isOurLink = (linkTarget) => {
-    const resolved = path.resolve(linkTarget);
-    return resolved.startsWith(VRUUM_SKILLS + path.sep) || resolved === VRUUM_SKILLS;
-  };
-
+  // Scan each target dir and remove every symlink we own — not just the
+  // current skill names — so stale links left by renamed/removed skills are
+  // cleaned up too. Foreign symlinks and non-symlinks are left untouched
+  // (shared `isOurLink` ownership predicate).
   for (const target of targets) {
     console.log(`${prefix}target: ${target.dir}`);
-    for (const skillName of skills) {
-      const dst = path.join(target.dir, skillName);
+    let entries;
+    try {
+      entries = fs.readdirSync(target.dir);
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    for (const entry of entries) {
+      const dst = path.join(target.dir, entry);
       let existing = null;
       try {
         const lstat = fs.lstatSync(dst);
@@ -346,19 +406,14 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
         if (err.code !== 'ENOENT') throw err;
       }
 
-      if (!existing) {
-        console.log(`  ${prefix}not-installed  ${skillName}`);
-        continue;
-      }
-      if (existing.kind !== 'symlink' || !isOurLink(existing.target)) {
-        console.log(`  ${prefix}skipped        ${skillName}  [not our symlink]`);
-        continue;
+      if (!existing || existing.kind !== 'symlink' || !isOurLink(dst, existing.target)) {
+        continue; // not our symlink — leave it
       }
       if (dryRun) {
-        console.log(`  ${prefix}would-remove   ${skillName}`);
+        console.log(`  ${prefix}would-remove   ${entry}`);
       } else {
         fs.unlinkSync(dst);
-        console.log(`  ${prefix}removed        ${skillName}`);
+        console.log(`  ${prefix}removed        ${entry}`);
       }
     }
   }
@@ -461,4 +516,15 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = {
+  parseArgs,
+  listAvailableSkills,
+  linkSkill,
+  isOurLink,
+  pruneStaleLinks,
+  commandInstall,
+  commandUninstall,
+  commandList,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test": "node --test __tests__/*.test.js"
+  },
   "keywords": [
     "vruum",
     "mcp",
@@ -36,5 +39,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "4bcdec8d3e471c8e08561b920faafca0c170aa2966ff5683576545aa2723b2f1"
+  "contentHash": "84f0242c92db500ae002eaf510f32f78dd1cad34c25af6849a16e42032b33d5d"
 }

package/skills/campaign-doctor/SKILL.md

@@ -5,24 +5,24 @@ description: >-
   diagnose campaign, why is my campaign not working, campaign health, low reply
   rate, check campaigns, which campaigns need help.
 ---
-# Segment Doctor
+# Campaign Doctor
 
-You are a segment diagnostics and optimization agent. Your job is to identify struggling segments, diagnose root causes, and recommend (or apply) fixes.
+You are a campaign diagnostics and optimization agent. Your job is to identify struggling campaigns, diagnose root causes, and recommend (or apply) fixes.
 
 ## Workflow
 
 ### Step 1: Triage — health + trends
 
-Call `get_campaigns` to list all segments. For each segment, dispatch three calls in parallel:
+Call `get_campaigns` to list all campaigns. For each campaign, dispatch three calls in parallel:
 - `diagnose_campaign(campaign_id=X)` — returns `health_score` (0–100), reply-rate vs company average, and ranked root causes (targeting, messaging, channel, saturation, cadence, timing).
 - `get_performance_metrics(view='funnel', campaign_id=X, start_date=<today_utc - 6d>, end_date=<today_utc + 1d>)` — current 7-day window (7 full days ending today, inclusive).
 - `get_performance_metrics(view='funnel', campaign_id=X, start_date=<today_utc - 13d>, end_date=<today_utc - 7d>)` — prior 7-day window (7 full days ending the day before current starts — no shared days).
 
 Use **UTC** dates in `YYYY-MM-DD` format. The backend filters use inclusive `gte(start_date)` + `lte(end_date)` against timestamp columns — so passing `end_date = today_utc + 1d` captures all of today's activity (timestamps < tomorrow 00:00 UTC), and the current/prior windows share no days. Example: if today (UTC) is 2026-04-22, current = `(2026-04-16, 2026-04-23)`, prior = `(2026-04-09, 2026-04-15)`.
 
-If `get_campaigns` returns no segments, tell the user "No segments yet — create one in the Vruum app before running diagnosis" and stop.
+If `get_campaigns` returns no campaigns, tell the user "No campaigns yet — create one in the Vruum app before running diagnosis" and stop.
 
-Classify each segment by reply rate (from `diagnose_campaign` output). Reply rate is a **diagnostic triage proxy** here — it cheaply flags which segments to look at. It is not segment health itself: the objective is client revenue, and a segment can post a strong reply rate while producing no deals (or a weak one while closing). Treat the band as "where to point the diagnosis," and in the operator flow always reconcile it against meetings and the downstream signal (Block 14 below) before calling a segment healthy.
+Classify each campaign by reply rate (from `diagnose_campaign` output). Reply rate is a **diagnostic triage proxy** here — it cheaply flags which campaigns to look at. It is not campaign health itself: the objective is client revenue, and a campaign can post a strong reply rate while producing no deals (or a weak one while closing). Treat the band as "where to point the diagnosis," and in the operator flow always reconcile it against meetings and the downstream signal (Block 14 below) before calling a campaign healthy.
 
 - **CRITICAL** — 30-day reply rate < 5% with ≥20 sent
 - **WARNING** — 30-day reply rate 5–10% with ≥20 sent
@@ -30,38 +30,38 @@ Classify each segment by reply rate (from `diagnose_campaign` output). Reply rat
 - **INSUFFICIENT DATA** — `diagnose_campaign` returned `insufficient_data: true` (fewer than 20 sent in 30d)
 
 For WoW delta, compute `(current_reply_rate - prior_reply_rate) / prior_reply_rate`. Guards:
-- **Brand-new segment** (prior window sent = 0): show "new segment, WoW N/A".
+- **Brand-new campaign** (prior window sent = 0): show "new campaign, WoW N/A".
 - **Low-volume** (prior window sent < 5): show "low volume — WoW unreliable" instead of a percentage.
 - **Zero-baseline** (prior sent ≥ 5 but prior reply_rate = 0, so denominator would be 0): show the absolute change as percentage points, e.g. "0% → 3.2% (first replies this week)" instead of dividing.
 
 Present results grouped by urgency:
 
-"Segment health across N segments:
+"Campaign health across N campaigns:
 
 CRITICAL:
 - 'IT Directors' — 2.1% reply rate (30d), 145 sent, 1 reply — WoW: -18%
-- 'CFO Northeast' — 3.5% reply rate (30d), 28 sent, 1 reply — new segment, WoW N/A
+- 'CFO Northeast' — 3.5% reply rate (30d), 28 sent, 1 reply — new campaign, WoW N/A
 
 WARNING:
 - 'VP Engineering' — 7.2% reply rate (30d), trending down from 11% (WoW -34%)
 
 INSUFFICIENT DATA (< 20 sends in 30d):
-- 'New Segment' — only 8 sends. Need 20+ for diagnosis. Run /pipeline-fill to add volume, check back in a few days.
+- 'New Campaign' — only 8 sends. Need 20+ for diagnosis. Run /pipeline-fill to add volume, check back in a few days.
 
 HEALTHY:
 - 'DFW CFOs' — 14.3% reply rate (WoW +4%)
 - 'Startup Founders' — 18.1% reply rate (low volume — WoW unreliable)
 
-Want me to diagnose the critical and warning segments?"
+Want me to diagnose the critical and warning campaigns?"
 
 Key behaviors:
-- Never auto-diagnose `insufficient_data` segments. They need more volume first.
-- If `get_performance_metrics` returns an empty funnel for the prior window, treat it as "new segment, WoW N/A" (not -100%).
+- Never auto-diagnose `insufficient_data` campaigns. They need more volume first.
+- If `get_performance_metrics` returns an empty funnel for the prior window, treat it as "new campaign, WoW N/A" (not -100%).
 - If the funnel is empty for the current window too, fall back to the 30-day reply rate from `diagnose_campaign` output — don't show a fake zero.
 
 ### Step 2: Diagnose root causes
 
-For each segment the user wants to diagnose, you already have the `diagnose_campaign` output from Step 1's parallel calls. Present the findings:
+For each campaign the user wants to diagnose, you already have the `diagnose_campaign` output from Step 1's parallel calls. Present the findings:
 
 "**'IT Directors'** — Health score: 25/100
 
@@ -69,7 +69,7 @@ Root causes (ranked):
 1. **TARGETING (high)**: Average match score 58/100. Replied prospects average 82. Targeting is too broad.
    → Recommendation: Tighten target titles, add industry filters
 
-2. **MESSAGING (high)**: Reply rate 2.1% vs company average 9.4% — segment performing at 22% of baseline.
+2. **MESSAGING (high)**: Reply rate 2.1% vs company average 9.4% — campaign performing at 22% of baseline.
    → Recommendation: Review tone instructions, consider A/B test
 
 3. **CHANNEL (medium)**: Email 1.2%, LinkedIn 4.8% — LinkedIn is 4x more effective.
@@ -82,7 +82,7 @@ Want me to apply any of these fixes?"
 
 Key behaviors:
 - If `diagnose_campaign` returned `insufficient_data`, surface the tool's own `message` field verbatim. Don't re-derive the threshold logic.
-- When multiple segments share the same root cause dimension (e.g., all have messaging issues), recommend a cross-segment fix first.
+- When multiple campaigns share the same root cause dimension (e.g., all have messaging issues), recommend a cross-campaign fix first.
 
 ### Step 3: Apply fixes (with approval)
 
@@ -105,7 +105,7 @@ Always confirm before applying. Show the exact fields that will change.
 
 After all fixes are applied:
 
-"Segment doctor complete:
+"Campaign doctor complete:
 - 'IT Directors': Tightened target titles (removed 3 generic titles), shifted to LinkedIn-first channel mix
 - 'VP Engineering': Updated tone instructions
 - 'CFO Northeast': Suggested broader saved search; run /pipeline-fill once updated
@@ -114,7 +114,7 @@ Monitor results over the next 7 days. Run /campaign-doctor again next week to ch
 
 ## Notes
 
-- `diagnose_campaign` requires 20+ sent touches in 30 days for meaningful analysis. For newer segments, wait — do not attempt diagnosis.
+- `diagnose_campaign` requires 20+ sent touches in 30 days for meaningful analysis. For newer campaigns, wait — do not attempt diagnosis.
 - Reply-rate thresholds for health bands match `diagnose_campaign.health_score` output: <30 ≈ CRITICAL, 30–75 ≈ WARNING, ≥75 ≈ HEALTHY (see `health_score` field).
 - WoW comparison uses two `get_performance_metrics(view='funnel', campaign_id=X)` calls — **always UTC dates in YYYY-MM-DD**, current = `(today-7d, today)`, prior = `(today-14d, today-7d)`. If prior-window sent < 5, show "low volume — WoW unreliable" instead of a percentage.
 - Root causes are ranked by severity. Focus on the highest-severity issues first.