@sellable/mcp 0.1.28 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-campaign-v2/SKILL.md

@@ -873,34 +873,40 @@ Orchestration requirements:
   before category nouns like `platform` or `MCP`.
 - pass the Thomas revision filters before writing findings
 - immediately after `message-validation.md` is confirmed and reconciled with
-  `lead-filter.md`, write `message-review.md` and render it inline starting
-  with `Status: message-review` as the first visible line. Do not put a
-  markdown heading, preface, or summary before that status line. This is a
-  customer checkpoint, not an audit report: show the approved campaign message
-  template first, then show one filled sample prospect version immediately after
-  it so the user can judge whether the tokens are being used correctly. Then
-  show rendered examples that prove the tokens fill well and can be omitted
-  cleanly when row data is weak. Keep the detailed
-  gold-standard/rule audit inside `message-validation.md`, not in the
-  user-facing review. The review must use this exact label shape so the gate can
-  be parsed: `Subject: ...`, `Tokenized template: ...`, `Sample prospect fill:
-  ...`, `Rendered examples: ...`, `Good token fill: ...`, `Good omit: ...`,
-  `Bad token fill: ...`, `Why bad: ...`, `Fallback if missing: ...`,
-  `Token notes: ...`, `My take: ...`, `Suggested adjustment: ...`,
-  `Question: approve-message or revise-messaging?`, `Recommendation:
-approve-message|revise-messaging`.
-- Never ask the message approval question until the full message review is
-  visible in the chat. A summary like `Message review is ready` or `the draft
-avoids a generic pitch` is not enough. The user must see the actual subject,
-  the actual tokenized message template, one filled sample prospect version, at
-  least one good filled example, one good omit example, one bad fill example,
-  why the bad fill is wrong, fallback rules for missing row data, token notes,
-  your take, and the suggested adjustment before any `approve-message` /
-  `revise-messaging` question appears. If you catch yourself wanting to offer
-  `show me message` as a choice, stop: render the message review first, then ask
-  only `approve-message` or `revise-messaging`.
-  Include `Open artifacts:` links to `message-review.md` and
-  `message-validation.md` before the approval question.
+  `lead-filter.md`, write `message-review.md` and render the slim chat version
+  inline starting with `Status: message-review` as the first visible line. Do
+  not put a markdown heading, preface, or summary before that status line.
+  This is a customer checkpoint optimized for fast approve / revise judgment.
+- Chat-vs-file split (this is the rule the user pinned):
+  - `message-review.md` (the file) keeps the full detail: `Status:
+message-review`, `Subject:`, `Tokenized template:`, `Sample prospect fill:` + `Token fill basis:`, `Rendered examples:`, `Good token fill:`,
+    `Good omit:`, `Bad token fill:`, `Why bad:`, `Fallback if missing:`,
+    `Token notes:`, `My take:`, `Suggested adjustment:`, `Question:
+approve-message or revise-messaging?`, `Recommendation:
+approve-message|revise-messaging`. The detailed gold-standard/rule audit
+    stays in `message-validation.md`. Both files are unchanged in scope and
+    are still required.
+  - The chat rendering shows ONLY: `Status: message-review`, `Subject:`,
+    `Tokenized template:`, `Sample prospect fill:` (with `Token fill basis:`),
+    `My take:`, `Suggested adjustment:`, `Question: approve-message or
+revise-messaging?`, `Recommendation:`. Then `Open artifacts:` links to
+    `message-review.md` and `message-validation.md` so the user can read the
+    full token guidance, good/omit/bad examples, and fallbacks if they want
+    to before deciding.
+  - Do NOT inline `Rendered examples:`, `Good token fill:`, `Good omit:`,
+    `Bad token fill:`, `Why bad:`, `Fallback if missing:`, or `Token notes:`
+    in chat. Those exist in the file and are linked. Keeping them out of
+    chat is what makes the gate easy to approve or revise on.
+- Never ask the message approval question until the slim chat review is fully
+  visible. A summary like `Message review is ready` or `the draft avoids a
+generic pitch` is not enough. The user must see the actual subject, the
+  actual tokenized message template, one filled sample prospect version with
+  its token fill basis, your take, and the suggested adjustment before any
+  `approve-message` / `revise-messaging` question appears. If you catch
+  yourself wanting to offer `show me message` as a choice, stop: render the
+  slim chat review first, then ask only `approve-message` or
+  `revise-messaging`. Include `Open artifacts:` links to `message-review.md`
+  and `message-validation.md` before the approval question.
 - `My take:` and `Suggested adjustment:` are mandatory customer-facing decision
   fields, not optional summary text. They must appear after `Token notes:` and
   before the question in every rendered message review. They must each be

