@vruum/skills 0.6.0 → 0.6.2

package/README.md

@@ -75,7 +75,7 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/yc-pipeline-fill` — YC harness source for /pipeline-fill. Scrapes YC's public Algolia index, extracts founder LinkedIn URLs, dedups, hands a candidate list to /pipeline-fill for deep research and import. Use when: YC pipeline fill, source from YC, fill segment with YC founders, sales nav dried up, source YC.
 - `/csv-pipeline-fill` — CSV harness source for /pipeline-fill. Reads a CSV, auto-detects headers, maps columns, hands off to /pipeline-fill for harness deep research and import. Use when: import CSV, paste a CSV, csv import, prospect list from CSV, csv harness mode.
 - `/create-content` — Co-produce an on-voice LinkedIn content post — pull your own signal, steer the angle conversationally, draft in your voice, then save as draft, schedule, or publish. Use when: write a post, draft LinkedIn content, create content, post about, content co-production, help me write a post.
-- `/segment-doctor` — Diagnose and fix struggling outreach segments. Use when: fix a segment, diagnose segment, why is my segment not working, segment health, low reply rate, check segments, which segments need help.
+- `/campaign-doctor` — Diagnose and fix struggling outreach campaigns. Use when: fix a campaign, diagnose campaign, why is my campaign not working, campaign health, low reply rate, check campaigns, which campaigns need help.
 - `/vruum-skills-upgrade` — Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE.
 - `/winback-fill` — Source winback candidates from closed-lost deals or churned customers. Surfaces people who went silent or lost a deal >90 days ago, where the loss reason wasn't 'no_fit'. Use when: winback, win back churned, reactivate, revive cold deals, 90-day silent revival, lost deal recovery, lost customer outreach.
 <!-- generated:skills-end -->

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.0",
+  "version": "0.6.2",
   "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": "5f98cbfea97d8be6ad68c50e12dca22533d20dcae067a0d5558d06e173ac1c72"
+  "contentHash": "753b0d94ad80acaf1986cadaa6502df2a6b6f32a913ec9b39349922331378345"
 }

package/skills/{segment-doctor → campaign-doctor}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: segment-doctor
+name: campaign-doctor
 description: >-
-  Diagnose and fix struggling outreach segments. Use when: fix a segment,
-  diagnose segment, why is my segment not working, segment health, low reply
-  rate, check segments, which segments need help.
+  Diagnose and fix struggling outreach campaigns. Use when: fix a campaign,
+  diagnose campaign, why is my campaign not working, campaign health, low reply
+  rate, check campaigns, which campaigns need help.
 ---
 # Segment Doctor
 
@@ -13,21 +13,21 @@ You are a segment diagnostics and optimization agent. Your job is to identify st
 
 ### Step 1: Triage — health + trends
 
-Call `get_segments` to list all segments. For each segment, dispatch three calls in parallel:
-- `diagnose_segment(segment_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', segment_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', segment_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).
+Call `get_campaigns` to list all segments. For each segment, 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_segments` 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 segments, tell the user "No segments yet — create one in the Vruum app before running diagnosis" and stop.
 
-Classify each segment by reply rate (from `diagnose_segment` 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 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.
 
 - **CRITICAL** — 30-day reply rate < 5% with ≥20 sent
 - **WARNING** — 30-day reply rate 5–10% with ≥20 sent
 - **HEALTHY** — 30-day reply rate ≥ 10% (reply-rate-healthy — confirm it also produces meetings/deals before treating it as truly healthy)
-- **INSUFFICIENT DATA** — `diagnose_segment` returned `insufficient_data: true` (fewer than 20 sent in 30d)
+- **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".
@@ -57,11 +57,11 @@ Want me to diagnose the critical and warning segments?"
 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%).
-- If the funnel is empty for the current window too, fall back to the 30-day reply rate from `diagnose_segment` output — don't show a fake zero.
+- 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_segment` output from Step 1's parallel calls. Present the findings:
+For each segment 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
 
@@ -81,18 +81,18 @@ Root causes (ranked):
 Want me to apply any of these fixes?"
 
 Key behaviors:
