@sellable/mcp 0.1.31 → 0.1.33

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

@@ -1064,11 +1064,17 @@ proof:`, `p.s. useful proof:`, `p.s. proof:`, or `p.s. social proof:`.
   `{{psLine}}`, and do not use `{{recent_signal_quote}}`; use fields that exist
   on the enriched prospect row instead.
 - the live body under `## Approved Message Template` must be sender-ready copy.
-  Do not include bracketed instruction placeholders such as `[ROW BRIDGE ...]`,
-  `[insert ...]`, `[generated ...]`, or prose that tells a later step to
-  paraphrase/fill a line. Put per-row generation rules in `## Token Fill Rules`
-  with concrete enriched-row fields, and copy approved good/bad examples into
-  `## Token Fill Examples`, or route to `revise-messaging`.
+  Bracketed text in the body is allowed only when it is a fully-specified
+  AI-native token (`[ALL_CAPS_NAME — Intent. DO: ... DON'T: ... FALLBACK:
+omit the line.]` — see
+  `mcp/sellable/skills/create-campaign/references/ai-native-tokens.md` for the
+  contract). Bracketed instruction placeholders that lack a contract are
+  BLOCKED — including `[ROW BRIDGE ...]`, `[insert ...]`, `[generated ...]`,
+  and any prose that defers per-row composition to a later step without
+  giving the model the rules. Either upgrade the placeholder to a full
+  AI-native token (Intent / DO / DON'T / FALLBACK), put the per-row rules in
+  `## Token Fill Rules` with concrete enriched-row fields, or route to
+  `revise-messaging`.
 - `approval-packet.md` and the live campaign brief passed to `create_campaign`
   must include `## Approved Message Template`, `## Token Fill Rules`, and
   `## Token Fill Examples`. `## Token Fill Examples` must copy the approved
@@ -1391,25 +1397,39 @@ Exact sequence:
    `campaignBrief.content` contains `{{...}}`; without this marker it will
    use full-generation mode and may rewrite the approved message.
    The live template body must contain only sender-ready copy plus supported
-   `{{tokens}}`; no bracketed instructions or placeholder prose may appear in
-   the body.
-   Include `## Token Fill Rules` for every enriched-prospect-row token in the
-   template. Tokens may be row fields such as `{{first_name}}`,
-   `{{company}}`, `{{role}}`, `{{headline}}`, `{{profile_summary}}`,
-   `{{post_context}}`, `{{comment_summary}}`, `{{source_post_topic}}`, or
-   `{{row_proof_note}}` when those exact fields are supported by the
-   row/enrichment data. Do not document static sender identity, product name,
-   proof points, casing style, `{{recent_signal_quote}}`, or abstract slot
-   tokens such as `{{hookLine}}`, `{{painLine}}`, `{{productLine}}`,
-   `{{closeLine}}`, or `{{psLine}}`.
-   Include `## Token Fill Examples` copied from the approved message review and
-   validation artifacts. It must preserve `Good token fill:`, `Good omit:`,
-   `Bad token fill:`, `Why bad:`, `Fallback if missing:`, and
-   `Token fill basis:` so the minted campaign brief teaches future row
-   generation how to fill tokens, what fills are blocked, and what to do when
-   row data is missing. If the brief does not contain `## Token Fill Rules` and
-   `## Token Fill Examples`, do not call `create_campaign`; route back to
-   message review or approval packet generation.
+   tokens. Two token shapes are allowed:
+   - `{{snake_case}}` field-substitution tokens for atomic values that drop
+     directly into a fixed slot (greeting, subject, company name).
+   - `[ALL_CAPS_NAME — Intent. DO: ... DON'T: ... FALLBACK: omit the line.]`
+     AI-native tokens for personalization sentences. The bracket carries
+     the contract inline; the model writes a sentence (or omits the line)
+     per the inline rules. Full spec:
+     `mcp/sellable/skills/create-campaign/references/ai-native-tokens.md`.
+     No other bracketed placeholders are allowed — bracketed prose without an
+     explicit Intent / DO / DON'T / FALLBACK contract (e.g., `[ROW BRIDGE]`,
+     `[insert ...]`, `[generated ...]`) is BLOCKED because it leaves the
+     per-row generation under-specified.
+     Include `## Token Fill Rules` for every token in the template. Field
+     tokens may be row fields such as `{{first_name}}`, `{{company}}`,
+     `{{role}}`, `{{headline}}`, `{{profile_summary}}`, `{{post_context}}`,
+     `{{comment_summary}}`, `{{source_post_topic}}`, or `{{row_proof_note}}`
+     when those exact fields are supported by the row/enrichment data. AI-native
+     tokens are listed in the rules table by name and type with a pointer back
+     to the inline contract (the rules themselves live inside the bracket — do
+     not duplicate them in the table). Do not document static sender identity,
+     product name, proof points, casing style, `{{recent_signal_quote}}`, or
+     abstract slot tokens such as `{{hookLine}}`, `{{painLine}}`,
+     `{{productLine}}`, `{{closeLine}}`, or `{{psLine}}` — those are abstract
+     slots without a contract; convert them to AI-native bracket tokens with
+     real Intent / DO / DON'T / FALLBACK clauses, or cut them.
+     Include `## Token Fill Examples` copied from the approved message review and
+     validation artifacts. It must preserve `Good token fill:`, `Good omit:`,
+     `Bad token fill:`, `Why bad:`, `Fallback if missing:`, and
+     `Token fill basis:` so the minted campaign brief teaches future row
+     generation how to fill tokens, what fills are blocked, and what to do when
+     row data is missing. If the brief does not contain `## Token Fill Rules` and
+     `## Token Fill Examples`, do not call `create_campaign`; route back to
+     message review or approval packet generation.
 3. Call `bootstrap_create_campaign({ flowVersion: "v2" })`. Respect
    `safeToProceed`; on blocking errors, surface and stop.
 4. Call

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

