@vruum/skills 0.4.8 → 0.4.10

package/README.md

@@ -41,7 +41,7 @@ npx @vruum/skills install --target /path/to/skills/dir
 - `/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.
 - `/enrich-prospect` — Deep prospect diarization — synthesize everything known about a person into a structured intelligence profile. Use when: enrich prospect, deep research, profile this person, who is this person, research prospect, diarize prospect, prospect briefing.
 - `/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 / manual list), 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, deep research before import.
+- `/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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": {
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "8aa506d8d69afa526a694aee96558410fd3cf23f1ba3972e2c176b603e034fe6"
+  "contentHash": "34fbd7484c6c20bd09f477dd3e78ab1ef04f41d1b263690006fcff16429b5bbc"
 }

package/skills/pipeline-fill/RESEARCH-ENGINE.md

@@ -188,7 +188,27 @@ If the prospect's company isn't already cached and Phase A produced fresh resear
    - Last-space heuristic: split on the last space. `Jane Smith` → first=`Jane`, last=`Smith`. `Jane van der Merwe` → first=`Jane`, last=`van der Merwe`.
    - **Override with Phase B canonical names** if `fetch_linkedin_data` returned them. LinkedIn's `first_name`/`last_name` fields are authoritative; the heuristic is a fallback for candidates without `linkedin_url`.
 
-2. **Call `save_person_research(first_name=..., last_name=..., company=..., linkedin_url=..., email=..., topics_of_interest=..., recent_posts=..., opening_hooks=..., role_start_date=...)`.**
+2. **Call `save_person_research(...)`.** The backend now requires you to identify the company unambiguously — pick ONE of these two paths:
+
+   **Path A (preferred): pass `company_id`.** Run `save_company_research(...)` first, capture the returned `company_id`, then pass it here.
+
+   **Path B (when Path A isn't done yet): pass `company_name` + at least one anchor.** Required anchors are any of `company_domain`, `company_website`, or `company_linkedin_url`. The data is in the LinkedIn payload you already fetched. The prospect's CURRENT employer is the entry in `work_experience[]` with `end_date: null` — that entry has `company_linkedin_url` (e.g. `https://linkedin.com/company/microsoft`). If you ran `fetch_linkedin_data(include_company=true)`, the separate company response carries `website` and `industry`. Domain can be derived from website (e.g. `microsoft.com` from `https://microsoft.com`) or from the prospect's verified work email.
+
+   **Anchor-less name-only saves are rejected with HTTP 422.** This was hardened to stop orphan stub creation in the companies table — name-only saves were silently producing duplicate rows for common names like Microsoft.
+
+   Example call:
+   ```
+   save_person_research(
+     first_name=..., last_name=...,
+     email=..., linkedin_url=...,
+     # ONE of:
+     company_id=<from save_company_research>
+     # OR:
+     company_name=..., company_linkedin_url=...,  # at least one anchor
+     # ...rest of research fields
+   )
+   ```
+
    - If the prospect already had `person_id` set on the candidate (e.g. operator pasted a Vruum person UUID), pass it explicitly: `save_person_research(person_id=..., ...)` — backend updates rather than creating a new record.
    - The response includes the `person_id`. Capture it for step c.
 

package/skills/pipeline-fill/SKILL.md

@@ -2,10 +2,10 @@
 name: pipeline-fill
 description: >-
   Source-agnostic pipeline orchestrator. Picks a source per segment (Sales Nav /
-  YC / CSV / manual list), 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, deep research before import.
+  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.
 ---
 
 ## Auto-update check
@@ -19,18 +19,18 @@ Never block skill execution on this check.
 
 # Pipeline Fill
 
-You are a source-agnostic pipeline filler. You pick segments to fill, pick a source per segment (Sales Nav / YC / CSV / manual list), and orchestrate harness deep research that gates against the segment ICP before saving prospects into the backend pipeline.
+You are a source-agnostic pipeline filler. You pick segments to fill, pick a source per segment (Sales Nav / YC / CSV / discovery), and orchestrate harness deep research that gates against the segment ICP before saving prospects into the backend pipeline.
 
 ## Why this skill exists
 
-Filling your pipeline by source-of-the-day is normal. Sales Nav drying up doesn't mean you're stuck — pick YC, paste a CSV, or paste prospects inline. This skill orchestrates deep research per prospect in your IDE (your compute), pre-filters against segment ICP, then saves the qualified ones into the segment via the backend's canonical gate.
+Filling your pipeline by source-of-the-day is normal. Sales Nav drying up doesn't mean you're stuck — pick YC, paste a CSV, or run discovery (paste candidates OR describe an ICP and the harness sources them via WebSearch + Vruum MCP + LinkedIn search). This skill orchestrates deep research per prospect in your IDE (your compute), pre-filters against segment ICP, then saves the qualified ones into the segment via the backend's canonical gate.
 
 ## Where the heavy logic lives
 
 Steps 3–8 (pre-flight, Phase A research, Phase B research, harness gate, save chain, audit-log report) are defined in `RESEARCH-ENGINE.md` (in this same skill directory). This skill owns:
 - Step 1: segment picker (with ETA)
 - Step 2: source picker (conditional PLATFORM block + always-visible HARNESS block)
