@sellable/mcp 0.1.0

package/skills/create-campaign-v2/references/watch-link-handoff.md

@@ -0,0 +1,106 @@
+# Watch Link Handoff
+
+This reference governs how create-campaign-v2 surfaces the watch link after
+the commit gate passes and the atomic mint succeeds. Load this file before
+showing the watch link, and on every resume where the link needs to be
+re-surfaced.
+
+## Plumbing Reuse
+
+`create_campaign` already returns a signed `watchUrl` on the response
+(`CampaignDetail.watchUrl` in `mcp/sellable/src/tools/campaigns.ts`). V2 does
+NOT mint a new token, does NOT call a different route, and does NOT construct
+the URL locally. The skill captures whatever `watchUrl` the existing tool
+returns and surfaces it verbatim.
+
+The v1 `create-campaign` SKILL uses the same "watch mode" pattern: after a
+step change, the skill names what changed and orients the user to what the
+watch link will show next. V2 adopts that pattern verbatim — the only
+difference is V2 surfaces the link once, at the atomic mint boundary, and
+then re-surfaces it on resume.
+
+## Atomic Mint Sequence
+
+The watch link is only surfaced after **both** of these tool calls succeed in
+this order:
+
+1. `create_campaign({ campaignBrief, currentStep: "auto-execute-leads" })`
+   → response MUST include `{ campaignId, watchUrl }`
+2. `save_rubrics({ campaignOfferId, rubric })`
+   → must return success
+
+Both calls must succeed before the link is printed. Never print the link
+between the two calls. Never print the link if either call fails.
+
+## Required Output Block
+
+After both tool calls succeed, print exactly one user-facing block. The block
+must contain:
+
+- a one-line orientation sentence: `Open this to watch lead sourcing, rubric
+scoring, and messaging populate live.`
+- the `watchUrl` captured from the `create_campaign` response
+
+Example skeleton:
+
+```text
+Campaign minted. Open this to watch lead sourcing, rubric scoring, and messaging populate live.
+
+Watch link: {watchUrl}
+```
+
+The exact wording may be adapted for tone, but the one-line orientation and
+the `watchUrl` are both required. Do not collapse the block into a single
+line with the link inline — the user needs to see the orientation clearly
+before they click.
+
+## Partial-Mint Recovery
+
+The following failure modes must NOT print the watch link:
+
+- `create_campaign` errors (no campaign exists, no watchUrl was returned) →
+  surface the underlying error, do not proceed to `save_rubrics`. No
+  rollback needed.
+- `create_campaign` succeeds but the response is missing `watchUrl` → treat
+  as a recoverable failure. Stop before `save_rubrics`. Do not print a link.
+  Surface an explicit error that names the contract violation (the backend
+  tool should always return `watchUrl`; a missing value is a plumbing bug,
+  not a silent skip).
+- `save_rubrics` fails after `create_campaign` succeeds → either rollback the
+  `CampaignOffer` row, or mark an explicit recoverable failure state so the
+  user can retry rubric save. Never leave a silent partial campaign with no
+  rubrics. Do NOT print the watch link during this recovery window.
+
+The guiding rule: a watch link points at a live, fully-minted campaign. If
+the campaign is half-minted, the link is misleading and must not be shown.
+
+## Resume Re-Surface
+
+Users can quit the session after `approve` and reopen later. Plan 85-02
+handles autonomous tail resume via `CampaignOffer.currentStep`. Part of the
+resume contract is re-surfacing the same watch link so the user reorients
+without digging through prior transcript.
+
+On resume:
+
+1. Load the `CampaignOffer` for the campaign being resumed.
+2. Call the same tool that yielded the link on mint (e.g.
+   `create_campaign({ campaignId })`, which is idempotent and returns the
+   existing campaign's `watchUrl` + state — see the v1 pattern in
+   `mcp/sellable/skills/create-campaign/SKILL.md`).
+3. Print the same block again with the one-line orientation plus `watchUrl`.
+
+The re-surface must use the signed `watchUrl` from the tool response, not a
+cached or reconstructed URL.
+
+## Hard Rules
+
+- Surface the link **once** on successful atomic mint, and re-surface on
+  resume. Do not spam the link between intermediate autonomous-tail steps.
+- Never print the link while the mint is mid-flight. Both
+  `create_campaign` and `save_rubrics` must have succeeded first.
+- Never fabricate or reconstruct the URL locally. Capture it from the
+  `create_campaign` response.
+- Missing `watchUrl` in the response is an error, not a silent skip.
+- Partial-mint states (campaign row created but rubrics not saved) must
+  block link surfacing and surface the recovery path instead.

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

