@sellable/mcp 0.1.0

package/skills/create-campaign/references/offer-patterns.md

@@ -0,0 +1,108 @@
+# Offer Patterns
+
+Use this file to teach the model why some offer structures outperform others.
+
+## Core Principle
+
+An offer is the specific thing that makes the prospect reply. A strong offer is
+easy to picture, low-friction relative to buyer intent, and tied to a real job
+the buyer already cares about.
+
+## Low-Friction vs High-Friction
+
+Low-friction offers usually work better earlier in the thread:
+
+- send a short teardown
+- send a one-page summary
+- send a 2-minute walkthrough
+- run one real artifact through the product and return the output
+
+High-friction offers require more intent:
+
+- book a 30-minute call
+- join a full demo
+- prepare materials before the first meeting
+- commit multiple stakeholders before value is shown
+
+## Stronger vs Weaker Structures
+
+Stronger:
+
+- give something concrete before asking for time
+- show exactly what comes back
+- offer a lightweight path and a higher-commitment path
+- tie the offer to the prospect's actual workflow or pain
+
+Weaker:
+
+- ask for time before the prospect sees value
+- describe the offer in vague terms
+- lead with a category pitch instead of a useful next step
+- rely on artificial urgency without a real reason
+
+## Option A / Option B Pattern
+
+Use this when both paths are clear and the prospect can self-select.
+
+Pattern:
+
+- Option A: passive or low-friction
+- Option B: higher-commitment live walkthrough
+
+Example shape:
+
+- A) send us one real example and we send back a short summary
+- B) if you want to see it live, we can run it together in 15 minutes
+
+Why it works:
+
+- captures early and late intent in the same message
+- lowers reply friction
+- avoids forcing every mildly interested prospect straight into a meeting ask
+
+## Galley Reference Case
+
+The Galley audit is a canonical comparison for this repo.
+
+Weaker path:
+
+- prospect replies "sounds interesting"
+- next step asks them to book time or do extra prep
+- warm interest stalls
+
+Stronger path:
+
+- offer to run one real menu rotation through the system
+- send back a one-page summary with mapped recipes, estimated margin gap, and unnecessary manual work
+- keep the live walkthrough as the higher-commitment option B
+
+Why the stronger version is better:
+
+- the prospect understands what they get back
+- the first value exchange does not depend on calendar commitment
+- the follow-up becomes about their own output, not a generic demo request
+
+## Good vs Bad Offer Framing
+
+Good:
+
+- "we can run one of your menu rotations through our system and send back the recipes that map over, the estimated margin gap, and the manual work that did not need to exist"
+- "happy to send a 2-minute walkthrough if that's easier, or we can do it live with your data"
+- "we pulled one example and turned it into a concrete output you can react to"
+
+Bad:
+
+- "free audit"
+- "free assessment"
+- "framework review"
+- "worth a quick call to walk through our process?"
+
+## When To Escalate The Ask
+
+Escalate from send-something to take-time only when:
+
+- the prospect explicitly asks to see more
+- the proof or output has already created curiosity
+- the thread indicates real buying intent
+
+If the prospect has only shown mild interest, the next step should usually stay lightweight.

package/skills/create-campaign/references/provider-selection-strategy.md