-- The inline manual-list parser
+- The discovery-mode handler (paste candidates inline OR describe an ICP and source via harness tools)
 - The multi-segment grammar
 
 When you reach Step 3, **stop and read** `RESEARCH-ENGINE.md`. That doc is the canonical source for the candidate-list shape, the harness gate criteria, the identity-resolution save chain, and the canonical handoff prompt that source skills use.
@@ -103,7 +103,7 @@ Source for {segment_name}?
     1. sales-nav-deep    — Sales Nav profiles + harness deep research
     2. yc                — scrape YC directory with filters you provide
     3. csv               — read a CSV file (path next), harness deep research
-    4. list              — paste candidates inline (one per line)
+    4. discovery         — paste candidates inline OR describe an ICP and I'll source them via WebSearch + Vruum MCP + LinkedIn search
 ```
 
 The conditional rendering happens at package-build time, not at skill-runtime — when the orchestrator runs in operator mode it sees the 6-option block; when it runs in public mode (stripped package) it sees only the 4-option block. Source-skill dispatch logic below uses option labels (`sales-nav-platform`, `yc`, etc.), not numbers, so the renumbering is cosmetic.
@@ -115,13 +115,16 @@ Per source pick, dispatch:
 - `sales-nav-deep` → invoke `/sales-nav-deep-fill` to produce a candidate list, then continue to Step 3 with it.
 - `yc` → invoke `/yc-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
 - `csv` → invoke `/csv-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
-- `list` → use the inline manual-list parser below to produce a candidate list, then continue to Step 3 with it.
+- `discovery` → use the discovery-mode handler below to produce a candidate list (handler branches: paste-shaped input → parse, prose ICP brief → harness sources via WebSearch + Vruum MCP + LinkedIn search), then continue to Step 3 with it.
 
 **Multi-segment behavior:** segments run sequentially. Segment 1's Step 7 (save chain + bulk enroll) completes before segment 2's Step 3 starts. Predictable rate-limit behavior, simple progress narrative. Trade-off: 3-segment fills are ~37min wall-clock vs ~22min if Phase A/B were overlapped across segments. Cross-segment overlap is a v2.
 
-## Inline manual-list parser (for `list` source)
+## Discovery-mode handler (for `discovery` source)
 
-Operator pastes lines, one per prospect. Tolerant parser:
+Discovery mode covers two paths off the same prompt:
+
+**Path A — operator pastes candidates** (you already know who you want)
+Tolerant line parser, candidates produced directly:
 
 - **Line is a LinkedIn URL** (matches `^https?://(www\.)?linkedin\.com/in/[^/?]+/?(\?.*)?$`) → set `linkedin_url`, leave `name` and `company` null. Phase B will fill them via `fetch_linkedin_data`.
 - **Line has comma(s)** → split as `name, company[, linkedin_url][, email]`. If 4 fields, last is email. If 3 fields, last is linkedin_url IF it matches the LinkedIn URL pattern, else interpret as email if it has `@`, else treat as a 2-field line + extra junk.
@@ -131,7 +134,21 @@ Drop blank lines and lines starting with `#` (treat as comments).
 
 **Cap at 100 lines** by default. Above that, ask: "{N} prospects pasted — process all, or first M? (a/N)". Keeps operators from accidentally kicking off a 1,000-prospect harness fill.
 
-The parser produces candidates matching the canonical shape in `RESEARCH-ENGINE.md`.
+**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.
+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
+   - `mcp__vruum-local__search_linkedin_people` for company-fitting roles when the brief is people-shaped (e.g. "VPs of Eng at Series A SaaS")
+3. **Source people from each company** — for each candidate company, use `mcp__vruum-local__find_people_at_company` (Unipile-backed; respects LinkedIn rate limits) to find titles matching the segment ICP. Cap at ~5 people per company to spread the discovery surface.
+4. **Dedup against existing pipeline** — for each discovered person, check `mcp__vruum-local__search_existing_people` so you don't research someone the segment already has.
+5. **Show the discovered list to the operator** before handoff. Format: `Name (title) — Company [linkedin]`. Cap the surface at 2x daily_target so we don't over-source. Get a "go" / "drop X" before continuing.
+
+Discovery-path candidates produced in either path use the canonical shape in `RESEARCH-ENGINE.md` and feed into Step 3 the same way.
+
+**Path detection:** if the first non-comment line looks like a URL or has commas (paste-shaped), use Path A. If it's prose without URLs/commas and >40 chars, use Path B. If ambiguous, ask: "paste, or describe the ICP and I discover?"
 
 ## Workflow — Steps 3 onward