@sellable/mcp 0.1.0

package/skills/create-campaign/FLOW_ASCII.md

@@ -0,0 +1,240 @@
+# Create Campaign MCP Flow (ASCII Audit + Streamlined Proposal)
+
+Scope: /sellable:create-campaign
+Sources: mcp/sellable/skills/create-campaign/SKILL.md, core/flow.v1.json, core/providers/_.json,
+mcp/sellable/skills/providers/_.md, mcp/sellable/src/server.ts
+
+Note: Tool names are shown without the mcp**sellable** prefix. AskUserQuestion is the UI question tool.
+
+======================================================================
+TOOL AUDIT (CREATE CAMPAIGN)
+======================================================================
+
+Bootstrap / Guardrails (required)
+
+- ToolSearch(select: ...)
+- get_auth_status
+- get_campaign_framework
+- get_campaign_context (resume, refresh)
+- get_subskill_prompt (research + handoff)
+- search_subskill_prompts (only if subskill name unclear)
+
+Discovery / Enrichment (required)
+
+- enrich_sender (returns clientProspectId, personData, companyDomain)
+
+Research (optional, parallel; only when needed)
+
+- fetch_linkedin_posts (LinkedIn posts)
+- fetch_company (company LinkedIn data)
+- WebFetch (homepage)
+- WebSearch (jobs/funding, reviews/traffic)
+
+Campaign Creation / Updates
+
+- create_campaign (requires clientProspectId + campaignBrief; offerPositioning auto-filled)
+- update_campaign (currentStep, leadSourceProvider)
+- update_campaign_brief (refine brief)
+
+Lead Sourcing
+
+- get_provider_prompt (provider-specific instructions)
+- search_signals / select_promising_posts / set_headline_icp_criteria
+- search_sales_nav
+- lookup_sales_nav_filter (Sales Nav dynamic filters)
+- search_apollo
+- import_leads
+- wait_for_lead_list_ready
+- confirm_lead_list
+- wait_for_campaign_table_ready
+
+Watch / UI / Diagnostics
+
+- AskUserQuestion
+- get_campaign_navigation_state (debug)
+- Chrome tools read_page/get_page_text (debug only)
+
+Handoff (next phase)
+
+- get_subskill_prompt (create-rubric)
+- upsert_rubric (downstream, not in this flow)
+
+======================================================================
+CURRENT FLOW (V1) - ASCII
+======================================================================
+
+[User: /sellable:create-campaign (cmp_... optional)]
+|
+v
+[ToolSearch: load required tools]
+|
+v
+[get_auth_status] --auth fail--> [Stop: show guidance; wait for "ready"]
+|
+v
+[get_campaign_framework]
+|
++--> cmp_id provided?
+| |
+| +-- yes --> [create_campaign(campaignId) -> watchUrl]
+| [get_campaign_context(refresh)]
+| [Resume via context.navState]
+| [Jump into flow at matching step]
+|
++-- no --> continue
+|
+v
+[Need LinkedIn URL? AskUserQuestion]
+|
+v
+[enrich_sender -> clientProspectId, personData, companyDomain]
+|
+v
+[Research subskill (parallel, optional)]
+|
+v
+[Ask direction]
+|\
+ | +-- "I have a direction" --> [User gives target/angle] --> (skip Q sets)
+| +-- "Lead the way" -------> [Onboarding Q set 1] -> [Onboarding Q set 2]
+|
+v
+[Generate 3 JTBD options] -> [User picks]
+|
+v
+[create_campaign (campaignBrief)]
+|
+v
+[Watch link gate] -- wait for "ready for leads" -->
+|
+v
+[update_campaign currentStep=pick-provider] -> (watch gate)
+|
+v
+[AskUserQuestion provider] -> [resolve provider]
+|
+v
+[update_campaign currentStep=provider step + leadSourceProvider] -> (watch gate)
+|
+v
+[get_provider_prompt]
+|
+v
+(Provider search path)
+|
+v
+[import_leads] -> [wait_for_lead_list_ready] -> [confirm_lead_list]
+|
+v
+[update_campaign currentStep=filter-choice] -> (watch gate)
+|
+v
+[wait_for_campaign_table_ready] -> [get_campaign_context refresh] -> [get_rows_minimal sample]
+|
+v
+[if filters=yes -> update_campaign currentStep=filter-rules] -> (watch gate)
+|
+v
+[handoff_to_subskill create-rubric]
+
+Provider search paths
+
+Signal Discovery
+search_signals
+-> select_promising_posts
+-> set_headline_icp_criteria
+-> import_leads
+-> confirm_lead_list
+
+Sales Navigator
+(lookup_sales_nav_filter as needed)
+-> search_sales_nav
+-> import_leads
+-> confirm_lead_list
+
+Apollo
+search_apollo
+-> import_leads
+-> confirm_lead_list
+
+======================================================================
+STREAMLINED FLOW (PROPOSED FAST PATH - DESIGN UPDATE)
+======================================================================
+
+Goal: reach the watch link (magic moment) ASAP while staying deterministic.
+Rules: ask only what is strictly needed; prefer user-confirm > user-question.
+
+[User: /sellable:create-campaign (cmp_... optional)]
+|
+v
+[ToolSearch + get_auth_status + get_campaign_framework]
+|
++-- cmp_id provided --> [create_campaign(campaignId) -> watchUrl]
+| [get_campaign_context(refresh)] -> resume
+|
+v
+[If LinkedIn URL missing] -> AskUserQuestion (single ask)
+|
+v
+[enrich_sender]
+|
+v
+[Ask 1 question only: "Who do you want to reach?"]
+|
+v
+[Do we already have a clear campaign angle/offer from context?]
+|\
+ | +-- yes --> (skip research)
+| |
+| +-- no --> [Minimal research (2 agents max: posts + homepage)]
+|
+v
+[Auto-pick 1 default campaign angle + draft brief]
+|
+v
+[create_campaign NOW] <-- magic moment (watch link)
+|
+v
+[Optional refinements while user reviews]
+
+- Only ask if user objects or wants options
+- update_campaign_brief if needed
+  |
+  v
+  [Auto-recommend provider + AskUserQuestion: confirm/change]
+  |
+  v
+  [update_campaign -> provider step] -> get_provider_prompt
+  |
+  v
+  [Run search + import leads] -> [wait_for_lead_list_ready] -> [confirm_lead_list]
+  |
+  v
+  [update_campaign currentStep=filter-choice] -> [wait_for_campaign_table_ready] -> [get_campaign_context] -> [get_rows_minimal]
+  |
+  v
+  [filter-rules] -> handoff to create-rubric
+
+Suggested question budget (fast path)
+
+- Required: LinkedIn URL (only if missing)
+- Required: 1 question max (ICP / who to reach)
+- Optional: Ask for campaign angle only if user wants options
+
+Research gating (fast path)
+
+- Skip research by default after ICP is known.
+- If only company domain exists, run Homepage Snapshot only.
+- If speed is priority, set research agentCount=2 (posts + homepage).
+
+======================================================================
+NOTES / DESIGN INTENT
+======================================================================
+
+- The earliest "magic moment" is the watch link returned by create_campaign.
+- create_campaign requires clientProspectId + offerPositioning + campaignBrief.
+  The fast path focuses on collecting only the brief; offerPositioning can be
+  auto-filled server-side to avoid delaying the watch link.
+- Every update_campaign step is a watch-mode gate in the current flow.
+  The fast path keeps gates but reduces question count and research scope.
+- Provider selection can be simplified to: "Recommended: X (yes/change?)".