@@ -0,0 +1,212 @@
+# Provider Selection Strategy
+
+## Core Philosophy: Active + ICP = Best Leads
+
+The best leads are people who are:
+
+1. **Active on LinkedIn** (will actually see your message)
+2. **Fit your ICP** (right role, company, interests)
+
+Only ~8% of a typical Apollo list is active on LinkedIn. That's why reply rates are so low with cold databases.
+
+## Provider Decision Hierarchy
+
+### 1. Signal Discovery (TRY FIRST)
+
+Best leads because they're both active AND interested in your topics.
+
+USE WHEN:
+
+- ICP is LinkedIn-active: founders, GTM, sales, marketing, engineers, content creators
+- There are posts about topics your ICP cares about
+- You can realistically get hundreds of ICP-fit engagers from the posts
+
+SKIP WHEN:
+
+- Niche ICP that doesn't engage on LinkedIn (enterprise CTOs, procurement, etc.)
+- Hard to find posts where your specific ICP engages
+- Need very high volume (1000+ leads)
+
+EXAMPLES:
+
+- Founders -> "founder mode", "product market fit" posts = GREAT fit
+- Engineers -> specific technology posts, open source discussions = GREAT fit
+- Enterprise CTOs -> hard to find posts they engage with = SKIP, use Sales Nav
+
+### 2. Sales Navigator (DEFAULT WHEN SIGNAL DISCOVERY WON'T WORK)
+
+With POSTED_ON_LINKEDIN filter = 4x higher reply rate than cold lists.
+
+USE WHEN:
+
+- Signal Discovery won't yield enough ICP-fit engagers
+- Niche/enterprise ICP that doesn't engage publicly
+- Account-based targeting (specific companies)
+- Need active LinkedIn users but can't find via engagement
+
+WHY: POSTED_ON_LINKEDIN ensures they're active on the platform.
+
+Activity Filters (use one or both):
+
+- **POSTED_ON_LINKEDIN** (id: RPOL) - Posted recently, 4x higher reply rates
+- **RECENTLY_CHANGED_JOBS** (id: RPC) - Changed jobs recently, often in "buying mode"
+
+Sales Nav works without these filters too -- just expect lower reply rates.
+
+### 3. Apollo (LAST RESORT FOR VOLUME)
+
+Large database but leads may not be active on LinkedIn.
+
+USE WHEN:
+
+- Need technology stack filters (Salesforce users, React devs, etc.)
+- Need very high volume and accept lower reply rates
+- Other sources didn't work
+
+CAVEAT: Only ~8% of Apollo leads actively use LinkedIn. Expect lower reply rates.
+
+## Quick Decision Flow
+
+```
+Is your ICP LinkedIn-active (founders, sales, marketing, GTM, engineers)?
+  YES -> Can you find posts they'd engage with?
+    YES -> Signal Discovery (4x reply rates)
+    NO  -> Sales Navigator + POSTED_ON_LINKEDIN (4x reply rates)
+  NO  -> Sales Navigator (with or without POSTED_ON_LINKEDIN)
+
+Need tech stack targeting? -> Apollo (has technology filters)
+Have specific company names? -> Sales Navigator or Apollo with domains
+```
+
+## ICP-to-Provider Quick Reference
+
+| ICP Type                  | Recommended      | Why                                                  |
+| ------------------------- | ---------------- | ---------------------------------------------------- |
+| Founders, CEOs            | Signal Discovery | Highly active on LinkedIn, lots of founder content   |
+| Sales/GTM leaders         | Signal Discovery | Very active, tons of sales content                   |
+| Marketing leaders         | Signal Discovery | Active, lots of marketing content                    |
+| Engineers/DevOps          | Signal Discovery | Active on tech discussions, open source              |
+| Enterprise CTOs           | Sales Navigator  | Less public engagement, use POSTED_ON_LINKEDIN       |
+| Procurement/Ops           | Sales Navigator  | Rarely engage publicly                               |
+| Few specific companies    | Sales Navigator  | Use CURRENT_COMPANY filter (lookup each company)     |
+| Company domain list (ABM) | Apollo           | Has `q_organization_domains_list` for bulk targeting |
+| Tech stack users          | Apollo           | Has technology filters                               |
+
+**Default:** Try Signal Discovery first. Fall back to Sales Navigator if ICP is too niche.
+
+## ABM / Account-Based Targeting
+
+When user has a list of target companies:
+
+- **Few companies (< 20):** Use Sales Navigator with CURRENT_COMPANY filter
+
+  - Requires looking up each company individually
+  - Can combine with POSTED_ON_LINKEDIN for active users
+
+- **Many companies (domain list):** Use Apollo with `q_organization_domains_list`
+  - Supports bulk domain upload (up to 190 per search)
+  - Example: `filters: { q_organization_domains_list: ["stripe.com", "notion.so", "figma.com"] }`
+  - Trade-off: No POSTED_ON_LINKEDIN equivalent, so reply rates may be lower
+
+## Recommendation Templates
+
+Use these as starting points. The `{icp}` and `{topics}` placeholders come from campaign context.
+
+**Signal Discovery (LinkedIn-active ICP):**
+
+```
+Now let's find the right people to reach.
+
+Since you're targeting **{icp}**, I'd recommend **Signal Discovery**.
+
+Here's why:
+- {icp} are very active on LinkedIn -- lots of posts about {topics}
+- We can find people who recently engaged with content about {topics}
+- These are warm leads: active on LinkedIn AND interested in your space
+- 4x higher reply rates vs cold databases
+
+Should I search for posts where {icp} are engaging?
+```
+
+**Sales Navigator (niche/enterprise ICP):**
+
+```
+Since you're targeting **{icp}**, I'd recommend **Sales Navigator** with the "Posted on LinkedIn" filter.
+
+Here's why:
+- {icp} don't publicly engage much on LinkedIn posts
+- But with Sales Nav, we can filter for people who recently posted -- these are 4x more likely to reply
+- Better than a cold database where only ~8% are actually active
+
+Should I search for active {icp} on Sales Navigator?
+```
+
+**Apollo (tech stack targeting):**
+
+```
+Since you need to find **{icp}**, I'd recommend **Apollo**.
+
+Here's why:
+- Apollo has technology filters that other sources don't
+- We can find people at companies using {techStack}
+- Heads up: reply rates will be lower since not all leads are active on LinkedIn
+
+Should I search Apollo for {techStack} users?
+```
+
+**Apollo ABM (company domains):**
+
+```
+Since you have a **list of target companies**, I'd recommend **Apollo** with domain targeting.
+
+Here's why:
+- Apollo supports bulk domain lists (up to 190 companies per search)
+- We can find decision-makers at your exact target accounts
+- Just share the domains (e.g., stripe.com, notion.so) and I'll find your ICP at those companies
+
+Note: Reply rates may be lower than Signal Discovery or Sales Nav with POSTED_ON_LINKEDIN, since we can't filter for LinkedIn activity. Consider combining with a strong personalized message.
+
+Can you share your target company domains?
+```
+
+## AskUserQuestion Construction Rules
+
+Do not hardcode provider options. Build them from the framework:
+
+1. Compute the recommendation deterministically:
+   - If user already has a LinkedIn profile CSV on disk -> use `load_csv_linkedin_leads` to create or append to a lead list, then review before `confirm_lead_list`
+   - If user already has a company-domain CSV on disk -> use `load_csv_domains`, then continue with provider selection/search using the returned `domainFilterId`
+   - If user already has some other list shape that does not fit those CSV paths -> proceed with provider selection
+   - If the user specifies a provider or research plan -> treat that as a hard override
+   - Else if `providerPreference` override exists -> recommend that provider
+   - Else use the decision hierarchy above (Signal Discovery -> Sales Nav -> Apollo)
+2. Build options from `providerOrder` and `framework.providers[providerId].askOption`
+3. Mark the recommended option by appending " (Recommended)" if needed
+
+**AskUserQuestion shape:**
+
+```json
+{
+  "questions": [
+    {
+      "header": "Provider",
+      "question": "Which lead source would you like to use?",
+      "options": "[Construct from framework provider configs in providerOrder]",
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+**labelToProviderId map:**
+
+When building options, store a `labelToProviderId` map. After user selects, resolve `providerId` from that map (not guesswork). If missing, fall back to the first valid provider in `providerOrder`.
+
+**User-directed research plan (skip recommendation when present):**
+
+If the user gives specific research instructions (provider order, filters, target accounts, tech stack, exclusions):
+
+1. Summarize their plan in 1-3 bullets
+2. Treat it as the active override
+3. Choose the provider that best matches their instructions
+4. Proceed without re-recommending a different provider

package/skills/create-campaign/references/question-examples.md

@@ -0,0 +1,167 @@
+# AskUserQuestion Examples
+
+JSON shapes for AskUserQuestion calls throughout the campaign creation flow. Use these as templates -- replace `{placeholders}` with actual values.
+
+## Phase 1 Step 2: Confirm Company & Authorize Research
+
+```json
+{
+  "questions": [
+    {
+      "header": "Research",
+      "question": "I found you at {company} ({companyDomain}). Should I research this company for credibility, case studies, and proof?",
+      "options": [
+        {
+          "label": "Yes, research this",
+          "description": "Research {companyDomain} for the campaign"
+        },
+        {
+          "label": "Different company",
+          "description": "I'll share another domain"
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+## Phase 2: Campaign Scope
+
+```json
+{
+  "questions": [
+    {
+      "header": "Campaign Scope",
+      "question": "Do you have your own idea, or should I go ahead and draft a campaign for {companyDomain}?",
+      "options": [
+        {
+          "label": "Draft one for me",
+          "description": "Use what you found for {companyDomain}"
+        },
+        {
+          "label": "I have an idea",
+          "description": "I'll share the target + angle"
+        },
+        {
+          "label": "Different company/offer",
+          "description": "This isn't for {companyDomain}"
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+## Phase 4 Step 3: Execution Mode
+
+Preface text (show before options):
+
+```
+Before we start lead sourcing, choose how hands-on you want me to be.
+This setting controls how often I pause for confirmation:
+- Continue step by step: I ask before each major action.
+- Use best judgment: I run autonomously and pause only when required.
+- Ask when needed: I move quickly and check in at branch decisions.
+```
+
+```json
+{
+  "questions": [
+    {
+      "header": "Execution Mode",
+      "question": "Before we start lead sourcing, which interaction mode do you want?",
+      "options": [
+        {
+          "label": "Continue step by step (Recommended)",
+          "description": "Most control: I pause for approval before each major action"
+        },
+        {
+          "label": "Use best judgment",
+          "description": "Fastest: I run autonomously and pause only when required"
+        },
+        {
+          "label": "Ask when needed",
+          "description": "Balanced: I move fast and check in for branch decisions"
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+Store `interactionMode`:
+
+- "Continue step by step" -> `step-by-step`
+- "Use best judgment" -> `autonomous`
+- "Ask when needed" -> `ask-when-needed`
+- If ambiguous, default to `ask-when-needed`
+
+## Phase 5: Provider Selection
+
+Build dynamically from framework -- see `references/provider-selection-strategy.md` for construction rules.
+
+```json
+{
+  "questions": [
+    {
+      "header": "Provider",
+      "question": "Which lead source would you like to use?",
+      "options": "[Construct from framework provider configs in providerOrder]",
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+## Phase 5: Lead List Mode (existing list detected)
+
+Only shown when `import_leads` returns `needsModeSelection: true`.
+
+```json
+{
+  "questions": [
+    {
+      "header": "Lead List",
+      "question": "A lead list already exists with {existingCount} leads. Should I add to it or replace it?",
+      "options": [
+        {
+          "label": "Add to existing",
+          "description": "Append new leads to the current list"
+        },
+        {
+          "label": "Replace",
+          "description": "Archive existing leads and import fresh"
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+## Phase 5: Filter Recommendation
+
+After sampling leads, recommend one of: Add filters / Skip filters / Refine list first.
+
+Format:
+
+```
+[X] leads imported into the campaign table.
+
+I moved you to the Enable Filtering step.
+You should see the yes/no choice for ICP filtering.
+
+Recommendation: [Add filters / Skip filters / Refine list first]
+- Why: [1-2 concrete reasons tied to the lead sample + ICP]
+
+Choose whether to add ICP filters (rubric) or skip filtering, and I'll continue.
+```
+
+Guardrails:
+
+- If list is small (under ~150) or ICP is already narrow, warn that filters may leave too few leads.
+- If user asked for exclusions (competitors, geo, tech stack, ARR), call that out as a reason to filter.
+- Keep to 2-4 sentences; be candid about quality.

package/skills/create-campaign/references/token-fill-examples.md

@@ -0,0 +1,81 @@
+# Token Fill Examples
+
+Use this file when template-style personalization is in play.
+
+## Good Token Fill
+
+Good token fill feels like a human wrote the sentence after seeing the
+prospect's context.
+
+Examples:
+
+- Good: "saw you're hiring AE talent after opening the Austin office"
+- Good: "noticed your team has been talking more openly about runtime exposure"
+- Good: "looks like you're still growing through founder-led content"
+
+Why these work:
+
+- specific enough to feel grounded
+- short enough to read naturally
+- integrated into the sentence instead of pasted on top
+
+## Bad Token Fill
+
+Bad token fill sounds mechanical, creepy, or vague.
+
+Examples:
+
+- Bad: "noticed that at {{company}} you are focused on business growth"
+- Bad: "I saw your impressive background in leadership and innovation"
+- Bad: "after reviewing your LinkedIn profile in detail..."
+- Bad: "congrats on all the momentum at {{company}}"
+
+Why these fail:
+
+- generic enough to fit almost anyone
+- sound over-researched or synthetic
+- add no real relevance
+
+## Interpolation Guardrails
+
+- Do not force every token into every message.
+- If the token does not make the sentence stronger, omit it.
+- Prefer one sharp personalized detail over three weak ones.
+- Avoid praise-heavy interpolation unless there is a real reason to praise.
+- Do not use stale or doubtful facts just because they were available in context.
+
+## Smooth vs Awkward
+
+Smooth:
+
+- "not sure if this is relevant but it looks like you're pushing into enterprise accounts now"
+- "saw the post on AI exposure and thought this might actually be relevant"
+
+Awkward:
+
+- "not sure if this is relevant but according to your recent post you are pushing into enterprise accounts"
+- "I saw on LinkedIn that you recently posted about AI exposure and therefore wanted to contact you"
+
+## Persona-Specific Notes
+
+Gelee / founder targeting:
+
+- use life-stage or operator context only when it changes the offer
+- avoid overpersonalized founder flattery
+
+Superposition / founder-story positioning:
+
+- keep named proof or founder story tight
+- do not turn the sender story into a monologue
+
+Revvix / security positioning:
+
+- favor concrete category language over hype
+- technical credibility should feel matter-of-fact, not theatrical
+
+## Red Flags
+
+- the token reads like CRM metadata
+- the token makes the sentence longer without making it better
+- the token sounds like a compliment sandwich
+- the token could be swapped into any message without changing meaning

package/skills/create-campaign-brief/ARCHITECTURE.md

@@ -0,0 +1,72 @@
+# Create Campaign Brief Architecture
+
+Phase 83 is a prompt and artifact workflow, not a database write path.
+
+## Boundary
+
+`create-campaign-brief` creates one `brief.md v1` and stops. Phase 84 validates
+the brief and creates rubric assets. Phase 85 mints or executes a campaign.
+
+The command must not call campaign creation, campaign update, lead import,
+rubric write, or workflow table write tools.
+
+## Prompt Layers
+
+### Orchestrator
+
+- `SKILL.md`
+
+Defines the command, phase boundary, forbidden actions, and seven-step flow.
+
+### Step References
+
+- `references/quick-research-protocol.md`
+- `references/campaign-idea-options.md`
+- `references/icp-lock-question-bank.md`
+- `references/reference-sheet-protocol.md`
+- `references/messaging-inputs.md`
+- `references/draft-lifecycle.md`
+
+These keep the prompt loadable in smaller pieces.
+
+### Output Contract
+
+- `references/brief-template.md`
+
+Defines `brief.md v1`, customer-facing source bibliography, concise product
+bullets, tokenized copy sections, token fill rules, and the simple next-step
+flow: find leads, tighten filter, then draft message.
+
+### Reference Bank
+
+- `references/examples/MANIFEST.json`
+- `references/examples/briefs/*.md`
+
+The manifest indexes client, campaign mode, file path, and holdout behavior.
+The actual gold-standard brief template and runtime instructions come from
+Phase 75:
+
+- `references/phase75-canonical-brief-template.md`
+- `references/phase75-active-runtime-message-pack.md`
+- `references/phase75-good-brief-and-messaging-examples.md`
+
+### UAT
+
+- `scripts/run-create-campaign-brief-vps-uat.sh`
+- `scripts/mcp/sellable-create-campaign-brief-rehearsal.mjs`
+- `.planning/artifacts/uat/83-create-campaign-brief/`
+
+Hosted UAT runs on `sellable-web-mcp` with real Claude Code stream-json output
+and records stream, summary, tool calls, generated brief, score, and notes.
+
+## Design Rules
+
+- Markdown-first.
+- Evidence-first.
+- Ask only blocking questions.
+- Reference briefs are explicit and swappable in operator/runtime context.
+- Internal references never appear in customer-facing brief sections.
+- Withhold a fixture customer's own references during holdout runs.
+- Messaging stays high-level, and the brief explains the next-step order as:
+  find leads, tighten filter, then draft message.
+- Token rules are part of the brief, not a later copy-generation guess.

package/skills/create-campaign-brief/DISCUSS.md

@@ -0,0 +1,64 @@
+# Create Campaign Brief - Design Discussion
+
+Purpose: lock the contract for the standalone brief command before it is merged
+into other flows.
+
+## 1) What the user runs
+
+The logical command is:
+
+- `create-campaign-brief`
+
+It is the standalone proving surface for brief quality.
+
+## 2) Why it is separate from create-campaign
+
+Because brief quality is easier to tune when the command only has to do one
+thing well:
+
+- consume a source bundle
+- produce a client-ready brief
+- optionally emit a bounded appendix
+
+This avoids mixing brief quality with provider selection, lead import, or UI
+state transitions.
+
+## 3) Output boundary
+
+Main brief:
+
+- client-facing
+- strategy-first
+- no giant copy dump
+
+Bounded appendix:
+
+- message directions
+- opener and CTA guidance
+- token-fill examples
+- anti-pattern reminders
+
+## 4) Acceptance bar
+
+The brief should be good enough zero-shot that:
+
+- the client feels understood
+- the operator does not need to rewrite the whole thing
+- downstream message drafting has clear, stable guardrails
+
+Amplify Security is the first named acceptance case, not the only one.
+
+## 5) What should not happen here
+
+- no campaign creation
+- no provider routing
+- no hidden dependence on the old 10-section builder schema
+- no invented proof
+
+## 6) Open questions
+
+- Should the command stay internal until the acceptance harness is stronger?
+- Should the bounded appendix be persisted inside `campaignBrief.content` or as
+  a separate artifact later?
+- Which parts of the command should become MCP tools vs remain prompt-layer
+  logic?