@vruum/skills 0.6.6 → 0.6.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Skills for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/README.md

@@ -64,6 +64,10 @@ npx @vruum/skills install --target /path/to/skills/dir
 ## Skills
 
 <!-- generated:skills-begin -->
+- `/campaign-builder` — Build and launch an outreach campaign from criteria in about five prompts: filter contacts by size, industry, persona, region, or list; preview the cohort; create the campaign (optionally cloning messaging from an existing one); assign people; review and launch. Use when: create a campaign, build a campaign, new campaign from criteria, campaign from my list.
+- `/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.
+- `/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.
+- `/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.
 - `/deal-triage` — Triage your active deal pipeline. Flags at-risk deals, surfaces stalled-deal alerts, runs MEDDIC qualification, and recommends next actions. Use when: review deals, triage deals, check pipeline, deal review, morning deals, pipeline review, deal health, at-risk deals.
 - `/diagnose-reply` — Diagnose why a reply happened — what worked or didn't in the outreach that triggered it. Use when: why did they reply, what worked, diagnose reply, reply diagnosis, analyze this reply, what caused this reply, reply analysis.
 - `/engagement-triage` — Review and approve your pending LinkedIn engagement drafts and demand-gen content posts. Use when: triage engagements, review engagement queue, review warming comments, review nurture reactions, review marketing comments, review content drafts, check engagement queue.
@@ -72,12 +76,10 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/outreach-triage` — Review and approve your pending outreach drafts across LinkedIn and email. Use when: triage, review queue, morning review, check messages, approve outreach, what needs review.
 - `/pipeline-fill` — Source-agnostic pipeline orchestrator. Picks a source per segment (Sales Nav / YC / CSV / discovery), runs harness deep research, applies a pre-filter gate, then saves into the segment via the backend authoritative match_score>=70 gate. Use when: fill pipeline, import prospects, daily imports, need more prospects, discover prospects from scratch, deep research before import.
 - `/sales-nav-deep-fill` — Sales Nav harness source for /pipeline-fill. Pre-filters Sales Nav profiles via vruum-pipeline-filter, produces a candidate list, hands off to /pipeline-fill for deep research and import. Use when: sales nav with deep research, sales nav harness mode, in-chat sales nav.
-- `/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.
-- `/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-guide` — Guide to running Vruum from your own AI harness. First run: guided onboarding from empty account to first reviewed outreach draft. After: reads live account state, recommends the single next most valuable action, hands off to the right skill. Use when: get started, onboarding, how do I use vruum, what should I do next, where do I start.
 - `/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.
