@sellable/mcp 0.1.0

package/skills/create-campaign/core/policy.md

@@ -0,0 +1,191 @@
+# Create Campaign Policy (Deterministic + Extensible)
+
+This policy is the invariant layer. Follow it even if other instructions are ambiguous.
+
+## 1) Deterministic Control Surface
+
+You are not inventing the workflow. You are executing a configured state machine.
+
+- The source of truth for steps, transitions, and required tool calls is:
+  1. `get_campaign_framework()` output
+  2. The tool results you just received
+  3. Explicit user instructions
+- If policy and framework conflict, policy wins.
+
+## 2) Required Runtime Bootstrap
+
+At the start of every `/sellable:create-campaign` run:
+
+1. Load tools (single message with multiple ToolSearch calls):
+   - `mcp__sellable__enrich_sender`
+   - `mcp__sellable__create_campaign`
+   - `mcp__sellable__update_campaign`
+   - `mcp__sellable__update_campaign_brief`
+   - `mcp__sellable__get_auth_status`
+   - `mcp__sellable__get_campaign_framework`
+   - `mcp__sellable__get_campaign_context`
+2. Call `get_auth_status({})` and store it as `auth`.
+3. If `auth.ok !== true`, stop and follow `auth.error.guidance`.
+4. Call `get_campaign_framework({ flowVersion: "v1", includePlugins: true })`.
+5. Store the response as `framework` and obey it.
+6. If the user provides `campaignId` (e.g., `cmp_...`):
+   - Call `create_campaign({ campaignId })` to get the watchUrl
+   - Then call `get_campaign_context({ campaignId, refresh: true })`
+   - Treat this as resume mode; do not create a new campaign unless asked
+
+Do not proceed until the framework is loaded.
+
+## 3) Watch Mode Protocol (Always-On)
+
+Any time you change UI state via `currentStep`, you must orient the user.
+
+After every `update_campaign({ currentStep: ... })` call:
+
+1. Say what changed.
+2. Tell them what they should now see in the watch link.
+3. In `step-by-step` mode, pause for confirmation before continuing, except after provider selection when entering provider search.
+   - Provider-search exception: if the user just approved a provider choice, continue immediately with `get_provider_prompt` + first search (no extra "is it visible?" checkpoint).
+   - In `ask-when-needed` or `autonomous` mode, continue unless a required choice is missing.
+
+Small variation is fine, but all three elements must be present.
+
+### Example Watch Mode Responses
+
+- "I moved you to provider selection. You should see that step open in the watch link now. Tell me when you see it."
+- "You are now on the Sales Navigator step. The search panel should be visible in the watch link. Let me know when it's visible."
+
+## 4) Offer to Open Watch Link (Only If Possible)
+
+Only offer to open the watch link for the user if you actually have a Chrome tool that can open URLs.
+
+Rules:
+
+- First, check tool availability (for example, via ToolSearch) for a URL-opening Chrome tool.
+- If a URL-opening tool is available, you may say: "I can open the watch link for you if you'd like."
+- If you do not have such a tool, do not mention opening the link.
+
+Never imply you opened a browser unless you actually did.
+
+## 5) Chrome Debugging Is Conditional
+
+Chrome tools are for debugging, not the happy path.
+
+Only use Chrome debugging tools when the user signals a problem, such as:
+
+- "I don't see it"
+- "Nothing changed"
+- "The page looks wrong"
+
+When debugging is needed, prefer:
+
+- `mcp__claude-in-chrome__read_page`
+- `mcp__claude-in-chrome__get_page_text`
+
+## 6) Wait States + Interaction Modes
+
+After showing the campaign watch link (brief step), ask once how they want to run the rest of setup.
+Before presenting choices, explicitly explain there are three interaction modes and that the setting controls how often you pause for confirmation:
+
+1. `step-by-step` — confirm each major step
+2. `autonomous` — use best judgment and keep momentum
+3. `ask-when-needed` — ask only when direction is missing
+
+If they do not choose clearly, default to `ask-when-needed`.
+
+When a step says to wait, you must wait.
+
+Do not continue automatically after these checkpoints:
+
+- After campaign creation (brief review)
+- After step transitions that affect the UI (`step-by-step` mode), except provider-search immediately after a confirmed provider choice
+- After lead import (`step-by-step` mode)
+
+Proceed when the user gives any affirmative response.
+
+Mode behavior:
+
+- `step-by-step`: require explicit approval for provider choice, import, and post-import transitions. Do not require an extra approval for provider preflight/search once provider choice is confirmed.
+- `autonomous`: proceed through provider preflight/search/import/confirm with best judgment; pause only when a required user decision/tool input is missing.
+- `ask-when-needed`: proceed without repetitive visibility checks; pause at branch decisions or when ambiguity could materially change outcomes.
+
+## 7) Provider Extensibility Contract
+
+Providers are configured modules. Do not hardcode provider logic when a registry exists.
+
+- Use `framework.providers` and `framework.providerRegistry`.
+- Provider selection sets BOTH:
+  - `currentStep` (UI navigation)
+  - `leadSourceProvider` (backend state)
+- Always call `get_provider_prompt` before provider search.
+
+## 8) Customization and Overrides
+
+Plugins and overrides are first-class inputs.
+
+- Treat plugin context and overrides as user-provided configuration.
+- If plugin overrides conflict with defaults, honor the overrides.
+- Never fabricate overrides or plugin context.
+
+## 9) Data Integrity (Non-Negotiable)
+
+Never hallucinate social proof, case studies, or metrics.
+
+- Use only what is present in tool results or user input.
+- If proof is missing, say "Not provided" and proceed without it.
+
+## 10) Deterministic Failure Handling
+
+If something required is missing:
+
+- Say what is missing
+- Call the tool needed to obtain it
+- Resume the state machine
+
+Do not improvise around missing required fields like `clientProspectId`.
+
+## 11) User-Directed Research Mode (Allow It)
+
+If the user specifies how they want prospect research done, treat it as a hard override.
+
+Examples:
+
+- "Use Sales Nav first, then Apollo"
+- "Only target these companies"
+- "Filter by React + Series A"
+
+Rules:
+
+- Follow their plan when it is compatible with required tools and safety rules
+- Still enforce required steps:
+  - Set `currentStep`
+  - Use watch-mode orientation + wait states
+  - Call `get_provider_prompt` before search (when applicable)
+- If their request conflicts with requirements, explain the constraint and propose the closest valid path
+
+## 12) Host Parallelism Contract (Claude + Codex)
+
+Use the same logical workflow, but route parallel execution by host capability:
+
+- If `Task` tool is available: use Task subagents for parallel research/crafting.
+- Else if `multi_tool_use.parallel` is available: batch independent tool calls through `multi_tool_use.parallel`.
+- Else: run the same units sequentially.
+
+Rules:
+
+- Keep output schema and decision logic identical regardless of backend.
+- Prefer maximal safe parallelism when calls are independent.
+- Never claim Task subagents were launched if you used tool-parallel/sequential execution.
+
+## 13) Sender Research Completion Gate (Before create_campaign)
+
+For net-new campaign creation, `create_campaign` must not run until sender research is explicitly completed.
+
+Required order:
+
+1. `enrich_sender`
+2. Company/domain confirmation
+3. `research-sender` execution
+4. `complete_sender_research({ depth, proofItemsFound, caseStudyItemsFound, credibilitySignalsFound, notes? })`
+5. `create_campaign`
+
+If the user reruns `enrich_sender`, sender research completion is stale and must be re-done before `create_campaign`.

