@sellable/mcp 0.1.127 → 0.1.129

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

@@ -50,8 +50,10 @@ template, senderIds, sequence template, and running state.
 There is no separate approval-packet, commit-gate, or mint step in the active
 shell-first flow. The campaign exists early for watch mode. The hard boundary
 is import/enrichment: no leads are imported, no workflow cells are queued, no
-sequence is attached, and nothing starts until the source is selected, rubrics
-are saved, and the approved message set is synced into the campaign brief.
+sequence is attached, and nothing starts until the source is selected, filter
+choice is resolved, rubrics are saved when filters are enabled, and Messages
+has either approved template/token rules or selected the product's AI-generated
+path.
 </objective>
 
 <files>
@@ -96,8 +98,8 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   state. Use `create-offer` for the brief, `pick-provider` or the selected
   provider step while sourcing, `filter-choice` after the 15-row review batch is
   imported, `messages`/`auto-execute-messaging` for message work,
-  `validate-sample` for the 15-row validation cascade, and
-  `awaiting-user-greenlight` for Settings. Do not advance `currentStep` backward.
+  `awaiting-user-greenlight` for Settings, and `validate-sample` only for
+  recovery/legacy validation if reached. Do not advance `currentStep` backward.
 - After the shell is minted, normal resume paths read the CampaignOffer first.
   Use debug files to explain or reconstruct work, not to decide whether a
   post-mint gate is allowed. validation/debug artifacts are not durable campaign
@@ -442,11 +444,12 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
   not given a specific source direction, use the default sequential source
   funnel:
   `Cool. I'm going to find people who are both a good fit and active enough to
-be worth a LinkedIn test. I'll start with warm LinkedIn post engagement because
-that gives the strongest message context if enough ICP-looking people are
-engaging. If that does not clear a quick viability check, I'll switch to Sales
-Nav with recent activity, then broader Sales Nav, and use Prospeo only as the
-fallback. No leads import until you approve the source.`
+be worth a LinkedIn test. I'll start with people engaging with relevant LinkedIn
+posts because that gives the strongest message context if enough ICP-looking
+people are engaging. If that does not clear a quick viability check, I'll switch
+to Sales Nav to find ICP people actively posting on LinkedIn, then search by
+titles, and use Prospeo for a broader account/contact path. No leads import
+until you approve the source.`
   The watched campaign should still be on Pick Provider while this source logic
   is being explained. If the default first lane is Signal Discovery, say clearly
   that Codex is about to test Signal Discovery as a viability path, not import
@@ -463,19 +466,23 @@ fallback. No leads import until you approve the source.`
   - explicit compare request -> compare only the requested sources
 - In watch mode, do not skip the Pick Provider checkpoint. First move the
   campaign to `pick-provider` and narrate the source-selection reasoning there.