package/skills/create-campaign/HOST-PARITY-CHECKLIST.md

@@ -0,0 +1,49 @@
+# Host Parity Checklist (Create Campaign)
+
+Use this checklist to verify Codex and Claude behavior stays aligned.
+Record factual evidence for each item.
+
+## Run Metadata
+
+- Date:
+- Operator:
+- Workspace:
+- Campaign ID (if resume):
+
+## Codex Run Checklist
+
+- [ ] Bootstrap sequence executed via `bootstrap_create_campaign`
+  - Evidence:
+- [ ] `requiredChecks` includes auth/framework/resume/subskill checks
+  - Evidence:
+- [ ] Fail-fast behavior observed when bootstrap has blockers (`Bootstrap incomplete`)
+  - Evidence:
+- [ ] `list_subskill_prompts` and `get_subskill_prompt("create-campaign")` available
+  - Evidence:
+- [ ] Provider preflight executed with `get_provider_prompt`
+  - Evidence:
+- [ ] Provider search/import blocked before preflight and allowed after preflight
+  - Evidence:
+- [ ] Resume behavior (when campaignId passed) continues from context, not new campaign creation
+  - Evidence:
+
+## Claude Non-Regression Checklist
+
+- [ ] Existing slash flow remains valid (`/sellable:create-campaign`)
+  - Evidence:
+- [ ] No additional mandatory user setup beyond prior Claude flow
+  - Evidence:
+- [ ] Required tool names remain unchanged and callable
+  - Evidence:
+- [ ] Auth guidance remains actionable when token/workspace is missing
+  - Evidence:
+- [ ] Provider gating remediation text is clear and actionable
+  - Evidence:
+- [ ] Prompt discovery fallback works when host prompt UI is limited
+  - Evidence:
+
+## Verdict
+
+- Codex parity status: PASS / FAIL
+- Claude non-regression status: PASS / FAIL
+- Follow-up actions:

package/skills/create-campaign/README.md