@@ -102,7 +102,6 @@
           "allowedTools": [
             "list_senders",
             "get_sender",
-            "enrich_sender",
             "fetch_company",
             "fetch_linkedin_profile",
             "WebFetch",
@@ -174,7 +173,6 @@
         "get_active_workspace",
         "list_senders",
         "get_sender",
-        "enrich_sender",
         "complete_sender_research",
         "fetch_company",
         "fetch_company_posts",

package/skills/generate-messages/SKILL.md

@@ -1139,6 +1139,44 @@ yours` are not enough when a safe row token would make the line feel more
   version sounds like mail merge. A good token should either make the sentence
   more concrete in normal language or be omitted. If the row signal is weak,
   write the segment-level line and document the omit rule.
+- **No product-noun substitution in possessive frames (HARD INVARIANT):** when
+  a token sits inside a possessive frame like `your {{X}}`, `at your {{X}}`,
+  or `because of your {{X}}`, the filled value MUST describe something the
+  recipient personally **does** — their work, focus, or activity. It must NOT
+  describe a product their company **builds or sells**. Grammar test: read
+  `your <filled-value>` out loud. If it reads as if the recipient _uses_ or
+  _has_ the thing, but they actually _build/sell_ the thing, the fill is wrong
+  → OMIT the entire sentence. Examples: `your monetization layer for AI
+builders` (BLOCKED — product description from the company), `your Moneyball
+dashboard for CEOs` (BLOCKED — the recipient builds this product, doesn't
+  have one of their own), `your AI scoring engine` (BLOCKED — product), vs
+  `your monetization research for AI founders` (ALLOWED — buyer activity),
+  `your founder-led-sales experiments` (ALLOWED — activity), `your GTM
+Engineering writing` (ALLOWED — what they do publicly). The omit-fallback
+  is the safe default. Aggressive omit > awkward fill. Do NOT substitute
+  generic nouns (`your work`, `your stack`, `your team`) — those add no
+  relevance and read as mail merge.
+- **AI-native tokens — write the sentence, don't fill the slot (HARD
+  INVARIANT):** when the message template contains a bracketed instruction
+  token of the form \`[ALL_CAPS_NAME — instructions]\`, that placeholder is
+  NOT a field-substitution slot. It is an inline instruction. Read the
+  contents of the bracket. The bracket will name an Intent, DO shapes,
+  DON'T shapes, and a FALLBACK clause. Your job: COMPOSE a complete
+  sentence (or sentences, if the intent calls for it) that satisfies all
+  the DO rules and avoids all the DON'T rules, then replace the bracket
+  with that rendered sentence. If you cannot satisfy the DOs cleanly from
+  the row data, REPLACE THE BRACKET WITH NOTHING (the entire line is
+  omitted, including any leading/trailing whitespace; the surrounding
+  message must read cleanly without it). Aggressive omit > awkward fill.
+  Never leave the bracket itself in the rendered output. Never substitute
+  a placeholder, ellipsis, or generic noun (\`your work\`, \`your team\`)
+  when the FALLBACK clause says omit. Canonical example from the runtime
+  gold pack: \`[PERSONALIZED REASON — their team size, role, or why
+  they're a perfect fit]\` — the model picks whichever input the row supports
+  and writes one short sentence in the sender's voice. Full spec:
+  \`references/ai-native-tokens.md\`. The \`[ALL_CAPS_NAME — ...]\` shape
+  is reserved for AI-native tokens; field substitutions stay as
+  \`{{snake_case}}\` and continue to work as direct value injections.
 - **No internal profile-signal token:** `{{profile_signal}}` is never allowed
   in customer-facing copy, message-review templates, rendered examples, token
   notes, or approval-packet message bodies. It names how enrichment classified

package/skills/research-sender/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: research-sender
-description: Parallel-first sender research protocol. One round of batched tool calls, ~10-15s wall time.
+description: "Parallel-first sender research protocol. One round of five batched tool calls (fetch_linkedin_profile + fetch_company + 3× WebSearch), no enrich_sender required, ~30-40s wall time."
 visibility: internal
+allowed-tools: mcp__sellable__fetch_linkedin_profile mcp__sellable__fetch_company mcp__sellable__complete_sender_research WebSearch ToolSearch
 ---
 
 # Research Sender (Parallel-First)
@@ -12,28 +13,36 @@ This protocol is standalone and does not depend on the generic `research` subski
 ## Core Idea — Don't Wait, Fan Out
 
 Old protocol: call `enrich_sender` → wait for partial → maybe spawn 2-3 subagents → wait.
-That's 3-4 sequential rounds and ~60s+ wall time.
+That's 3-4 sequential rounds and ~88s+ wall time.
 
-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.
+New protocol: **fire one parallel batch.** No `enrich_sender` precondition.
+`fetch_linkedin_profile` (sender background), `fetch_company` (company description /
+industry / employees), and 3× `WebSearch` (proof, growth, positioning) all run in the
+same window. They finish in ~10-15s if truly parallel, ~30-40s when the model
+serializes (interactive mode is best-effort, headless `claude -p` always serializes).
 
-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.
+Then synthesize once into the campaign brief — the brief is what downstream
+message generation reads, not a `clientProspect` row. `clientProspectId` is
+optional in `create_campaign`; pass `senderLinkedinUrl` instead.
 
 ## Inputs
 
 Provide as many as available. Use `"Unknown"` for missing values.
 
-- `linkedinUrl` (REQUIRED)
+- `linkedinUrl` (REQUIRED — drives `fetch_linkedin_profile`)
 - `name`
 - `title`
 - `companyName`
-- `companyDomain` (REQUIRED for WebSearch — derive from email or LinkedIn if absent)
+- `companyDomain` (REQUIRED — drives `fetch_company` and all three WebSearch queries; derive from email or LinkedIn if absent)
 - `headline` (optional)
 
+## Execution Backend Routing
+
+This skill runs differently depending on the host:
+
+- **Claude Code host:** the parallel batch uses MCP tools directly — `mcp__sellable__fetch_linkedin_profile`, `mcp__sellable__fetch_company`, and `WebSearch`. Issue all five calls as `tool_use` blocks in a single assistant message.
+- **Codex host:** if MCP `fetch_*` tools are not available, fall back to web-fetch equivalents — use the LinkedIn URL with WebFetch for the sender profile, fetch the company's `/about` page for company facts, and use the same three WebSearch queries below for proof / growth / positioning. Synthesis treats both backends identically.
+
 ## Setup: Pre-Load Deferred Tools (One-Time, Before The Parallel Batch)
 
 Some hosts (Claude Code with deferred-tool fetch) require `WebSearch` and
@@ -41,27 +50,28 @@ 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:
 
-`ToolSearch({ query: "select:WebSearch,mcp__sellable__enrich_sender,mcp__sellable__complete_sender_research", max_results: 5 })`
+`ToolSearch({ query: "select:WebSearch,mcp__sellable__fetch_linkedin_profile,mcp__sellable__fetch_company,mcp__sellable__complete_sender_research", max_results: 5 })`
 
 Skip this turn entirely if the tools are already directly callable.
 
 ## The One Round (Parallel Batch)
 
-**HARD RULE:** the four tool calls below MUST be emitted as **four `tool_use`
+**HARD RULE:** the five tool calls below MUST be emitted as **five `tool_use`
 content blocks inside a single assistant message** (one turn, parallel
 execution). Do NOT split them across multiple assistant messages.
 
-Concretely, your next assistant message must contain exactly these four
+Concretely, your next assistant message must contain exactly these five
 `tool_use` blocks, in any order, with no leading or trailing prose:
 
-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. `fetch_linkedin_profile({ linkedinUrl })` — sender's LinkedIn profile (firstName/lastName, currentCompany, experience, follower count, education) for the brief's "sender background" section.
+2. `fetch_company({ companyDomain })` — sender's company LinkedIn page (description, industry, employee range, recent posts). REQUIRED — replaces what `enrich_sender` used to provide for `companySnapshot`.
+3. `WebSearch({ query: 'site:{companyDomain} ("case study" OR "customer story" OR testimonial OR "success story") "{companyName}"' })` — proof.
+4. `WebSearch({ query: '"{companyName}" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR launch OR "press release")' })` — growth/credibility.
+5. `WebSearch({ query: '"{companyName}" about product site:{companyDomain}' })` — positioning.
 
-**Self-check before you reply:** if your reply contains fewer than four
+**Self-check before you reply:** if your reply contains fewer than five
 `tool_use` blocks (after the optional `ToolSearch` setup turn), you are
-violating the protocol. Stop, rewrite the reply with all four.
+violating the protocol. Stop, rewrite the reply with all five.
 
 **Known limitation (`claude -p` headless mode):** Claude often serializes
 these calls one-per-turn even with explicit instructions. That's fine — the
@@ -69,35 +79,63 @@ 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.
 
-No subagent fan-out. No second round of enrichment polling.
+No subagent fan-out. No second round of enrichment polling. **No `enrich_sender` call.**
 
 ## Synthesis (Single Pass After Batch Returns)
 
-Merge the four results. Treat `enrich_sender` as the authoritative baseline
-for company/sender facts; treat WebSearch as proof and signals.
+Merge the five results into the campaign brief. Treat `fetch_linkedin_profile` and
+`fetch_company` as authoritative for sender/company facts; treat `WebSearch` as
+proof and signals.
 
 ```markdown
 ## {Company} - Sender Research
 
-**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)]
+**Sender Background:** [from fetch_linkedin_profile — name, current title, follower count, key experience]
+**Company Context:** [from fetch_company.description OR positioning WebSearch top result]
+**Industry / Size:** [from fetch_company.industry + employee range]
+**Positioning Notes:** [positioning WebSearch top results + any positioning one-liner from fetch_company]
+**Proof Options:** [case-study WebSearch hits — pick 1-3 with named customers / metrics]
+**Credibility Signals:** [growth WebSearch hits (funding, hiring, press) + any high-signal posts from fetch_company]
 **Gaps:** [what's still missing — usually fine to ship with this]
 ```
 
-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.
+The synthesis result is what feeds the campaign brief, which is what message
+generation reads via `campaignBriefContent` (see `getOfferPositioning()` in
+`prompt.ts:236`). The brief is the load-bearing path now — `clientProspect`
+contributes only fallback context and the sender display name (which is
+resolved from the `Sender` row's profileData when `clientProspect` is null).
+
+### Partial Failure Handling
+
+The five calls run in parallel, so any one of them can fail independently
+(404, rate-limit, timeout). Synthesis MUST still produce a usable brief.
+Apply these rules:
+
+- **If `fetch_company` errors or returns empty:** mark `Company Context` as
+  `[unavailable — fetch_company failed]`. Use the positioning WebSearch top
+  result as a partial substitute. Set `Industry / Size` to `[unavailable]`
+  (do NOT guess). The brief still ships; downstream message generation reads
+  the brief verbatim and is null-safe on missing fields.
+- **If `fetch_linkedin_profile` errors:** fall back to WebSearch-derived
+  sender background. Set `Sender Background` to a one-liner derived from the
+  positioning WebSearch ("found via {companyDomain}/about and other web
+  signals — full LinkedIn profile unavailable").
+- **If a WebSearch errors:** mark the corresponding section
+  (`Proof Options`, `Credibility Signals`, or `Positioning Notes`) as `[no
+results]` and continue. Do NOT retry — one round only.
+- **NEVER skip `complete_sender_research`** even on partial failure. Pass
+  `proofItemsFound: 0`, `caseStudyItemsFound: 0`, `credibilitySignalsFound: 0`
+  for the failed sections so the preflight knows the research ran.
+
+**The contract:** synthesis always produces SOME brief. `complete_sender_research`
+always fires. The brief ships even with gaps; downstream is null-safe.
 
 ## Optional Deepen (Only If Synthesis Reveals A Hard Gap)
 
 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.
+the proof WebSearch. Cap at one WebFetch. No subagents, no second WebSearch round.
 
 If that still yields nothing, set `proofItemsFound: 0` in
 `complete_sender_research` and proceed; the brief can ship without proof.
@@ -122,7 +160,7 @@ If no reliable evidence is found, set counts to 0 and include that in `notes`.
 Before issuing the parallel batch:
 
 ```
-Pulling sender enrichment + case studies + growth signals + positioning in parallel (~10s)...
+Pulling sender profile + company snapshot + case studies + growth signals + positioning in parallel (~10s)...
 ```
 
 After synthesis:
@@ -133,7 +171,11 @@ Sender research ready — {proofItemsFound} proof items, {credibilitySignalsFoun
 
 ## What Changed From The Previous Protocol
 
+- **Removed `enrich_sender` from the parallel batch entirely.** The MCP `create_campaign` tool now accepts `senderLinkedinUrl` as an alternative to `clientProspectId`. `enrich_sender` itself has been removed from the MCP tool registry — calling it returns "tool not found".
+- Replaced with `fetch_company` (REQUIRED) — provides company description, industry, employee data that `enrich_sender` used to give via `companySnapshot`.
+- Five parallel tool calls instead of four (added `fetch_linkedin_profile` + `fetch_company`, dropped `enrich_sender`).
+- Added explicit Partial Failure Handling — synthesis always produces a brief even when one or two of the five calls error.
 - 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.
+- No subagent fan-out — WebSearch from the orchestrator turn is faster and cheaper.
+- Synthesis writes to the campaign brief, not to an `EnrichedProspect` row.
 - One round, one synthesis, one `complete_sender_research` call.