@sellable/mcp 0.1.66 → 0.1.68

package/README.md

@@ -241,7 +241,11 @@ Provider preflight contract:
 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.
+- Codex host: use named custom scouts for source-angle work when subagents are
+  available: `linkedin_engagement_scout`, `sales_nav_scout`, and
+  `prospeo_contact_scout`. Use `multi_tool_use.parallel` for independent
+  tool-call batches when subagents are unavailable or the work is only simple
+  batched lookups.
 - If neither backend is available, run sequentially with the same output schema.
 
 Config path resolution (in order):

package/package.json

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

package/skills/create-campaign/SKILL.md

@@ -99,10 +99,15 @@ denominator, and sample basis.
 
 When the user has not supplied a source and multiple source angles are viable,
 scout those angles as independent branches when the host can actually do it:
-Signals / active LinkedIn posts, Sales Nav / title + company filters, and
-Prospeo / domains only when relevant. If the host runs them sequentially, do not
-claim they ran in parallel. In chat, call the downstream copy stage `message
-generation`; `message-validation.md` is only an internal proof artifact.
+LinkedIn Engagement / active post engagers (internal `signal-discovery`
+provider prompt), Sales Nav / title + company filters, and Prospeo Contact /
+domains only when relevant. In Codex, explicitly spawn the named custom scouts
+`linkedin_engagement_scout`, `sales_nav_scout`, and `prospeo_contact_scout` for
+the credible lanes; Codex does not infer subagent fan-out from generic source
+comparison wording. In Claude Code, keep using the existing Task agents under
+`.claude/agents/`. If the host runs them sequentially, do not claim they ran in
+parallel. In chat, call the downstream copy stage `message generation`;
+`message-validation.md` is only an internal proof artifact.
 
 Use rendered Markdown for user review surfaces, not fenced code blocks. Keep
 lines short, use indexed section labels and bullets, and translate internal

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

@@ -363,8 +363,18 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
   Include an `Open artifact:` link to `brief.md` before the approval question.
   The visible brief must come before local persistence chrome. After the brief
   is synthesized, render the approval-ready brief in chat before running visible