@@ -0,0 +1,142 @@
+# Create Campaign Framework (MVP Guide)
+
+This is the smallest clean version that is both deterministic and extensible.
+If you only read one file, read this one.
+
+## Start Here (What to do)
+
+1. Put your business context in `context/context.md`
+2. Set deterministic overrides in `context/registry.json`
+3. (Optional) Adjust provider behavior in `core/providers/*.json`
+4. Validate with `npm run validate:create-campaign-framework`
+
+That is the MVP operating loop.
+
+## Host Parity Contract (Codex + Claude)
+
+Use the same runtime sequence in both hosts:
+
+1. `bootstrap_create_campaign({ campaignId? })`
+2. If `safeToProceed !== true`, stop and resolve `blockingErrors`
+3. Continue with framework/context flow only after bootstrap passes
+
+Prompt discovery contract for hosts without prompts/list UI:
+
+- `list_subskill_prompts`
+- `search_subskill_prompts`
+- `get_subskill_prompt({ subskillName: "create-campaign" })`
+
+Provider preflight contract:
+
+- Always call `get_provider_prompt({ provider, campaignOfferId? })` before provider search/import tools.
+- Provider tools are runtime-gated until this preflight call is made.
+
+Parallel execution contract:
+
+- Claude host: use `Task` subagents for parallel research/crafting units.
+- Codex host: use `multi_tool_use.parallel` for independent tool-call batches.
+- If neither is available, run sequentially with the same output schema.
+
+## How a run works (mental model)
+
+1. `SKILL.md` calls `get_campaign_framework`
+2. The framework loader returns:
+   - Policy (`core/policy.md`)
+   - Flow (`core/flow.v1.json`)
+   - Providers (`core/providers/*.json`)
+   - Custom context + overrides (`context/*`)
+3. The skill executes the flow using those configs
+
+## Flow map (what happens and where it gates)
+
+1. Bootstrap
+   - Load tools
+   - Call `get_campaign_framework({ flowVersion: "v1", includePlugins: true })`
+2. Discovery + enrichment
+   - `enrich_sender` -> capture `clientProspectId`
+   - Parallel sender research
+   - `complete_sender_research(...)` marker before create
+3. Quick inputs
+   - Confirm identity
+   - Ask for ICP + campaign idea (proof optional)
+4. Create campaign (Gate 1)
+   - `create_campaign(...)`
+   - Provide watch link
+   - Gate: user reviews brief and confirms ready
+5. Move to provider selection (Gate 2)
+   - `update_campaign({ currentStep: "pick-provider" })`
+   - Gate: confirm they see provider selection
+6. Move to provider step (Gate 3)
+   - Use `core/providers/<id>.json` for `currentStep` + `leadSourceProvider`
+   - `update_campaign({ currentStep, leadSourceProvider })`
+   - Gate: confirm they see the provider step
+7. Provider prompt injection + search
+   - Call `get_provider_prompt({ provider: providerConfig.promptProvider })`
+   - Execute the provider's workflow
+8. Import leads -> review list -> confirm (Gate 4)
+   - `import_leads(...)` (creates lead list + starts import)
+   - `wait_for_lead_list_ready(...)`
+   - Gate: confirm the list looks right
+   - `confirm_lead_list(...)` (imports into campaign table)
+   - `update_campaign({ currentStep: "filter-choice" })` (move watch UI immediately)
+   - `wait_for_campaign_table_ready(...)` (required readiness check)
+   - `get_campaign_context({ refresh: true })` + `get_rows_minimal(...)` (sample leads for recommendation)
+9. Enable filtering (Gate 5)
+   - Gate: user chooses whether to add filters or skip
+10. Handoff
+
+- Provide watch link + status
+- If filters=yes: `update_campaign({ currentStep: "filter-rules" })` then hand off to rubric
+- If filters=no: `update_campaign({ currentStep: "messages" })` then proceed to messaging
+
+Notes:
+
+- Gates are intentional: after every `currentStep` change, the skill orients
+  the user and waits.
+- Chrome tools are only used when the user says something is wrong.
+
+## Folder structure (explains itself)
+
+- `SKILL.md` - Orchestrator (thin; not the source of truth)
+- `core/` - System-owned framework (rarely edit)
+  - `core/policy.md` - Non-negotiable rules
+  - `core/flow.v1.json` - Step graph and transitions
+  - `core/providers/registry.json` - Provider index and order
+  - `core/providers/*.json` - Provider contracts (step mapping + copy)
+- `context/` - Your space (edit these)
+  - `context/context.md` - Your default context
+  - `context/registry.json` - What is enabled + overrides
+  - `context/learnings.md` - What worked (learning log)
+  - `context/README.md` - How to customize safely
+
+## Where to change behavior (fast path)
+
+Most changes should happen here:
+
+- Add org/user context: `context/context.md`
+- Change defaults and recommendation behavior: `context/registry.json`
+
+Advanced changes:
+
+- Change provider step wiring or watch text: `core/providers/<id>.json`
+- Change global behavior: `core/policy.md`
+- Change the flow: `core/flow.v1.json`
+
+## Add a provider (extensible contract)
+
+1. Copy an existing provider file in `core/providers/`
+2. Edit `id`, `currentStep`, `leadSourceProvider`, and `askOption`
+3. Add it to `core/providers/registry.json`
+4. Validate with `npm run validate:create-campaign-framework`
+
+## Add context or overrides (customization)
+
+1. Add a context file under `context/`
+2. Register it in `context/registry.json`
+3. Put structured overrides in the registry entry
+4. Validate with `npm run validate:create-campaign-framework`
+
+## Determinism checks
+
+- `npm run validate:create-campaign-framework`
+- `npx tsc -p mcp/sellable/tsconfig.json --noEmit`