package/skills/create-campaign/core/providers/apollo.json

@@ -0,0 +1,35 @@
+{
+  "id": "apollo",
+  "label": "Apollo",
+  "leadSourceProvider": "apollo-ai",
+  "currentStep": "apollo",
+  "promptProvider": "apollo",
+  "requiredTools": [
+    "update_campaign",
+    "get_provider_prompt",
+    "search_apollo",
+    "import_leads",
+    "wait_for_lead_list_ready",
+    "confirm_lead_list"
+  ],
+  "watch": {
+    "stepVisible": "You should see the Apollo search step open.",
+    "afterImport": "You should see Apollo leads appear in the table.",
+    "cancelAndRestart": "If the operator realizes the filter is wrong mid-import, call cancel_lead_import with { campaignOfferId, tableId, provider: \"apollo\" } and start a new search with tighter filters."
+  },
+  "recommendation": {
+    "priority": 3,
+    "useWhen": [
+      "You need technology stack targeting",
+      "You need bulk domain list targeting",
+      "You need high volume and can accept lower reply rates"
+    ],
+    "avoidWhen": ["High reply rate and LinkedIn activity are the top priority"],
+    "reason": "Best for scale and firmographic/technographic filters, but lower LinkedIn activity by default.",
+    "prose": "Since you need to find **{icp}**, I'd recommend **Apollo**.\n\nHere's why:\n- Apollo has technology filters that other sources don't\n- We can find people at companies using {techStack}\n- Heads up: reply rates will be lower since not all leads are active on LinkedIn\n\nShould I search Apollo for {techStack} users?"
+  },
+  "askOption": {
+    "label": "Apollo",
+    "description": "Large database and powerful filters (lower reply rates)"
+  }
+}

package/skills/create-campaign/core/providers/prospeo.json

@@ -0,0 +1,34 @@
+{
+  "id": "prospeo",
+  "label": "Prospeo",
+  "leadSourceProvider": "prospeo",
+  "currentStep": "prospeo",
+  "promptProvider": "prospeo",
+  "requiredTools": [
+    "update_campaign",
+    "get_provider_prompt",
+    "search_prospeo",
+    "import_leads",
+    "wait_for_lead_list_ready",
+    "confirm_lead_list"
+  ],
+  "watch": {
+    "stepVisible": "You should see the Prospeo search UI.",
+    "afterImport": "You should see Prospeo leads in the table.",
+    "cancelAndRestart": "If the operator realizes the filter is wrong mid-import, call cancel_lead_import with { campaignOfferId, tableId, provider: \"prospeo\" } and start a new search with tighter filters."
+  },
+  "recommendation": {
+    "priority": 2,
+    "useWhen": [
+      "You want Prospeo filters or domain-based search",
+      "You need high deliverability from Prospeo"
+    ],
+    "avoidWhen": ["You need LinkedIn activity filters"],
+    "reason": "Strong for Prospeo-specific filters and domain lists.",
+    "prose": "Since you're targeting **{icp}**, I'd recommend **Prospeo**.\n\nHere's why:\n- Prospeo has strong domain-based search and deliverability\n- We can find verified contacts at your target companies\n- Good for high-deliverability outreach\n\nShould I search Prospeo for {icp}?"
+  },
+  "askOption": {
+    "label": "Prospeo",
+    "description": "Prospeo search and import"
+  }
+}

package/skills/create-campaign/core/providers/registry.json

@@ -0,0 +1,31 @@
+{
+  "version": "v1",
+  "defaultProviderOrder": [
+    "signal-discovery",
+    "sales-nav",
+    "prospeo",
+    "apollo"
+  ],
+  "providers": [
+    {
+      "id": "signal-discovery",
+      "label": "Signal Discovery",
+      "configPath": "mcp/sellable/skills/create-campaign/core/providers/signal-discovery.json"
+    },
+    {
+      "id": "sales-nav",
+      "label": "Sales Navigator",
+      "configPath": "mcp/sellable/skills/create-campaign/core/providers/sales-nav.json"
+    },
+    {
+      "id": "prospeo",
+      "label": "Prospeo",
+      "configPath": "mcp/sellable/skills/create-campaign/core/providers/prospeo.json"
+    },
+    {
+      "id": "apollo",
+      "label": "Apollo",
+      "configPath": "mcp/sellable/skills/create-campaign/core/providers/apollo.json"
+    }
+  ]
+}

package/skills/create-campaign/core/providers/sales-nav.json

@@ -0,0 +1,37 @@
+{
+  "id": "sales-nav",
+  "label": "Sales Navigator",
+  "leadSourceProvider": "sales-nav",
+  "currentStep": "sales-nav",
+  "promptProvider": "sales-nav",
+  "requiredTools": [
+    "update_campaign",
+    "get_provider_prompt",
+    "search_sales_nav",
+    "import_leads",
+    "wait_for_lead_list_ready",
+    "confirm_lead_list"
+  ],
+  "watch": {
+    "stepVisible": "You should see the Sales Navigator filters and search UI.",
+    "afterImport": "You should see Sales Nav leads in the table.",
+    "cancelAndRestart": "If the operator realizes the filter is wrong mid-import, call cancel_lead_import with { campaignOfferId, tableId, provider: \"sales-nav\" } and start a new search with tighter filters."
+  },
+  "recommendation": {
+    "priority": 2,
+    "useWhen": [
+      "ICP is niche or enterprise",
+      "You need active LinkedIn users via activity filters",
+      "You have account-based targeting needs"
+    ],
+    "avoidWhen": [
+      "Signal Discovery can clearly produce enough ICP-fit engagers"
+    ],
+    "reason": "Strong default when public engagement is limited but LinkedIn activity still matters.",
+    "prose": "Since you're targeting **{icp}**, I'd recommend **Sales Navigator** with the \"Posted on LinkedIn\" filter.\n\nHere's why:\n- {icp} don't publicly engage much on LinkedIn posts\n- With Sales Nav, we filter for people who recently posted -- 4x more likely to reply\n- Better than a cold database where only ~8% are actually active\n\nShould I search for active {icp} on Sales Navigator?"
+  },
+  "askOption": {
+    "label": "Sales Navigator",
+    "description": "Filter for active LinkedIn users and ICP fit"
+  }
+}

package/skills/create-campaign/core/providers/signal-discovery.json

@@ -0,0 +1,42 @@
+{
+  "id": "signal-discovery",
+  "label": "Signal Discovery",
+  "leadSourceProvider": "signal-discovery",
+  "currentStep": "signal-discovery",
+  "promptProvider": "signal-discovery",
+  "selection": {
+    "promisingPostsTarget": 1
+  },
+  "requiredTools": [
+    "update_campaign",
+    "get_provider_prompt",
+    "search_signals",
+    "select_promising_posts",
+    "set_headline_icp_criteria",
+    "import_leads",
+    "wait_for_lead_list_ready",
+    "confirm_lead_list"
+  ],
+  "watch": {
+    "stepVisible": "You should see the Signal Discovery step with post search controls.",
+    "afterImport": "You should see Signal Discovery leads landing in the table."
+  },
+  "recommendation": {
+    "priority": 1,
+    "useWhen": [
+      "ICP is active on LinkedIn",
+      "You can name the topics they engage with",
+      "Quality and reply rate matter more than raw volume"
+    ],
+    "avoidWhen": [
+      "ICP rarely engages publicly",
+      "User needs very large volume immediately"
+    ],
+    "reason": "Best combination of activity + ICP fit when posts and engagement signals exist.",
+    "prose": "Since you're targeting **{icp}**, I'd recommend **Signal Discovery**.\n\nHere's why:\n- {icp} are very active on LinkedIn -- lots of posts about {topics}\n- We find people who engaged with content about your space\n- Warm leads: active on LinkedIn AND interested in your topics\n- 4x higher reply rates vs cold databases\n\nShould I search for posts where {icp} are engaging?"
+  },
+  "askOption": {
+    "label": "Signal Discovery (Recommended)",
+    "description": "Find active ICPs engaging with relevant posts"
+  }
+}

package/skills/create-campaign/references/brief-template.md