-  After that visible checkpoint, move the campaign to the first source lane that
-  will actually be tested (`signal-discovery`, `sales-nav`, `prospeo`, or the
+  While the watched browser is still on Pick Provider, ask for approval before
+  starting Signal Discovery or a user-directed first lane. After that visible
+  checkpoint and approval, move the campaign to the first source lane that will
+  actually be tested (`signal-discovery`, `sales-nav`, `prospeo`, or the
   user-directed lane), then run the campaign-attached provider prompt + provider
   search in the parent thread with `campaignOfferId`, `confirmed: true`, and
-  `currentStep` when the tool accepts it. If that lane fails the quick viability
-  gate, update the campaign step and watchNarration before trying the next lane
-  so the user sees the source switch happen in the app.
+  `currentStep` when the tool accepts it. If that lane has timeout/error, zero
+  raw results, weak ICP fit, or weak message context, update the campaign step
+  and watchNarration before trying the next approved lane or ask the user to
+  revise the source/target before import. All lanes failed is a terminal
+  revise-source state, not an import state.
 - After the lead sample/source decision is ready and approved,
   show the next progress line:
   `Lead source is set. I'll import the first 15-row review batch into the
-campaign table, then add fit filters and draft the first message from that same
-sample. You can inspect filters once they are saved, but enrichment and message
-checks wait until the message draft is ready and approved.`
+campaign table, then ask you to Choose filters or skip. I may let the Message
+Draft Builder prepare a template in the background, but template review waits
+until the filter choice is resolved and you choose Use Template.`
 - During long post-intake work, show concise progress checkpoints before the
   next expensive stage: source being checked, source switch/tradeoff if any,
   lead sample usable, filter/message drafting, and message-review rule loading.
@@ -517,17 +524,19 @@ checks wait until the message draft is ready and approved.`
   candidate messages and element tests, but it cannot select the final winner
   and cannot override `lead-filter.md`.
 - `message-validation.md` is the internal validation artifact produced by the
-  user-facing `message generation` stage.
+  Message Draft Builder / `message generation` stage. It is provisional until
+  the user answers filter choice and then chooses Use Template in Messages.
 - `message-review.md` and `message-review-decision.md` are the mandatory
   message quality gate outputs between `message-validation.md` and
   `approval-packet.md`.
 - Run the dependency chain as a DAG: `create-campaign-brief` -> `find leads` ->
   bounded import/confirm. Once the source decision, lead sample, and campaign
-  table `workflowTableId` exist, the normal path is the
-  `post-lead-workstreams` step. Launch `filter leads` and `message generation`
-  from the same basis (live campaign brief, source decision, lead sample, and
-  the imported review-batch rows) as separate workstreams when the host exposes
-  the named Sellable post-find-leads agents or real background work.
+  table `workflowTableId` exist, the normal path is the `filter-choice` user
+  gate. If the user chooses filters, `post-lead-workstreams` launches filter
+  leads and can let the Message Draft Builder run from the same basis (live
+  campaign brief, source decision, lead sample, and the imported review-batch
+  rows) as separate workstreams when the host exposes the named Sellable
+  post-find-leads agents or real background work.
   First call `get_post_find_leads_scout_registry` and use the returned
   canonical `name` values only when those names are available in the current
   runtime. In Claude Code, use both returned Task/Agent subagents in the same
@@ -538,14 +547,19 @@ checks wait until the message draft is ready and approved.`
   context. Do not surface agent install status to the customer. The existing
   `filter-rubric` and `message-generation` steps remain focused retry and
   resume targets.
-- Message generation does not need `lead-filter.md` to start. The moment the
-  bounded review batch is imported and `workflowTableId` is ready, start the
-  message-generation workstream from the live campaign brief, source decision,
-  lead sample, and the imported campaign table sample. It can prepare
-  proof inventory, token strategy, and candidate angles while filter-leads
-  tightens keep/exclude rules. Approval still waits for both `lead-filter.md`
-  and `message-validation.md`, then reconciles that the selected message basis
-  rows still pass the final filter.
+- Message generation does not need `lead-filter.md` to start, but it is only
+  background template drafting until the user reaches Messages. The moment the
+  bounded review batch is imported, `workflowTableId` is ready, and the user is
+  on/after filter choice, the Message Draft Builder may start from the live
+  campaign brief, source decision, lead sample, and imported campaign table
+  sample. It can prepare proof inventory, token strategy, and candidate angles
+  while filter-leads tightens keep/exclude rules. Template review cannot start
+  until filter choice is answered and the user chooses Use Template. If filters
+  are enabled, template review is locked until rubrics are saved, a bounded
+  filter run has usable passing/probably passing rows, and the draft reconciles
+  to those rows. Prefer at least 2 usable passing rows; if only 1 passes, show
+  weak-sample copy and ask whether to continue, revise, import more, or skip
+  filters.
   If a legacy/resume host starts message prep from preview rows before import,
   it still needs at least 3 probable good-fit rows and must reconcile the final
   winner against the imported review batch before message review.
@@ -557,29 +571,19 @@ checks wait until the message draft is ready and approved.`
   provisional candidate work from probable good-fit rows in `lead-sample.json`,
   but the final `message-validation.md` winner must cite basis rows from
   `lead-sample.json` that still pass `lead-filter.md`.
-- Parallel means real parallel execution, not optimistic progress copy. For the
-  lead-source scout, first call `get_source_scout_registry` and use the
-  returned canonical `name` values. In Codex, explicitly spawn one named custom scout per
-  credible source lane when those subagents are visible in the current runtime:
-  `source-scout-linkedin-engagement`
-  (display: LinkedIn Engagement Scout, powered by the `signal-discovery`
-  provider prompt), `source-scout-sales-nav` (Sales Nav Scout), and
-  `source-scout-prospeo-contact` (Prospeo Contact Scout). For Claude Code,
-  invoke the generated `source-scout-*` Task/Agent subagents for all credible
-  lanes in one assistant message only when the session exposes those names.
-  They are installed from the same canonical Sellable agent registry and carry
-  explicit Sellable MCP tool allowlists when `@sellable/install` is active. The
-  parent thread should not preload every provider prompt before spawning scouts;
-  each scout loads only its own provider prompt. If host subagents are
-  unavailable or the names are not visible, use the same provider probes via
-  independent MCP/tool calls in the parent thread or dedicated Sellable MCP
-  tools that perform server-side `Promise.all` fan-out. Do not write "source
-  scout agents are not installed" or similar host status into customer-facing
-  output. 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. Source
+  scouting is sequential by default: start with the first recommended lane from
+  `flow.v2.json`, usually Signal Discovery / LinkedIn engagement. Only launch
+  multiple named source scouts when the user explicitly requested comparison, a
+  prior lane failed, or the active flow marks the first lane borderline. The
+  fallback order is plain: use Sales Nav to find ICP people who are actively
+  posting on LinkedIn; if that is not enough, search Sales Nav by titles; if
+  that is still not enough, use Prospeo for a broader account/contact path.
+  Before any source scout dispatch, call `get_source_scout_registry` and use the
+  returned canonical `name` values. The parent thread should not preload every
+  provider prompt; each scout loads only its own provider prompt. Do not write
+  "source scout agents are not installed" or similar host status into
+  customer-facing output.
 - Source scout parallelism must not hide all provider work from the watch UI.
   The parent thread owns the first visible provider search: call the chosen
   provider prompt/search with the minted CampaignOffer id and provider
@@ -612,15 +616,31 @@ workstreams`, `in parallel`, or `background` unless parallel branches were
 batch`, and a no-launch safety note. Do not leave the guide saying
   `source approved` or `I'll show the review-batch outcome` once import is
   starting.
-- After Lead Fit Builder saves rubrics, move the watched browser to Filter
-  Leads before waiting for message work to finish. Persist
-  `enableICPFilters: true`, `currentStep: "apply-icp-rubric"`, and
-  `watchNarration.stage: "fit-message"` so the user can see fit filtering
-  happen while the first message sample finishes. After message approval,
-  persist `useMessagingTemplate: true` and keep `enableICPFilters: true`;
-  sample validation then runs the review-batch cascade, and the user should be
-  walked through fit results, generated message results, and
-  Settings/sender/sequence handoff.
+- After the bounded review batch is present, update the watched browser to
+  `currentStep: "filter-choice"` with `watchNarration.stage: "fit-message"` and
+  ask the user to Choose filters or skip. If import succeeds but row readback
+  returns zero rows, do not move to filter choice; keep the user in source/import
+  recovery and ask whether to retry import, import more from the approved
+  source, or revise source. Active filtering starts only after rubrics are
+  saved; do not say filtering the batch before rubrics are saved.
+- When the user chooses filters, immediately persist `enableICPFilters: true`
+  and `currentStep: "create-icp-rubric"` so the watched app leaves the filter
+  choice screen and shows that Codex is defining the rules in chat. After Lead
+  Fit Builder saves rubrics, move the watched browser to Filter Leads before
+  waiting for message work to finish. Persist `currentStep:
+"apply-icp-rubric"` and `watchNarration.stage: "fit-message"`, then read the
+  bounded review batch with `get_rows_minimal`, queue only pending/error
+  `enrichCellId` values with `queue_cells`, and then wait for rubric results
+  with at least one passing row. Do not call `check_rubric` in the normal
+  create-campaign-v2 path. The next user-facing Messages screen must show mode
+  choice first: Use Template and AI Generated. Use Template is recommended. AI
+  Generated is an explicit opt-out that cancels or ignores the background
+  template draft and must not let late template output overwrite campaign
+  state. Product Generate Message cells should not run from the background
+  template path until template/token rules are approved. After message approval,
+  update the campaign brief with an Approved Message Template containing
+  `{{...}}` tokens and keep `enableICPFilters: true`; Generate Message detects
+  template mode from those tokens, not from `useMessagingTemplate`.
 - During pre-import validation, do not call `check_rubric`; use the lead-filter
   artifacts and only use campaign-backed scoring after Step 13 imports the
   15-lead test batch.
@@ -666,7 +686,7 @@ batch`, and a no-launch safety note. Do not leave the guide saying
 
 <conditional_gates>
 
-There are four customer-visible gates in the net-new hosted flow:
+There are six customer-visible gates in the net-new hosted flow:
 
 - `brief-review` asks whether to approve the rendered campaign brief before
   Find Leads starts. Do not skip this by inferring approval from setup
@@ -674,11 +694,17 @@ There are four customer-visible gates in the net-new hosted flow:
 - `lead-review` / source decision asks whether to approve the selected source
   path and sample before moving into filter/message work. Do not skip this by
   compressing the source decision into message review.
-- `message-review` is the mandatory pre-import message quality gate. It asks
-  only whether to proceed with the selected message (`approve-message`) or run
-  one more messaging revision (`revise-messaging`). `approve-message` authorizes
-  syncing the approved message set into the campaign brief, saving rubrics,
-  importing the bounded 15-lead test batch, and queueing/observing that sample.
+- `filter-choice` asks whether to use filters or skip after the non-empty
+  review batch is imported. This is the first post-import user gate.
+- `messages-mode-choice` asks whether to Use Template or choose AI Generated.
+  Use Template is recommended. AI Generated is an explicit opt-out that cancels
+  or ignores the background template draft.
+- `message-review` is the mandatory template quality gate only when the user
+  chooses Use Template. It asks only whether to proceed with the selected
+  message (`approve-message`) or run one more messaging revision
+  (`revise-messaging`). `approve-message` authorizes syncing the approved
+  template/token rules into the campaign brief and queueing/observing the
+  review-batch cascade.
 - The sender/settings/sequence handoff is the launch gate. After message
   validation, use Settings to help the user connect or select a LinkedIn sender.
   Explain Slack reply review before launch. After sender selection, attach the
@@ -814,6 +840,12 @@ Required behavior:
   watched campaign moving, not to compare every plausible lane in parallel.
   Run only enough evidence for the current lane to pass or fail the quick gate,
   then stop on the first viable source unless the user asked to compare.
+  User-facing fallback copy should stay fifth-grade clear: people engaging with
+  relevant LinkedIn posts -> Sales Nav to find ICP people actively posting on
+  LinkedIn -> search by titles -> Prospeo for a broader account/contact path.
+  The older provider label `broader Sales Nav` maps to the plain-language
+  `search by titles` fallback; `Prospeo only as the fallback` maps to the
+  plain-language broader account/contact path. Keep user-facing copy simple.
   1. Start with LinkedIn Engagement / active LinkedIn posts (internal provider:
      Signals / `signal-discovery`) because recent engagement gives the strongest
      message context and expected reply-rate upside. Search intersection keyword
@@ -842,6 +874,10 @@ Required behavior:
   start with Signal Discovery. If they name titles/personas/company filters,
   start with Sales Nav. If they explicitly ask for a comparison, compare only
   those requested sources.
+- failed or empty source lanes do not import leads. A timeout/error, zero raw
+  results, weak ICP fit, or weak message context must trigger the next approved
+  lane or a revision question before import. All lanes failed is a terminal
+  revise-source state, not an import state.
 - run source scouts in parallel only when the user explicitly requested a
   comparison, the current turn is resuming from already-started parallel scouts,
   or the first viable source is borderline and one cheap fallback check is
@@ -1237,30 +1273,50 @@ Do not:
 
 ## Step 3: Generate Message
 
-Step 3 is orchestrated by the main thread and executed either by the
-`post-find-leads-message-scout` worker or by the parent-thread fallback. The
-worker carries the campaign-launch message rules in its agent prompt. The
-parent-thread fallback must load the small safety-gate reference before writing
-message artifacts:
+Step 3 is the Message Draft Builder path. It is orchestrated by the main thread
+and executed either by the `post-find-leads-message-scout` worker or by the
+parent-thread fallback. The worker and fallback must load the full
+`generate-messages` prompt with `get_subskill_prompt` and use it as the drafting
+contract. The small safety-gate reference is only a supplemental approval
+check, not a replacement for the long message workflow:
 
 ```
+mcp__sellable__get_subskill_prompt({ subskillName: "generate-messages", offset, limit }) until hasMore=false
 mcp__sellable__get_subskill_asset({ subskillName: "create-campaign-v2", assetPath: "references/message-review-safety-gate.md" })
 ```
 
-Do not load the full long-form `generate-messages` subskill in
-`create-campaign-v2`. The safety-gate asset is a parent-thread compatibility
-path for hosts that cannot launch `post-find-leads-message-scout`, not a
-generate-message fast-mode prompt and not the preferred route. If the safety gate
-is missing a needed campaign-specific rule or the draft fails quality gates, stop
-at `revise-messaging` with the exact failure instead of pulling the long prompt
-into the main thread.
-
-Do NOT proceed to Step 4 (message review gate) unless `message-validation.md`
-contains the safety-gate required sections, a raw sendable Selected Winner, and an
-explicit single-first-send PASS. If `message-validation.md` contains post-accept
-DM, follow-up, second-touch, cadence, branch, or other sequence-shaped copy, do
-not summarize it as ready; route back to message-generation and require a
-single first outbound send.
+Use campaign state, campaign brief content, selected source state, and the
+selected/imported review-batch rows as the source of truth. Do not read
+`brief.md`, `lead-review.md`, or `lead-sample.json` as required state in the
+normal live campaign path; those files are optional debug context only. If the
+long prompt plus safety gate cannot safely approve the draft, stop at
+`revise-messaging` with the exact failure.
+
+Do NOT proceed to Step 4 (message review gate) unless the user has answered
+filter choice, the Messages step has shown the mode choice, the user chose Use
+Template, and `message-validation.md` contains the safety-gate required
+sections, a raw sendable Selected Winner, and an explicit single-first-send
+PASS. If the user reaches Messages and chose Use Template before the draft is
+ready, say you are waiting for the Message Draft Builder and do not ask for
+approval. If the draft worker fails, produces no usable message, or has no known
+worker status, require retry/regenerate copy instead of approval copy. If
+`message-validation.md` contains post-accept DM, follow-up, second-touch,
+cadence, branch, or other sequence-shaped copy, do not summarize it as ready;
+route back to message-generation and require a single first outbound send.
+
+Messages first shows mode choice:
+
+1. Use Template (recommended): wait for and review the Message Draft Builder
+   template. If filters are enabled, lock this review until saved rubrics and a
+   bounded filter run produce usable passing/probably passing rows. Prefer at
+   least 2 usable passing rows; if only 1 passes, use weak-sample copy and ask
+   whether to continue, revise, import more, or skip filters.
+2. AI Generated: this is an explicit opt-out. Cancel or ignore the background
+   template draft and prevent late template output from overwriting campaign
+   state.
+
+Product Generate Message cells should not run from the background template path
+until template/token rules are approved.
 
 After the main-chat message approval, update_campaign_brief writes `## Approved
 Message Template` with `{{...}}` tokens before any Generate Message cascade is

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

@@ -230,31 +230,24 @@ setting: `~/.codex/config.toml` with
 
 ## Parallelism + Naming
 
-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.
-Call `get_source_scout_registry` first and use the returned canonical `name`
-values; the names below are the current registry entries. In Codex, explicitly
-spawn named custom scouts in the same turn when the current runtime exposes
-them:
-`source-scout-linkedin-engagement` (LinkedIn Engagement Scout, backed by the
-`signal-discovery` provider prompt), `source-scout-sales-nav` (Sales Nav Scout), and
-`source-scout-prospeo-contact` (Prospeo Contact Scout) for the credible lanes. Codex
-does not infer subagent fan-out from generic "compare paths" wording. In Claude
-Code, invoke the generated `source-scout-linkedin-engagement`, `source-scout-sales-nav`,
-and/or `source-scout-prospeo-contact` Task/Agent subagents in one assistant
-message only when the session lists those names, so Claude can run the source
-lanes concurrently/background. These agents come from the same canonical
-Sellable registry and must load their matching provider prompt before
-searching. The parent thread should not fetch every provider prompt first; that
-burns time and often degenerates into parallel tool calls instead of true
-subagents. When asking the user to approve a brief with Sellable finding leads,
-use an explicit label like `Approve brief + use background source scouts` only
-when the current runtime exposes the named agents; otherwise use `Approve brief
-
-- compare source paths`. If the host runs them sequentially or the named agents
-  are absent, keep the output numeric but do not claim the source scout was
-  parallel or surface install status to the customer.
+Source selection is sequential by default. Start with the first recommended
+source lane from `flow.v2.json`; for the current campaign shape that is usually
+Signal Discovery / LinkedIn engagement. Only try the next fallback after the
+current lane is not viable, the user asks for a comparison, or the first lane is
+borderline and needs a second source to avoid a bad recommendation. The fallback
+order must stay plain: use Sales Nav to find ICP people who are actively posting
+on LinkedIn; if that is not enough, search Sales Nav by titles; if that is still
+not enough, use Prospeo for a broader account/contact path.
+
+Source-angle comparison should be real, not implied. Call
+`get_source_scout_registry` before dispatching source scouts and use the
+returned canonical `name` values. In Codex or Claude Code, launch multiple named
+source scouts in the same turn only when the user explicitly requested source
+comparison, a prior lane failed, or the active flow marks the first lane as
+borderline. The parent thread should not fetch every provider prompt first; each
+scout loads only its matching provider prompt. If source work is sequential,
+keep the output numeric but do not claim the source scout was parallel or
+surface install status to the customer.
 
 For post-lead work, call `get_post_find_leads_scout_registry` after source
 approval and use the returned canonical `name` values. Launch both returned