@@ -0,0 +1,296 @@
+---
+name: create-campaign-v2-validation
+description: Validate a Phase 83 `brief.md` through chained Phase 84 artifacts before any live campaign state exists.
+visibility: internal
+---
+
+# Create Campaign v2 Validation
+
+<role>
+You are the Phase 84 validation orchestrator for create-campaign-v2. Your job
+is to validate a Phase 83 `brief.md` through chained draft artifacts without
+creating live campaign state.
+</role>
+
+<objective>
+Run validation in three serial steps:
+
+1. find leads
+2. filter leads
+3. generate message
+
+Each step writes its own artifact into the draft directory. The original
+`brief.md` stays preserved as the campaign thesis input.
+</objective>
+
+<files>
+
+Validated draft directory:
+
+```text
+.sellable/create-campaign-v2/drafts/{workspace-slug}/{campaign-slug}/
+  brief.md
+  lead-review.md
+  lead-sample.json
+  lead-filter.md
+  message-validation.md
+  rubric.json   # optional implementation artifact only
+```
+
+</files>
+
+<rules>
+
+- `brief.md` is the stable Phase 83 input and remains the thesis source.
+- `lead-review.md` and `lead-sample.json` are the required outputs of `find leads`.
+- `lead-filter.md` is the primary output of `filter leads`.
+- `rubric.json` is optional and secondary to `lead-filter.md`.
+- `message-validation.md` is the output of `generate message`.
+- Run validation serially in this order: `find leads`, `filter leads`, `generate message`.
+- Resume state is based on the presence and completeness of the chained artifacts,
+  not on inline validation blocks inside `brief.md`.
+- Preserve the Phase 83 thesis. Do not rewrite product, ICP, offer, or message
+  hypothesis sections during preview validation.
+- Every artifact write uses `tmp + rename` so a failed write leaves the prior
+  artifact intact.
+- If a required upstream artifact is missing, stop and route back to the
+  missing step instead of guessing.
+
+</rules>
+
+<step_contracts>
+
+## Step 1: Find Leads
+
+Use existing `find-leads` campaignless preview behavior to validate ICP and
+volume with a real sample.
+
+Write:
+
+- `lead-review.md`
+- `lead-sample.json`
+
+Required behavior:
+
+- use campaignless preview mode
+- do not pass `campaignOfferId`
+- do not import leads
+- do not set `selectedLeadListId`
+- do not create lead-list rows
+- do not mutate DB-backed campaign state
+- do not use generic tool discovery when the MCP tool names are already known
+- start with the narrowest credible role/company TAM for the first lane, then inspect a real sample before deciding the lane is good enough
+- after the first real search, estimate projected good fits from the sample and surface the math explicitly
+- if the projected good-fit pool is below roughly 300 and the market is not clearly niche by brief design, run one more real refinement or widening search before finalizing
+- if the market is clearly niche by brief design, it is acceptable to confirm a smaller pool, but say explicitly that it is niche-limited and still large enough for the first campaign
+- if the brief's primary goal is to reach out to people most likely to reply and the TAM plausibly uses LinkedIn, test a Signals-first lane before defaulting to Sales Nav
+- for reply-likelihood-first outbound, use this fallback order unless the brief explicitly points elsewhere: `Signals -> Sales Nav -> Prospeo`
+- if the Signals lane is too sparse, too noisy, or too small to sustain the campaign, say that explicitly and fall back to Sales Nav rather than forcing it
+- if the brief's primary channel is InMail or LinkedIn send, test a `POSTED_ON_LINKEDIN` slice after the baseline TAM whenever that slice can still support the first campaign
+- for InMail / LinkedIn send lanes, prefer the recently-posted slice as the first-send segment when it still yields enough projected good fits; if it is too small, explicitly remove the posted filter and continue with the non-posted role/company/industry lane
+- use Prospeo as the fallback when Signals and Sales Nav still cannot produce enough good fits or when account/domain expansion is the clearest next move
+- when a provider response includes reusable search URLs, include only one plain-English link label in `lead-review.md` such as `Search link I'd use:` so the user can open the search we actually want to use; mention discarded searches in prose without extra links and avoid internal phrasing like `chosen lane`
+- for regulated bank fraud / AML briefs, start title-first and Banking-first on the first sweep; do not begin with broad bio-keyword searches across generic Financial Services
+- treat card networks, payments platforms, insurers, asset managers, vendors, and generic transformation / analytics roles as second-pass expansions only after the title-first Banking lane is tested
+- for retail CPG brand ops briefs, start with brand-side ops-owner titles first and prefer finished-goods industries such as Food and Beverage Manufacturing, Beverage Manufacturing, and Personal Care Product Manufacturing before broad Consumer Goods
+- for retail CPG brand ops briefs, treat suppliers, CDMOs, packaging, logistics / 3PLs, retailers, and service companies as false positives unless the brief explicitly targets them
+- for retail CPG brand ops briefs, widen headcount before widening industry when the first pass is clean but small, and prefer named-account / domain-list second passes over generic industry expansion
+
+`lead-review.md` must state:
+
+- validation status: `confirmed`, `rejected`, or `unclear`
+- confidence
+- provider path used
+- plain-English search link label when available (for example `Search link I'd use`)
+- preview count
+- ICP match rate
+- sampledCount
+- passCount
+- passRate
+- projectedGoodFits
+- expectedPostFilterRange
+- volume comparison
+- repeated false-positive patterns
+- suggested next action or revision
+
+`lead-sample.json` must be a machine-readable sample that downstream filter
+validation can inspect directly.
+
+If preview returns zero usable leads, write the rejection evidence, stop the
+chain, and route to `revise-leads`.
+
+## Step 2: Filter Leads
+
+Read `brief.md`, `lead-review.md`, and `lead-sample.json`.
+
+Write:
+
+- `lead-filter.md`
+- optional `rubric.json`
+
+Required behavior:
+
+- preserve recurring keep/exclude filter families that show up across campaign
+  history: buyer role, wrong-function exclusions, company-type exclusions,
+  competitor/vendor exclusions, geography, company size, and active-role status
+- use the actual lead sample to identify repeated false positives
+- prefer required keep/exclude rules over a broad scoring stack
+- allow at most one optional/supporting rule when it materially helps later
+  messaging or prioritization
+- judge each proposed rule against the sample, report pass rate, and call out
+  whether the rule is truly necessary or should be removed
+- make every accepted filter directly translatable into production
+  `LeadScoringRubric` rows (`checkName`, `description`, `criterion`, `reason`,
+  `isRequiredCheck`, `allowPartialCredit`, `strictMatching`)
+- do not accept a filter that cannot be evaluated from `lead-sample.json`,
+  provider row fields, enrichment, or normal public research
+- derive `rubric.json` from the final `lead-filter.md` rules only when a
+  machine-readable sidecar is needed downstream
+- continue with `lead-filter.md` as the source of truth when `rubric.json`
+  cannot be written or parsed
+- if `rubric.json` is omitted, keep the filter concise enough that a 2-5 item
+  production rubric can be compiled from it without inventing new rules
+- write `lead-filter.md` user-facing first: decision, who we keep, who we
+  exclude, what the sample showed, pass rate, recommendation
+- include `Implementation Details` inside `lead-filter.md` whenever the status
+  is confirmed; this is where production rubric fields belong
+- `Implementation Details` must be a fenced JSON object with
+  `leadScoringRubrics` so downstream can parse/save the rules without
+  inference
+
+`lead-filter.md` must contain:
+
+- `Status`
+- `Decision`
+- `Who We'll Keep`
+- `Who We'll Exclude`
+- `Sample False Positives`
+- `Optional Supporting Rule` only when one is clearly justified
+- `Pass Rate`
+- `Recommendation`
+- `Implementation Details`
+
+When `rubric.json` is emitted, it must use the production rubric shape, not a
+custom sidecar schema:
+
+- `leadScoringRubrics`
+- `checkName`
+- `description`
+- `criterion`
+- `reason`
+- `isRequiredCheck`
+- `allowPartialCredit`
+- `strictMatching`
+
+`Implementation Details` must contain a fenced JSON object with
+`leadScoringRubrics`, and that array must contain 2-5 production rubric items
+total. Do not create one rubric row per keep/exclude bullet. Bundle related
+false-positive families into one exclusion criterion, and keep role fit as its
+own explicit criterion. Keep raw rubric flags out of the top user-facing
+sections.
+
+Do not:
+
+- call `check_rubric`
+- call `save_rubrics`
+- create a second independent scoring design in `rubric.json`
+- emit more than one optional/supporting rule
+
+## Step 3: Generate Message
+
+Read `brief.md`, `lead-filter.md`, and `lead-sample.json`.
+
+Write:
+
+- `message-validation.md`
+
+Run the `generate-messages` skill in caller-declared `DRY MODE`. Its SKILL.md
+holds the full drafting contract (retrieval, proof inventory, candidates,
+finalizer pass, voice rules, safety). This step only covers orchestration.
+
+Orchestration requirements:
+
+- draft only after real leads and final filter rules exist
+- pass no `campaignId`
+- read only `brief.md`, `lead-filter.md`, `lead-sample.json`, and the
+  `gold-standard-*` references
+- generate 2-3 sample messages inline
+- start output with `Mode: DRY MODE (no DB mutation)`
+- treat the archived examples as the **quality bar**, not a paste source;
+  write messages that could plausibly belong in the archive for this motion
+- exact-template preservation only applies when the archived winner is the
+  same company as the brief
+- draft 3 internal candidates and run a Finalizer Pass that combines the
+  best opener, proof sentence, bridge, and CTA across them into one winner
+- pass the Thomas revision filters before writing findings
+
+Do not:
+
+- call `get_campaign`
+- call `get_rows`
+- call `update_cell`
+- call `update_campaign_brief`
+- fetch fresh web or LinkedIn research
+- mutate DB-backed campaign state
+
+`message-validation.md` must contain:
+
+- `Status`
+- `Mode`
+- `Template Used`
+- `Primary Example`
+- `Secondary Influence`
+- `Lead Sample Basis`
+- `Strongest Reply Reason`
+- `Pre-Draft Buyer-Role Analysis`
+- `Campaign Element Pool`
+- `Gold Standard Strategy Map`
+- `Current Campaign Translation`
+- `Element Scoring`
+- `Proof Inventory`
+- `Token Fill Rules`
+- `Token Adherence Table`
+- `Angle Drafts`
+- `Kill / Combine Review`
+- `Finalists`
+- `Candidate Messages`
+- `Finalizer Pass`
+- `Gold-Standard Quality Gate`
+- `Skeptical Prospect Review`
+- `Winner Gate`
+- `Selected Winner`
+- `Findings`
+- `Recommendation`
+
+If token sourcing is weak, revise token fill rules or route back to
+`revise-filter` or `revise-message` instead of guessing.
+
+</step_contracts>
+
+<resume_rules>
+
+- Only `brief.md` present -> run `find leads`
+- `lead-review.md` + `lead-sample.json` present, but no `lead-filter.md` -> run
+  `filter leads`
+- `lead-filter.md` present, but no `message-validation.md` -> run `generate message`
+- `message-validation.md` present -> validation is complete
+- `lead-review.md` without `lead-sample.json`, or vice versa -> stop with a
+  contract violation
+- `lead-filter.md` without upstream lead artifacts -> stop with a contract violation
+
+</resume_rules>
+
+<boundaries>
+
+Do not create live campaign state.
+
+Do not:
+
+- mint a campaign
+- import leads
+- persist selected lead lists
+- attach downstream assets
+- save remote rubric state
+- move the user into a live execution step
+
+</boundaries>