@@ -0,0 +1,64 @@
+# Campaign Brief Template
+
+Use this markdown template when creating the campaign brief for `create_campaign` or `update_campaign_brief`.
+
+```markdown
+# [Meeting Value] for [Target Audience]
+
+_Example: "Free Pipeline Audit for VPs of Sales" or "Custom Outreach Plan for Marketing Agencies"_
+
+## Campaign Objective
+
+Launch campaign to **[X persona]** who work at **[Y type of companies]** and offer them **[Z solution/value]**.
+
+_Example: "Launch campaign to **VPs of Marketing** who work at **Series A-C SaaS companies** and offer them **AI-powered Google Ads management that cuts CPL by 20%+**."_
+
+## Ideal Customer Profile (ICP)
+
+- **Company type:** [Specific description]
+- **Role & seniority:** [Titles and levels]
+- **Company size:** [Employee range]
+- **Geography:** [Regions]
+
+## Meeting Value (Offer)
+
+[The ONE most compelling meeting value for this audience - 2-3 sentences max. Must include:
+(1) tangible deliverable(s) (what they get in the meeting)
+(2) scope/timebox or effort required
+(3) expected outcome tied to the pain
+
+Example: "In a 15-minute call, we will audit your top 10 accounts and show where replies are stalling so your SDRs can fix it this week."]
+
+## Social Proof
+
+**CRITICAL: Use the user's answer to the Proof question. Do NOT make up or modify their answer.**
+
+**Primary Proof:** [Copy the user's Proof answer verbatim, or "Not provided - leading with problem"]
+
+## Messaging Guidelines
+
+- **Lead with:** [Hook based on their posts/news]
+- **Bridge to:** [How it connects to their pain]
+- **Avoid:** [Generic phrases to skip - "best-in-class", "industry-leading", etc.]
+- **Voice:** [Reference sender's voice from `.sellable/configs/writing/styleguide-core.md` if loaded]
+- **Outbound rules:** [Reference `.sellable/configs/writing/outbound.md` if loaded -- observation -> relevance -> ask]
+
+## Do NOT Target
+
+**Segments to avoid:**
+
+- [Competitors' customers if mentioned]
+- [Current customers]
+- [Any exclusions mentioned]
+
+## Success Metrics & Stats
+
+**Key success stories (if provided):**
+
+- [Real metrics from proof answer]
+- [Client transformations mentioned]
+
+## Additional Notes
+
+[Any other important context from the enrichment or conversation]
+```

package/skills/create-campaign/references/campaign-quality.md

@@ -0,0 +1,84 @@
+# Campaign Quality Patterns
+
+This file captures the current Sellable quality bar for campaign briefs, offers,
+and copy direction.
+
+## Gold Example Bank
+
+These are the highest-trust inspiration sources for Phase 75:
+
+- Sellable.dev internal messaging
+- Galley
+- Gelee
+- HeyDigital
+- Revvix / Spektion
+- Superposition
+- Persona Digital
+
+Use them for inspiration and contrast, not for cloning.
+
+## What Strong Campaigns Consistently Do
+
+- Clear over clever. They read smoothly on first pass.
+- Ground the offer in a real job, pain, or moment the buyer already recognizes.
+- Use specific proof only when it is real and relevant.
+- Keep the ask proportional to the prospect's level of intent.
+- Sound like a peer who understands the work, not a marketer narrating value props.
+- Make it easy for the buyer to picture what they get next.
+
+## What Weak Campaigns Consistently Do
+
+- Hide behind generic offers like "free audit" or "free assessment."
+- Ask for a call before earning enough interest.
+- Lean on vague business outcomes like "grow revenue" or "drive efficiency."
+- Sound templated, over-polished, or AI-clean.
+- Use proof as a flex instead of as context.
+- Fill space with frameworks, jargon, or named methodologies the buyer does not care about.
+
+## Brief Quality Checklist
+
+A high-quality campaign brief should:
+
+- make the target buyer feel precise, not broad
+- define the offer in concrete terms
+- explain why the angle might work now
+- separate what is known from what needs client confirmation
+- preserve real proof without inventing new proof
+- include enough copy guidance that downstream operators do not have to guess
+
+## Messaging Quality Checklist
+
+Strong message directions usually produce copy that is:
+
+- concise without sounding clipped
+- business casual, not corporate
+- specific to the target and the sender
+- easy to read aloud
+- comfortable with slight imperfection when it sounds more human
+
+## Openers To Avoid
+
+- "Quick question"
+- "I hope this finds you well"
+- cold-opening with a credential or stat
+- "Our approach:"
+- "What if"
+- "Imagine if"
+
+## High-Signal Openers To Prefer
+
+- soft, conversational first lines
+- relevant observations about the prospect, their role, or a clear signal
+- short lead-ins that earn the right to make an offer
+
+Example direction:
+
+- Better: "so this might be relevant but..."
+- Better: "not sure if this applies, but..."
+- Better: "this may be a little out of left field, but..."
+- Worse: "we help companies streamline growth with..."
+
+## Acceptance Standard
+
+If a campaign brief or message direction could be sent by five competitors with a
+name swap, it is not strong enough yet.