package/skills/create-campaign-v2/core/flow.v2.json

@@ -605,25 +605,23 @@
             "subject",
             "tokenized template",
             "sample prospect fill",
-            "rendered examples",
-            "bad token examples",
-            "token notes",
             "my take",
             "suggested adjustment",
             "question",
             "recommendation"
           ],
           "mustRenderInlineBeforeQuestion": true,
-          "minimumVisibleMessageDetail": "full_message_review_before_question",
+          "minimumVisibleMessageDetail": "tokenized_template_plus_sample_fill_only",
           "requiredArtifactLinks": [
             "message-review.md",
             "message-validation.md"
           ],
           "artifactLinkTiming": "before_approval_question",
-          "requiredLabels": [
+          "requiredFileLabels": [
             "Subject:",
             "Tokenized template:",
             "Sample prospect fill:",
+            "Token fill basis:",
             "Rendered examples:",
             "Good token fill:",
             "Good omit:",
@@ -636,6 +634,18 @@
             "Question: approve-message or revise-messaging?",
             "Recommendation:"
           ],
+          "requiredChatLabels": [
+            "Status: message-review",
+            "Subject:",
+            "Tokenized template:",
+            "Sample prospect fill:",
+            "Token fill basis:",
+            "My take:",
+            "Suggested adjustment:",
+            "Question: approve-message or revise-messaging?",
+            "Recommendation:"
+          ],
+          "chatRenderRule": "Show ONLY the tokenized template and one filled sample prospect version (with Token fill basis), then My take, Suggested adjustment, Question, Recommendation, and Open artifacts links. Do NOT inline Rendered examples, Good token fill, Good omit, Bad token fill, Why bad, Fallback if missing, or Token notes — those live in message-review.md and message-validation.md only.",
           "allowedRecommendations": ["approve-message", "revise-messaging"],
           "judgeAgainst": [
             "generate-messages rules",
@@ -670,13 +680,7 @@
             "Subject:",
             "Tokenized template:",
             "Sample prospect fill:",
-            "Rendered examples:",
-            "Good token fill:",
-            "Good omit:",
-            "Bad token fill:",
-            "Why bad:",
-            "Fallback if missing:",
-            "Token notes:",
+            "Token fill basis:",
             "My take:",
             "Suggested adjustment:",
             "Recommendation:"

package/skills/research-sender/SKILL.md

@@ -1,120 +1,106 @@
 ---
 name: research-sender
-description: Enrichment-first sender research protocol. 0-3 agents, 30s target.
+description: Parallel-first sender research protocol. One round of batched tool calls, ~10-15s wall time.
 visibility: internal
 ---
 
-# Research Sender (Enrichment-First)
+# Research Sender (Parallel-First)
 
 Use this subskill when creating campaigns and you need sender/company research.
 This protocol is standalone and does not depend on the generic `research` subskill.
 
-## Core Architecture
+## Core Idea — Don't Wait, Fan Out
 
-`enrich_sender` compact mode already returns `companySnapshot`, `senderBackground`, and `proofDigest`.
-Four of the old five research agents duplicated this data. Only Growth Signals + Case Studies are net-new.
-When `companySnapshot.description` is missing/thin, we also run a tiny positioning snippet pass (1 WebSearch) so we don't end up with blank company context.
+Old protocol: call `enrich_sender` → wait for partial → maybe spawn 2-3 subagents → wait.
+That's 3-4 sequential rounds and ~60s+ wall time.
 
-**This protocol uses enrichment as the baseline and only spawns extra work when proof or positioning context is missing.**
+New protocol: **fire one parallel batch.** `enrich_sender` (5-8s, returns
+`clientProspectId` + baseline) runs alongside 2-3 `WebSearch` calls. They all
+finish in the same ~10s window, then you synthesize.
+
+The `enrich_sender` call is still required because downstream tools
+(`create_campaign`, `attach_sequence`, message generation) need the
+`clientProspectId` it produces and the cached `EnrichedProspect` row it writes.
+Don't skip it — just stop waiting for it before doing the rest of the research.
 
 ## Inputs
 
 Provide as many as available. Use `"Unknown"` for missing values.
 
+- `linkedinUrl` (REQUIRED)
 - `name`
 - `title`
 - `companyName`
-- `companyDomain`
-- `companyLinkedinUrl` (optional)
-- `linkedinUrl` (optional)
+- `companyDomain` (REQUIRED for WebSearch — derive from email or LinkedIn if absent)
 - `headline` (optional)
-- `enrichSender` response (REQUIRED — must include `companySnapshot`, `senderBackground`, `proofDigest`)
-
-## Depth Decision (Deterministic — from proofDigest)
-
-Check the `proofDigest` from the `enrich_sender` compact response:
-
-### `minimal-verification` (0-1 agent, 0-1 web calls, ~2-10 seconds)
-
-**Condition:** `proofDigest.caseStudyCount > 0` AND `proofDigest.reviewHighlight` exists (not null)
 
-- Do NOT spawn proof/growth agents (Case Studies, Growth Signals).
-- If `companySnapshot.description` is missing/thin, spawn the **Company Positioning** agent (1 WebSearch, no WebFetch).
-- Synthesize directly from enrichment data (companySnapshot + senderBackground + proofDigest) plus Agent 3 if used.
-- Call `complete_sender_research()` immediately with enrichment counts.
-- ~0 additional tokens.
+## Setup: Pre-Load Deferred Tools (One-Time, Before The Parallel Batch)
 
-### `deep-proof` (2-3 agents in parallel, max 5 tool calls total, ~30 seconds)
+Some hosts (Claude Code with deferred-tool fetch) require `WebSearch` and
+some MCP tools to be loaded via `ToolSearch` before they can be invoked. If
+they are not already directly callable, issue this once as the first tool
+call, on its own:
 
-**Condition:** `proofDigest.caseStudyCount === 0` OR `proofDigest.reviewHighlight` is null
+`ToolSearch({ query: "select:WebSearch,mcp__sellable__enrich_sender,mcp__sellable__complete_sender_research", max_results: 5 })`
 
-- Spawn exactly **2 agents in parallel** (Case Studies + Growth Signals).
-- If `companySnapshot.description` is missing/thin, also spawn **1 positioning agent** (Company Positioning) in parallel.
-- Homepage, Company LinkedIn, Reviews → all covered by enrichment, skip these entirely.
-- ~100k tokens total.
+Skip this turn entirely if the tools are already directly callable.
 
-## Positioning Context (Conditional — from companySnapshot.description)
+## The One Round (Parallel Batch)
 
-If `companySnapshot.description` is null/undefined or shorter than ~120 characters, run the **Company Positioning** agent (1 WebSearch, no WebFetch).
+**HARD RULE:** the four tool calls below MUST be emitted as **four `tool_use`
+content blocks inside a single assistant message** (one turn, parallel
+execution). Do NOT split them across multiple assistant messages.
 
-## Execution Backend Routing
+Concretely, your next assistant message must contain exactly these four
+`tool_use` blocks, in any order, with no leading or trailing prose:
 
-Choose backend once:
+1. `enrich_sender({ linkedinUrl, companyDomain })` — baseline + `clientProspectId`.
+2. `WebSearch({ query: 'site:{companyDomain} ("case study" OR "customer story" OR testimonial OR "success story") "{companyName}"' })` — proof.
+3. `WebSearch({ query: '"{companyName}" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR launch OR "press release")' })` — growth/credibility.
+4. `WebSearch({ query: '"{companyName}" about product site:{companyDomain}' })` — positioning.
 
-1. If `Task` is available: use Task subagents in parallel (Claude host).
-2. Else if `multi_tool_use.parallel` is available: batch independent tool calls (Codex host).
-3. Else: run units sequentially.
+**Self-check before you reply:** if your reply contains fewer than four
+`tool_use` blocks (after the optional `ToolSearch` setup turn), you are
+violating the protocol. Stop, rewrite the reply with all four.
 
-Never claim Task subagents were used when they were not.
+**Known limitation (`claude -p` headless mode):** Claude often serializes
+these calls one-per-turn even with explicit instructions. That's fine — the
+skill still produces the same output, just with sequential tool execution
+(~30–40s total wall time vs. ~10–15s if truly parallelized). If you can
+batch, do; if not, proceed sequentially without retrying or re-prompting.
 
-## Agent Prompts (when needed)
+No subagent fan-out. No second round of enrichment polling.
 
-### Agent 1: Case Studies + Proof (max 3 tool calls)
+## Synthesis (Single Pass After Batch Returns)
 
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Case studies and proof",
-  "prompt": "Find 1-3 concrete proof items for {companyName} ({companyDomain}).\n\nUse only: WebSearch, WebFetch.\n\nTool budget:\n- 1 WebSearch\n- Up to 2 WebFetch (only if the page looks like a case study/testimonial with named customers or metrics)\n\nWebSearch query (run exactly once):\nsite:{companyDomain} (\"case study\" OR \"customer story\" OR testimonial OR results OR \"success story\") \"{companyName}\"\n\nWebFetch: pick up to 2 results that look most likely to contain named customers or metrics.\nIf a fetched page is JS-heavy/empty, skip it and use snippets.\nDo not do a second search.\n\nReturn EXACTLY:\n---\nPROOF_OPTIONS: [Up to 3 items. Each: customer + outcome/metric + timeframe if present; or 'None found']\nSOURCES: [Short source hints]\n---\nKeep under 120 words. No extra commentary."
-}
-```
-
-### Agent 2: Growth/Credibility Signals (max 1 tool call)
+Merge the four results. Treat `enrich_sender` as the authoritative baseline
+for company/sender facts; treat WebSearch as proof and signals.
 
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Growth and credibility signals",
-  "prompt": "Find recent growth/credibility signals for {companyName} ({companyDomain}).\n\nUse only: WebSearch.\nTool budget: 1 WebSearch.\n\nWebSearch query (run exactly once):\n\"{companyName}\" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR \"we're hiring\" OR launch OR announcement OR \"press release\")\n\nReturn EXACTLY:\n---\nHIRING: [Notable signals or 'None found']\nFUNDING: [Round, amount, date or 'None found']\nPRESS: [Recent announcement or 'None found']\n---\nKeep under 90 words. No extra commentary."
-}
-```
-
-### Agent 3: Company Positioning (max 1 tool call)
+```markdown
+## {Company} - Sender Research
 
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Company positioning context",
-  "prompt": "If the enrichment company description is missing/thin, pull a crisp positioning summary for {companyName} ({companyDomain}) using only search snippets.\n\nUse only: WebSearch.\nTool budget: 1 WebSearch.\n\nWebSearch query (run exactly once):\n\"{companyName}\" about product site:{companyDomain}\n\nReturn EXACTLY:\n---\nPOSITIONING: [1-2 sentences]\nICP: [1 short line, or 'Unknown']\nDIFFERENTIATORS: [Up to 3 short bullets, or 'Unknown']\nSOURCES: [Short source hints]\n---\nKeep under 90 words. No extra commentary."
-}
+**Company Context:** [companySnapshot.description OR positioning WebSearch top result]
+**Industry / Size:** [companySnapshot.industry + employeeRange]
+**Positioning Notes:** [proofDigest.positioningOneLiner + keyDifferentiators]
+**Proof Options:** [proofDigest.caseStudySummary + case-study WebSearch hits — pick 1-3 with named customers / metrics]
+**Credibility Signals:** [proofDigest.reviewHighlight + growth WebSearch hits (funding, hiring, press)]
+**Gaps:** [what's still missing — usually fine to ship with this]
 ```
 
-## Synthesis (Orchestrator — No Agents)
+If `enrich_sender` returns `enrichmentStatus: "partial"`, that's expected and
+fine — `companySnapshot` and `senderBackground` are populated immediately.
+`proofDigest` may be null on partial; in that case rely on WebSearch results
+for proof and credibility, not on a second enrichment poll.
 
-After agents return (or immediately for minimal-verification), merge enrichment baseline + agent findings:
+## Optional Deepen (Only If Synthesis Reveals A Hard Gap)
 
-```markdown
-## {Company} - Sender Research
+If after synthesis you genuinely have zero proof and zero credibility
+signals, AND the campaign fixture/operator told you proof is required, you
+MAY issue ONE additional WebFetch on the most promising case-study URL from
+batch step 2. Cap at one WebFetch. No subagents, no second WebSearch round.
 
-**Company Context:** [companySnapshot.description OR Agent 3 POSITIONING] + [companySnapshot.industry + employeeRange]
-**Positioning Notes:** [proofDigest.positioningOneLiner + keyDifferentiators + Agent 3 DIFFERENTIATORS (if present)]
-**Proof Options:** [proofDigest.caseStudySummary + agent upgrades if deep-proof]
-**Credibility Signals:** [proofDigest.reviewHighlight + agent growth signals if deep-proof]
-**Gaps:** [what's missing]
-```
+If that still yields nothing, set `proofItemsFound: 0` in
+`complete_sender_research` and proceed; the brief can ship without proof.
 
 ## Completion Marker (Required)
 
@@ -124,7 +110,7 @@ After synthesis, call:
 
 Count rules:
 
-- `depth`: "minimal-verification" or "deep-proof"
+- `depth`: always `"parallel-batch"` for this protocol.
 - `proofItemsFound`: number of concrete proof items you would confidently use.
 - `caseStudyItemsFound`: number of usable case-study examples.
 - `credibilitySignalsFound`: number of trust signals (reviews/ratings/funding/hiring/press).
@@ -133,26 +119,21 @@ If no reliable evidence is found, set counts to 0 and include that in `notes`.
 
 ## Progress UX
 
-If launching deep-proof agents:
-
-```
-Running a quick research pass for case studies and growth signals (~30s)...
-```
-
-If also launching the Company Positioning agent:
+Before issuing the parallel batch:
 
 ```
-Running a quick research pass for case studies, growth signals, and positioning (~30s)...
+Pulling sender enrichment + case studies + growth signals + positioning in parallel (~10s)...
 ```
 
-If only launching the Company Positioning agent:
+After synthesis:
 
 ```
-Pulling a quick positioning summary from search snippets (~10s)...
+Sender research ready — {proofItemsFound} proof items, {credibilitySignalsFound} credibility signals.
 ```
 
-If skipping agents (minimal-verification):
+## What Changed From The Previous Protocol
 
-```
-Enrichment already has strong proof — synthesizing directly from baseline data.
-```
+- No "minimal-verification vs deep-proof" branch. Always run the same parallel batch.
+- No spawn of `general-purpose` subagents for research — WebSearch from the orchestrator turn is faster and cheaper.
+- No waiting on `enrich_sender` before issuing WebSearch.
+- One round, one synthesis, one `complete_sender_research` call.