vibe-prospecting

What this skill does

# Vibe Prospecting CLI

Use the CLI: `npx @vibeprospecting/vpai@latest`. Treat every tool response as JSON.

**Cowork mode: always use this connector flow.** Before doing any work in Cowork mode, check whether the Vibe Prospecting MCP connector tools are available in your tool list (look for a tool matching the pattern `mcp__*__fetch-entities`).

If those tools are present, use the connector directly and follow its tool descriptions and schemas. If those tools are NOT present:
1. Call `mcp__mcp-registry__search_mcp_registry` with keywords `["vibe prospecting", "explorium"]`
2. Call `mcp__mcp-registry__suggest_connectors` with the UUID `1bdcb159-b6f0-4f13-bc08-fdb40b007828` and keywords `["prospecting"]`
3. Tell the user to click **Connect** on the card — the tools unlock automatically once authorized
4. **Poll until connected.** On every subsequent turn, re-check your tool list for `mcp__*__fetch-entities`. Do not start prospecting work until those tools appear. **Never** fall back to the CLI, the npm `vpai` tool, or an OAuth URL in Cowork mode — the Cowork connector store is the only path. If the user cannot connect from the suggested card, tell them to open the **connector store** and install Vibe Prospecting from there, then poll again. If tools are still missing, remind the user to connect and wait; repeat until the connector is available.

**If the CLI does not work** outside Cowork mode (e.g. `npx` unavailable, sandboxed environment, permission denied), and you are Claude, suggest the Vibe Prospecting connector to the user. The rest of this file is CLI-only. In Cowork mode, use the connector store flow above.

## Hard Rules

1. **Sample first, always.** Run the COMPLETE workflow on exactly 5 entities (`--number-of-results 5`) before any full run. That cap is a **quality gate only**: Explorium can match **many more** rows for the same filters. **Never** describe those 5 rows as the full dataset, "all results," or "what the database has." Show the sample, state clearly that it is a preview and the index has more, then after explicit approval **re-run the same CLI tool(s)** you used in the sample chain with full-scale parameters (same `--args`, session, and filters; raise caps such as **`--number-of-results`** to the user's real target where that flag applies). Run **`fetch-entities-statistics`** only when **all** of your discovery **`fetch-entities`** filters (and any supported scope flags) are valid for statistics too — see rule 8. Never auto-export. "Find 100" still means sample 5 first, then scale up after approval.
2. **`--tool-reasoning '<user wording>'`** on every real call. Use the user's request verbatim. Reuse across the whole workflow. Skip ONLY when running `<tool> --all-parameters` with no `--args`.
3. **Chain via session DB, never paste IDs.** Each step prints `session_id`, `db_path`, and `table_name`. Pass **`--session-id`** with the **`session_id`** from the prior JSON output so the next command uses the same SQLite session store. With **`--session-id`**, **`--table-name`** is **required** for **`enrich-business`**, **`enrich-prospects`**, **`fetch-businesses-events`**, and **`fetch-prospects-events`** — pass the prior step's **`table_name`** exactly. For **`match-*`** only, **`--table-name`** is optional (CLI can pick the first table with the right ID column when omitted). For **`fetch-entities`** prospects scoped to earlier companies, use **`--businesses-table-name`** plus **`--session-id`**.
4. **`--csv` only on the final step.** Intermediate steps emit JSON for chaining. Add `--csv` once, at the end.
5. **`autocomplete` first** for: `naics_category`, `linkedin_category`, `company_tech_stack_tech`, `job_title`, `business_intent_topics`, `city_region`. Use returned standardized values, not raw user wording.
6. **Never invent tool parameters.** Before the **first** `--args` execution of each distinct tool in a workflow, run `npx @vibeprospecting/vpai@latest <tool> --all-parameters` for that tool (once per tool per task unless you already printed its schema earlier in the same workflow). That command prints one JSON object to stdout: **`name`**, **`description`**, and **`inputSchema`** (the tool **input** JSON Schema). **Do this even when** the planned call matches the examples and you are not uncertain—examples can drift; the printed schema is authoritative. Run `--all-parameters` again if you change tools, filters, or shapes materially, or if anything still feels ambiguous. You may use examples and reference docs as shortcuts only **after** they align with that live schema. Build `--args` only from fields and shapes confirmed by **`inputSchema`** from `--all-parameters` (and examples when they match it).
7. **`--session-id`** is a CLI flag (not inside `--args`). Use the **`session_id`** value returned by the MCP in each prior step's JSON. Omit only on the first call in a chain.
8. **`fetch-entities-statistics` only when stats supports the full fetch.** Compare your planned **`fetch-entities`** payload to the **input schema** from **`fetch-entities-statistics --all-parameters`**. Call statistics **only if every** filter key, value shape, **`entity_type`**, and any scope you rely on (e.g. **`--session-id`** / **`--businesses-table-name`**) is accepted by the statistics tool the same way it is for **`fetch-entities`**. If any part of the discovery query is missing from the stats schema, unsupported, or would require a different shape, **skip stats** — do not call it with a partial or guessed subset. When you do call it, reuse the **same** **`--args`** filter object (and supported flags) as **`fetch-entities`**, plus **`--tool-reasoning`**. Prefer running stats **before** presenting the sample so you can headline **5 of [total]** when the response includes a usable count. When you **did not** run statistics (or stats had no usable total), present **Sample preview (5 rows)** and tell the user Explorium has **much more** matching the same filters—**do not** quote how many remain, **do not** say statistics failed or a total was unavailable, and **never** invent a number. Call stats again before a full-scale fetch **if** filters or scope changed **and** the full fetch filter set still fits statistics.

## Auth

```bash
mcp__cowork__request_cowork_directory path=~/.config/vpai
API_KEY=$(python3 -c "import json;print(json.load(open('/sessions/<session-id>/mnt/vpai/config.json'))['api_key'])")
npx @vibeprospecting/vpai@latest config --api-key "$API_KEY"
```

If the mount fails or `config.json` is missing, follow [`login.md`](references/login.md).

## Sample Gate

The sample is the **complete workflow on 5 entities**, not a fetch preview.

**Universe vs sample:** The 5 rows are a **small fixed preview** so the user can validate filters and enrichment before spending quota. The underlying match set is typically **much larger** (often thousands or more). Do not equate "we returned 5" with "only 5 exist." Ground volume with **`fetch-entities-statistics`** only when the **entire** planned **`fetch-entities`** filter set is valid for stats (rule 8); never guess a total.

1. **When the full fetch filter set is supported by statistics**, run **`fetch-entities-statistics`** with the same discovery **`entity_type`**, **`filters`**, and supported CLI flags as the upcoming **`fetch-entities`** (per rule 8). Otherwise skip stats; still tell the user Explorium has **much more** for the same filters (no numeric total, no mention of statistics gaps).
2. Fetch exactly 5 (`--number-of-results 5`).
3. Run **every** subsequent step (`match-*`, `enrich-*`, `fetch-*-events`) on those 5.
4. Show the **fully enriched final rows** as a markdown table with all useful columns.
5. Stop. Wait for approval in a new message. Then run at full scale.

NEVER stop after the fetch to ask for approval. Complete the full chain on 5 first.

Example — user says "find 100 Israeli companies, get 30 CEOs, find contact info":
- WRONG: fetch 5 companies → show table → ask "continue