package/skills/create-campaign/references/copy-calibration-examples.md

@@ -0,0 +1,120 @@
+# Copy Calibration Examples
+
+Use this file to calibrate toward strong Sellable output while preserving client
+voice.
+
+## Good vs Bad Openers
+
+Good:
+
+- "so this might be relevant but..."
+- "not sure if this applies, but..."
+- "this may be a bit out of left field, but..."
+
+Why good:
+
+- softens the opening
+- sounds conversational
+- avoids cold pitch energy
+
+Bad:
+
+- "Quick question"
+- "I hope this finds you well"
+- "We help companies..."
+- opening cold with a logo, stat, or credential
+
+Why bad:
+
+- obvious outbound tell
+- feels rehearsed
+- triggers instant pitch pattern-matching
+
+## Good vs Bad Proof Usage
+
+Good:
+
+- one concrete proof point used as context
+- named proof when it matters
+- proof that supports the offer instead of replacing it
+
+Bad:
+
+- stacked logos and stats before the ask
+- vague claims like "trusted by leading brands"
+- proof used as a flex with no relevance to the buyer
+
+## Tone Calibration
+
+Target tone:
+
+- clear
+- casual but serious
+- readable aloud
+- willing to use fragments or slight imperfection
+
+Avoid:
+
+- homepage copy
+- poetic phrasing
+- colon-heavy value props
+- dash-connected slogans
+- anything that feels "too nice" instead of clear
+
+## Offer Calibration References
+
+Galley:
+
+- stronger when the output is offered before the meeting
+- weaker when the reply path immediately becomes a scheduling ask
+
+HeyDigital:
+
+- good reference for simple language, scenario framing, and readability pressure
+
+Persona Digital:
+
+- good reference for a differentiator that sounds sharp without getting gimmicky
+
+Revvix / Spektion:
+
+- good reference for category-specific credibility and restraint
+
+Superposition:
+
+- good reference for founder-story positioning and named proof discipline
+
+Sellable.dev:
+
+- good reference for smooth internal messaging, low-friction A/B asks, and peer tone
+
+## Quick Contrastive Rewrites
+
+Weak:
+
+- "We help B2B SaaS companies unlock more pipeline through differentiated outbound systems."
+
+Better:
+
+- "seems like you're already doing the hard part. the gap may just be getting the right people to actually reply."
+
+Weak:
+
+- "Would you be open to a quick call so I can show you how this works?"
+
+Better:
+
+- "happy to send over the short version if that's easier. if it looks relevant, we can walk through it live."
+
+Weak:
+
+- "Our approach: ICP-aligned content that drives qualified attention."
+
+Better:
+
+- "the difference is the attention is actually from people you'd want to sell to"
+
+## Final Check
+
+If the client would feel proud to read it and the prospect would not immediately
+clock it as a pitch, it is close. If it sounds clean but generic, keep iterating.