-- If `diagnose_segment` returned `insufficient_data`, surface the tool's own `message` field verbatim. Don't re-derive the threshold logic.
+- 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.
 
 ### Step 3: Apply fixes (with approval)
 
 For each recommended fix the user approves:
 
-- **Targeting fix**: Suggest specific ICP field changes and call `update_segment` with new `target_titles`, `target_industries`, or `positioning_angle`.
+- **Targeting fix**: Suggest specific ICP field changes and call `update_campaign` with new `target_titles`, `target_industries`, or `positioning_angle`.
 
-- **Messaging fix**: Suggest revised `ai_tone_instructions` or `ai_selling_strategy` and call `update_segment`.
+- **Messaging fix**: Suggest revised `ai_tone_instructions` or `ai_selling_strategy` and call `update_campaign`.
 
-- **Channel fix**: Call `update_segment` with adjusted `allowed_channels`.
+- **Channel fix**: Call `update_campaign` with adjusted `allowed_channels`.
 
 - **Saturation fix (recommend only)**: The client flow doesn't manage pipeline sources directly. Instead:
   1. Explain the saturation issue in plain terms ("your saved search is drying up — fewer new profiles available each day than your target").
@@ -110,12 +110,12 @@ After all fixes are applied:
 - 'VP Engineering': Updated tone instructions
 - 'CFO Northeast': Suggested broader saved search; run /pipeline-fill once updated
 
-Monitor results over the next 7 days. Run /segment-doctor again next week to check progress."
+Monitor results over the next 7 days. Run /campaign-doctor again next week to check progress."
 
 ## Notes
 
-- `diagnose_segment` requires 20+ sent touches in 30 days for meaningful analysis. For newer segments, wait — do not attempt diagnosis.
-- Reply-rate thresholds for health bands match `diagnose_segment.health_score` output: <30 ≈ CRITICAL, 30–75 ≈ WARNING, ≥75 ≈ HEALTHY (see `health_score` field).
-- WoW comparison uses two `get_performance_metrics(view='funnel', segment_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.
+- `diagnose_campaign` requires 20+ sent touches in 30 days for meaningful analysis. For newer segments, 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.
 - Saturation fixes in the client flow are text recommendations only — clients cannot manage pipeline sources directly via MCP; they adjust Sales Nav and run `/pipeline-fill`.

package/skills/pipeline-fill/SKILL.md

@@ -56,7 +56,7 @@ The orchestrator's MCP precheck at the top of Step 3 (`get_research_playbook` ca
 
 ## Workflow — Step 1: Show pipeline status & pick segments
 
-Call `manage_sales_nav_searches(action="list")` + `get_outreach_stats` for queue depth + `get_segments` for non-Sales-Nav segments. Present a numbered table with **per-segment ETA**:
+Call `manage_sales_nav_searches(action="list")` + `get_outreach_stats` for queue depth + `get_campaigns` for non-Sales-Nav segments. Present a numbered table with **per-segment ETA**:
 
 ```
 Pipeline status:
@@ -127,7 +127,7 @@ Drop blank lines and lines starting with `#` (treat as comments).
 **Path B — operator describes an ICP** (you want the harness to discover candidates)
 Operator gives a brief like "Series A-C SaaS founders, US, 50-500 ppl" or "directors of operations at MSPs in DFW, recently posted about hiring". Harness sources candidates from scratch:
 
-1. **Anchor on segment ICP** — read the segment's existing ICP/company profile (via `get_segment` and `get_company_profile`) and merge with the operator's brief. Show a one-line synthesis ("OK so: Series A-C SaaS, US, 50-500 ppl, founder/CEO/CTO titles") and confirm before sourcing.
+1. **Anchor on segment ICP** — read the segment's existing ICP/company profile (via `get_campaign` and `get_company_profile`) and merge with the operator's brief. Show a one-line synthesis ("OK so: Series A-C SaaS, US, 50-500 ppl, founder/CEO/CTO titles") and confirm before sourcing.
 2. **Source companies first** — use harness tools to find candidate companies matching the brief:
    - `WebSearch` for funding announcements, news, lists ("Series A SaaS 2026", "TechCrunch Series B SaaS announcements")
    - `WebFetch` on Crunchbase / PitchBook / company directories