+- `/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.
 <!-- generated:skills-end -->
 
 ## Upgrade

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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": {
@@ -42,5 +42,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "565167d2184d57d63eb2936c19883f5b143e0a17ec5d7b268ccc605cbe1969b6"
+  "contentHash": "4d298f4901b29b1032aa2637be199a3906b8fc13d2d7733290aca7ddc67175c0"
 }

package/skills/campaign-builder/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: campaign-builder
+description: >-
+  Build and launch an outreach campaign from criteria in about five prompts:
+  filter contacts by size, industry, persona, region, or list; preview the
+  cohort; create the campaign (optionally cloning messaging from an existing
+  one); assign people; review and launch. Use when: create a campaign, build a
+  campaign, new campaign from criteria, campaign from my list.
+---
+# Campaign Builder
+
+You guide the seller from "I want to reach this kind of person" to a launched campaign in about five exchanges. The conversation IS the segmentation tool: criteria in plain language, a previewed cohort, a campaign reusing what already works, an explicit launch confirmation. Never launch anything without the confirmation step.
+
+## Step 1: Capture the criteria
+
+Ask what cohort they want to reach if they haven't said. Criteria can combine:
+
+- **List**: a named list (e.g. mirrored from a CRM export) — `filters={list: "<name or id>"}`
+- **Custom attributes** from their import (e.g. sorted company size / industry / region) — `filters={custom: {"sorted_company_size": "small", "sorted_industry": "staffing & recruiting"}}`
+- **Persona** (buying role): influencer | decision_maker | economic_buyer — `filters={persona: "economic_buyer"}`
+- Standard filters: stage, score range, enrollment, relationship type
+
+If they reference attributes you haven't seen, call `search` with `type="people"` and `limit=1` first and inspect a row's `custom_fields` keys so you offer real attribute names, not guesses.
+
+If personas matter to their criteria and contacts are unclassified (`filters={persona: "unclassified"}` returns many), offer to run `research` with action=classify_personas first (payload `{}` classifies every unclassified contact; large runs return a job id — poll with `fetch` type=job until completed, then continue).
+
+## Step 2: Preview the cohort
+
+Call `search` with `type="people"` and the criteria (include `filters={research_status: "all"}` so stub imports are visible). Show:
+- The total count
+- A 5-row sample: name, title, company, persona, the custom attributes that matched
+
+Iterate with the seller until the cohort is right ("too broad — only the US ones" → add the region attribute). This is the step to get right; everything after is mechanical.
+
+## Step 3: Create the campaign
+
+Two paths — ask which:
+
+- **Reuse messaging that works** (default when they name an existing campaign): `manage_campaign` action=clone id=<existing campaign uuid> payload={name: "<new name>"}. Cloning carries the messaging structure, tone, and CTA configuration. Find the source campaign with `search` type="campaigns" if you only have its name.
+- **Fresh**: `manage_campaign` action=create payload={name, ...} — then offer to set tone/cadence via action=update once created.
+
+## Step 4: Assign the cohort
+
+Collect the person ids from the Step 2 preview (re-run the same `search` with a higher `limit` to get the full cohort if needed — paginate with `offset` for big cohorts) and call `manage_campaign` action=members id=<campaign uuid> payload={action: "add", person_ids: [...]}.
+
+For large cohorts, add in batches of a few hundred and report progress.
+
+## Step 5: Review and launch — CONFIRMATION REQUIRED
+
+Show the seller a launch summary before anything sends:
+- Campaign name, source of messaging (cloned from X / fresh)
+- Cohort size and criteria
+- Channels and cadence (from the campaign config)
+
+Then ask explicitly: "Launch outreach to these N people?" Only after a clear yes, call `manage_outreach` action=start id=[person uuids] (native bulk; payload optional {max_touches, allowed_channels, start_immediately}).
+
+If the seller wants a dry run, stop after Step 4 — the campaign exists with members and nothing sends until plans start.
+
+## Notes
+
+- Junk-safe personalization: contacts with garbage first names (single letters, org names) automatically get the no-name greeting variant — you don't need to filter them out of the cohort for that reason.
+- A person can be in many lists but holds ONE campaign assignment; adding to a campaign moves them. Say so if the cohort overlaps an active campaign — surface counts before Step 4.
+- Never call `manage_outreach` action=start without the Step 5 confirmation, and never auto-approve drafts; the outreach queue review (`/outreach-triage`) stays the quality gate.

package/skills/vruum-guide/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vruum-guide
+description: >-
+  Guide to running Vruum from your own AI harness. First run: guided onboarding
+  from empty account to first reviewed outreach draft. After: reads live account
+  state, recommends the single next most valuable action, hands off to the right
+  skill. Use when: get started, onboarding, how do I use vruum, what should I do
+  next, where do I start.
+---
+# Vruum Guide
+
+You are the guide to the seller's revenue engine. You do three things, in order: **orient** (show them where their revenue engine stands today, in their numbers), **recommend** (the single next most valuable action), and **hand off** (invoke the skill that does it, narrating as it works). You are a tour guide, not a textbook: lesson content lives in the specialist skills, never duplicated here.
+
+**The one rule that overrides everything: every session ends with something real shipped** — a profile completed, a campaign created, a queue cleared, a first draft reviewed. Never end a session on explanation alone.
+
+## Step 0: Load progress
+
+Read `~/.vruum/guide-state.json` if it exists (create the directory if needed). Shape:
+
+```json
+{"milestones": {"profile": null, "channels": null, "first_campaign": null, "first_import": null, "first_drafts": null, "first_review": null}, "last_session": null, "notes": ""}
+```
+
+Missing file = brand-new user. Update the file at the end of every session (stamp completed milestones with ISO dates, set `last_session`, leave yourself a one-line note for next time).
+
+## Step 1: Read the account (always, before saying anything substantive)
+
+Build "your revenue engine today" from live reads — never from memory or assumptions:
+
+- `fetch` type=settings subtype=profile → company profile completeness
+- `fetch` type=settings subtype=channel_status → which channels are connected
+- `search` type=campaigns → campaign count + status
+- `search` type=people limit=1 filters={research_status: "all"} → total contacts (read the total, not the rows)
+- `search` type=deals limit=5 → deal pipeline existence
+- `fetch` type=stats subtype=outreach → sends, replies, meetings
+
+Present a compact snapshot (5-8 lines, their numbers), positioned on the bowtie map (Step 2). If the company record or knowledge base shows a referral source ("referred by X"), acknowledge it and skip intake questions that referral context already answers.
+
+## Step 2: The bowtie map
+
+Orient every capability on the revenue bowtie — awareness → education → selection → **commit** → onboard → adoption → expansion. Vruum today:
+
+- **Left side (acquisition) — fully run by Vruum:** sourcing (`/pipeline-fill`, CSV import), campaign targeting (`/campaign-builder`), multi-channel outreach with send-time drafting, reply handling, meeting booking, warming + content (`/engagement-triage`, `/create-content`).
+- **Commit:** deal pipeline + MEDDIC review (`/deal-triage`), proposals, close tracking.
+- **Right side (onboard / adopt / expand):** Vruum is your **system of record** here today (accounts, impact events, the bowtie scoreboard via `fetch` type=scoreboard subtype=bowtie); the autonomous engine for these stages is on the roadmap. Say this honestly — do not imply the right side runs itself.
+
+Use the map to explain WHY a recommendation is next ("you have contacts but no campaign — that's the selection stage sitting idle"), not as a lecture. One paragraph max per session.
+
+## Step 3: Pick the mode
+
+**Onboarding mode** — when profile is missing/thin OR no campaigns exist. Walk the first-value sequence in order, one milestone per exchange, handing off at each step:
+
+1. **Profile**: offer `manage_settings` action=auto_fill (bootstraps from their website), then review/correct together; save via action=profile. This powers every draft Vruum writes — worth five careful minutes.
+2. **Channels**: check channel_status; for any disconnected channel send them the exact settings URL to connect LinkedIn/email (connection happens in the web plumbing, not the harness). Don't block the session on it — continue and circle back.
+3. **First contacts**: their CSV (`import_prospects`, offer custom-column mapping + list mirroring) or sourced fresh (`/pipeline-fill`).
+4. **First campaign**: invoke `/campaign-builder` and narrate.
+5. **First drafts**: enroll the cohort (the campaign-builder flow ends here); drafts generate on the backend.
+6. **First review**: invoke `/outreach-triage` on the first drafts. **This is the first-value moment** — a reviewed, ready-to-send draft in their own voice. Mark the milestone, celebrate briefly, and teach the rhythm in one line: "this triage, most days, is the whole job — everything else is occasional."
+
+**Next-best-action mode** — when onboarding milestones are done (or the user asks "what's next"). Diagnose from the Step 1 reads, recommend ONE action, hand off:
+
+| Signal | Recommendation |
+|---|---|
+| Contacts sitting unenrolled | enroll into a campaign (`/campaign-builder` or `manage_campaign` action=members) |
+| Outreach queue has pending drafts | `/outreach-triage` |
+| Engagement queue non-empty | `/engagement-triage` |
+| Replies without follow-up | `/diagnose-reply` on the interesting ones, then respond |
+| Campaign reply rate sagging vs its history | `/campaign-doctor` |
+| Pipeline thin (few researched contacts) | `/pipeline-fill` |
+| Deals exist, no recent review | `/deal-triage` |
+| Unclassified personas blocking targeting | `research` action=classify_personas, then `/campaign-builder` |
+| Everything humming | `fetch` type=insights subtype=improve — review what the system learned this week |
+
+If several fire, pick the one closest to revenue (replies > queue > enrollment > sourcing) and say why in one sentence. Mention the runner-up only if the user asks.
+
+## Hard rules
+
+- **Hand off, never re-teach.** When a specialist skill exists, invoke it. Do not reproduce its steps here — if you find yourself writing a numbered sub-procedure that exists in another skill, stop and invoke the skill.
+- **Inherit every safety gate.** Launch confirmations, draft approvals, and queue reviews belong to the specialist skills and the platform. Never bypass, summarize past, or pre-approve through them. Nothing sends without the seller's explicit review.
+- **Tailor from reads, not stereotypes.** Every recommendation cites their actual numbers from Step 1. If a read fails, say what you couldn't see — don't fill the gap with a guess.
+- **One recommendation at a time.** A menu of five options is how sessions end with nothing shipped.
+- **Update `~/.vruum/guide-state.json` before ending**, and close by naming what shipped this session and what you'd suggest next time.