-  `mkdir`, `Write`, artifact-copy, or similar local draft setup. File/folder
-  creation is not the user's value moment; the brief is.
+  `mkdir`, `Write`, artifact-copy, or similar local draft setup. When the host
+  supports sidecar/background work, let a background writer persist `brief.md`
+  while the main thread keeps the brief review moving. If no background writer
+  is available, write `brief.md` synchronously only after the visible brief is
+  already in chat. File/folder creation is not the user's value moment; the
+  brief is.
+
+  The approval question can be based on the rendered brief in chat. Do not wait
+  for file-write chrome before asking for approval. Before lead sourcing or any
+  downstream step reads `brief.md`, reconcile that the persisted file matches
+  the visible approved brief; if the sidecar is still running, wait quietly or
+  finish the write synchronously at that boundary.
 
 - After the brief is approved or auto-confirmed, show the next progress line:
   `Cool. Now I'm going to find people who are both a good fit and likely to
@@ -422,19 +432,20 @@ should test for this campaign. Those can run in parallel and usually take
   `lead-sample.json`). Approval waits for both `lead-filter.md` and
   `message-validation.md`, then reconciles that the selected message basis rows
   still pass the final filter.
-- Parallel means real parallel execution, not optimistic progress copy. Prefer
-  product-native parallelism that works in both Claude Code and Codex:
-  independent MCP/tool calls in the same model turn, or dedicated Sellable MCP
-  tools that perform their own server-side `Promise.all` fan-out. Host subagents
-  are optional acceleration only: use Claude Task/subagents or Codex subagents
-  only when the host exposes them, policy allows them, and the user explicitly
-  asked for agent fan-out. A normal `$sellable:create-campaign` invocation is
-  not an explicit request for Codex subagents. If only parallel tool batching is
-  available, batch independent tool reads/lookups only. If real parallel
-  execution is not available or not allowed, run the same DAG sequentially and
-  use honest copy: `I’ll tighten the filter first, then draft the message from
-the same sample.` Never say `kicking off two workstreams`, `in parallel`, or
-  `background` unless parallel branches were actually launched.
+- Parallel means real parallel execution, not optimistic progress copy. For the
+  lead-source scout in Codex, explicitly spawn one named custom scout per
+  credible source lane when subagents are available: `linkedin_engagement_scout`
+  (display: LinkedIn Engagement Scout, powered by the `signal-discovery`
+  provider prompt), `sales_nav_scout` (Sales Nav Scout), and
+  `prospeo_contact_scout` (Prospeo Contact Scout). For Claude Code, keep using
+  the existing `.claude/agents/lead-explorer-*.md` Task agents. If host
+  subagents are unavailable, use independent MCP/tool calls in the same model
+  turn or dedicated Sellable MCP tools that perform server-side `Promise.all`
+  fan-out. If real parallel execution is not available or not allowed, run the
+  same DAG sequentially and use honest copy: `I’ll tighten the filter first,
+  then draft the message from the same sample.` Never say `kicking off two
+  workstreams`, `in parallel`, or `background` unless parallel branches were
+  actually launched.
 - Never run a downstream stage until the active `flow.v2.json` step's
   `requiredArtifacts` exist.
 - Never call a tool outside the active step's `allowedTools`, and never call a
@@ -590,18 +601,21 @@ Required behavior:
 - do not mutate DB-backed campaign state
 - run a real parallel source-angle scout when the source is not supplied and at
   least two viable source angles exist. Treat source scouting as independent
-  branches, then compare the outputs in `lead-review.md`. If the realistic
-  source set is Signals + Sales Nav, run both. If it is Signals + Prospeo, run
-  both. If all three are credible, run all three when the host/runtime supports
-  it.
-  - Branch A: Signals / active LinkedIn posts. Search relevant keyword lanes,
-    review finalist posts, fetch top-post engagers, and estimate warm-fit
-    volume.
+  branches, then compare the outputs in `lead-review.md`. In Codex, explicitly
+  spawn named custom subagents in the same turn: `linkedin_engagement_scout`,
+  `sales_nav_scout`, and `prospeo_contact_scout` for the credible lanes. Codex
+  does not infer this from generic "compare paths" wording. If the realistic
+  source set is LinkedIn Engagement + Sales Nav (Signals + Sales Nav), run both.
+  If it is LinkedIn Engagement + Prospeo Contact (Signals + Prospeo), run both.
+  If all three are credible, run all three when the host/runtime supports it.
+  - Branch A: LinkedIn Engagement / active LinkedIn posts (internal provider:
+    Signals / `signal-discovery`). Search relevant keyword lanes, review
+    finalist posts, fetch top-post engagers, and estimate warm-fit volume.
   - Branch B: Sales Nav / title + company filters. Run preview filters, inspect
     preview rows, and estimate scalable-fit volume.
-  - Branch C: Prospeo / domains only when the campaign has a domain/account
-    path or the user supplied domains. Estimate email/contact scale and call out
-    weaker LinkedIn activity.
+  - Branch C: Prospeo Contact / domains only when the campaign has a
+    domain/account path or the user supplied domains. Estimate email/contact
+    scale and call out weaker LinkedIn activity.
     If the host cannot run these branches in parallel, run them sequentially and
     do not claim they ran in parallel. If only one source angle is credible, say
     that and run the best primary source plus one cheap fallback/quality check

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

@@ -224,8 +224,14 @@ setting: `~/.codex/config.toml` with
 Source-angle comparison should be real, not implied. When the source is not
 supplied and multiple source angles are viable, scout Signals, Sales Nav, and
 relevant domain/contact paths as independent branches when the host can do so.
-If the host runs them sequentially, keep the output numeric but do not claim the
-source scout was parallel.
+In Codex, explicitly spawn named custom scouts in the same turn:
+`linkedin_engagement_scout` (LinkedIn Engagement Scout, backed by the
+`signal-discovery` provider prompt), `sales_nav_scout` (Sales Nav Scout), and
+`prospeo_contact_scout` (Prospeo Contact Scout) for the credible lanes. Codex
+does not infer subagent fan-out from generic "compare paths" wording. In Claude
+Code, keep using the existing Task agents under `.claude/agents/`. If the host
+runs them sequentially, keep the output numeric but do not claim the source
+scout was parallel.
 
 Only promise parallel post-lead work when parallel work actually started. If the
 host cannot or should not launch background branches, say the real sequence:

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

@@ -162,12 +162,17 @@
             "Risks",
             "After approval"
           ],
-          "mustRunBefore": ["write_artifact", "Bash", "mkdir"],
+          "mustRunBefore": ["start_background_artifact_writer", "Bash", "mkdir"],
           "chatRenderRule": "After synthesizing the brief, render the approval-ready brief in chat before any visible local folder creation, file write, or artifact copy. The user should see useful brief content before local persistence chrome. Do not ask the user to approve a hidden artifact."
         },
         {
-          "action": "write_artifact",
-          "artifact": "brief.md"
+          "action": "start_background_artifact_writer",
+          "artifact": "brief.md",
+          "mode": "sidecar_when_host_supports_background_agents",
+          "shouldNotBlockMainThread": true,
+          "allowedToRunWhileUserReviewsInlineBrief": true,
+          "fallback": "If no background writer is available, write brief.md synchronously only after the approval-ready brief is already visible in chat.",
+          "chatRenderRule": "Do not surface folder/file-write progress in chat unless the write fails or the user asks. The main thread should keep the brief review moving while the sidecar persists brief.md."
         },
         {
           "action": "ask_source_intake_after_strategy_batch",
@@ -254,7 +259,7 @@
           ],
           "minimumVisibleBriefDetail": "full_readable_brief_before_question",
           "requiredArtifactLinks": ["brief.md"],
-          "artifactLinkTiming": "before_approval_question",
+          "artifactLinkTiming": "when_ready_before_downstream",
           "avoidQuestionWhenOnlyUsefulAnswerIs": "looks good"
         },
         {
@@ -265,9 +270,16 @@
             "noOpenStrategicTradeoff": true,
             "noMissingRequiredInputs": true
           }
+        },
+        {
+          "action": "ensure_background_artifact_ready",
+          "artifacts": ["brief.md"],
+          "requiredBeforeTransition": "find-leads",
+          "reconcileRule": "Before lead sourcing reads brief.md, verify the sidecar persisted the same brief shown in chat. If the sidecar is still running, wait quietly or finish the write synchronously; if it differs, reconcile to the visible approved brief.",
+          "chatRenderRule": "Do not block the brief approval question on this step. Only mention artifact persistence if it fails or needs user action."
         }
       ],
-      "requiredArtifacts": ["brief.md"],
+      "requiredArtifacts": [],
       "producesArtifacts": [],
       "allowedTools": [
         "AskUserQuestion",
@@ -329,7 +341,7 @@
           "action": "run_subskill",
           "target": "find-leads",
           "mode": "campaignless-preview",
-          "sourceScoutRule": "When source is not user-supplied and at least two viable source angles exist, scout independent source angles with product-native parallelism when host/tooling permits: independent MCP/tool calls in the same model turn or dedicated Sellable MCP tools that perform server-side fan-out. Signals active-post branch + Sales Nav title/company branch, Signals + Prospeo when domains/accounts are relevant, or all three when credible. Do not rely on Codex subagents for a normal $sellable:create-campaign invocation; use host subagents only when the user explicitly asked for agent fan-out. If real parallel execution is unavailable, run the same scouts sequentially and do not claim parallel execution. Compare outputs by raw volume, n/N sampled fit, estimated good-fit range, expected reply range, and tradeoff. Keep Signals as viable when selected posts can produce ~150+ ICP-fit warm prospects before final filtering, even if Sales Nav is more scalable; when both are viable, present the choice and recommend the stronger default."
+          "sourceScoutRule": "When source is not user-supplied and at least two viable source angles exist, scout independent source angles with real parallelism when host/tooling permits. In Codex, explicitly spawn one named custom scout per credible lane in the same turn: linkedin_engagement_scout for LinkedIn Engagement / active post engagers (internal signal-discovery provider prompt), sales_nav_scout for Sales Nav title/company/activity filters, and prospeo_contact_scout for Prospeo account/domain/contact expansion. In Claude Code, use the existing .claude/agents/lead-explorer-*.md Task agents. Fallback to independent MCP/tool calls in the same model turn or dedicated Sellable MCP tools that perform server-side fan-out. Run LinkedIn Engagement + Sales Nav, LinkedIn Engagement + Prospeo Contact, or all three when credible. If real parallel execution is unavailable, run the same scouts sequentially and do not claim parallel execution. Compare outputs by raw volume, n/N sampled fit, estimated good-fit range, expected reply range, and tradeoff. Keep Signals/LinkedIn Engagement as viable when selected posts can produce ~150+ ICP-fit warm prospects before final filtering, even if Sales Nav is more scalable; when both are viable, present the choice and recommend the stronger default."
         },
         {
           "action": "write_artifacts",
@@ -467,7 +479,7 @@
             "parallel only if real parallel branches were launched"
           ],
           "timeEstimate": "~2-3 min",
-          "chatRenderRule": "If real parallel MCP/tool branches or explicitly requested host subagents were actually launched, say: 'I’m kicking off two workstreams now' and list 'Tighten the fit filter' and 'Message generation'. If not, do not mention parallel/background work; say: 'I’ll tighten the filter first, then run message generation from the same approved brief and sample leads.' Never claim parallelism unless parallel execution actually started. A normal $sellable:create-campaign invocation is not an explicit request for Codex subagents. User-facing stage name is message generation; message-validation.md is only the internal artifact."
+          "chatRenderRule": "If real parallel MCP/tool branches or host subagents were actually launched, say: 'I’m kicking off two workstreams now' and list 'Tighten the fit filter' and 'Message generation'. If not, do not mention parallel/background work; say: 'I’ll tighten the filter first, then run message generation from the same approved brief and sample leads.' Never claim parallelism unless parallel execution actually started. User-facing stage name is message generation; message-validation.md is only the internal artifact."
         },
         {
           "action": "ask_continue_revise_or_confirm_only_if_needed",

package/skills/find-leads/SKILL.md

@@ -65,7 +65,19 @@ The kickoff doc is the resume surface. Re-open it before repeating discovery wor
 
 ## Execution Backend Routing
 
-- If `Task` is available, deep exploration uses the file-backed explorer agents:
+- If Codex subagents are available, run the scout lanes with named custom
+  agents. Spawn one agent per credible lane in the same turn, then wait for all
+  lane results before synthesizing `lead-review.md`:
+  - `linkedin_engagement_scout` (display: LinkedIn Engagement Scout) for
+    active LinkedIn posts and engagers; internally this uses the
+    `signal-discovery` provider prompt plus `search_signals` /
+    `fetch_post_engagers`.
+  - `sales_nav_scout` (display: Sales Nav Scout) for Sales Navigator title,
+    company, geography, and activity filters.
+  - `prospeo_contact_scout` (display: Prospeo Contact Scout) for Prospeo
+    account/domain and verified-contact expansion.
+- If Claude `Task` is available, deep exploration uses the existing file-backed
+  Claude explorer agents:
   - `./.claude/agents/lead-explorer-signals.md`
   - `./.claude/agents/lead-explorer-sales-nav.md`
   - `./.claude/agents/lead-explorer-prospeo.md`
@@ -236,10 +248,12 @@ Use the existing provider tools to run a small, directional probe:
 If the first probe is weak or noisy and enough context exists, try 1-2 alternate hypotheses before returning.
 If the first probe has good quality but insufficient scale, iterate 1-2 times to widen intelligently before returning.
 When two or more source angles are viable, run the provider probes in real
-parallel when the host/runtime allows it. Examples: Signals + Sales Nav,
-Signals + Prospeo, or Sales Nav + Prospeo. If the host cannot run them in
-parallel, run the same probes sequentially and do not claim they ran in
-parallel.
+parallel when the host/runtime allows it. For Codex, explicitly spawn the
+named source scout agents above; Codex will not infer subagent fan-out from
+general "compare sources" wording. Examples: LinkedIn Engagement + Sales Nav,
+LinkedIn Engagement + Prospeo Contact, or Sales Nav + Prospeo Contact. If the
+host cannot run them in parallel, run the same probes sequentially and do not
+claim they ran in parallel.
 
 Treat refinement as a measured loop: