@sellable/mcp 0.1.511 → 0.1.513

package/skills/refill-sends-v2/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: refill-sends-v2
+description: Plan refill sends v2 work through the read-only three-lane dry-run planner.
+visibility: public
+allowed-tools:
+  - mcp__sellable__refill_sends_v2
+  - mcp__sellable__get_refill_plan_v2
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends V2
+
+Use this public command wrapper for refill planning requests such as "refill
+sends", "fill evergreen senders", "load everyone up", "plan Damiano", or "show a
+dry-run for this workspace".
+
+Host command names:
+
+- Claude Code: `/sellable:refill-sends-v2`
+- Codex: `$sellable:refill-sends-v2`
+
+This is plan-only, read-only, dry-run, zero mutations. It creates no campaigns,
+does not prepare or approve messages, does not start campaigns, does not
+schedule or send messages, does not refresh paid InMail credit facts, and does
+not change source configuration. Execution remains in the Phase 86 workflow.
+
+## Entry
+
+Resolve the explicit `workspaceId` from the request, automation config, or
+active workspace readback. Scheduled or autonomous usage must carry
+`workspaceId` on every tool call. If the workspace is missing or ambiguous, stop
+with `WORKSPACE_REQUIRED`; do not switch the shared active workspace.
+
+Start with the command contract:
+
+```text
+refill_sends_v2({ workspaceId })
+```
+
+Then load the internal workflow prompt and flow asset:
+
+```text
+get_subskill_prompt({ subskillName: "refill-sends-v2-workflow" })
+get_subskill_asset({ subskillName: "refill-sends-v2-workflow", assetPath: "core/flow.v1.json" })
+```
+
+Continue both loads until `hasMore:false`; parse the flow JSON and verify
+`workflow:"refill-sends-v2-workflow"` with a `v1` version before the planner
+call.
+
+Call the dry-run planner with the explicit workspace id:
+
+```text
+get_refill_plan_v2({ workspaceId, intent:"auto", senderIds?, runState?, journal?, journalNote? })
+```
+
+The default `intent:"auto"` checks the three lane-source families in order:
+
+- `managed_waterfall` for product-managed evergreen waterfall lanes.
+- `dashboard_evergreen` for dashboard-visible evergreen campaigns.
+- `active_campaign` for regular active campaigns that should refill through a
+  deterministic lane chain.
+
+Use `senderIds` only when the user scoped the request to exact senders. Use
+`runState` only for an explicit what-if dry run; otherwise let the MCP read
+local lane memory hints. Leave `journal` enabled unless the user specifically
+asked for no local journal.
+
+## Report
+
+Review the returned packet before giving a recommendation:
+
+- `planRevision` starts with `pr1:`.
+- `stateRevision` identifies the current readback.
+- `packet` is the operator-facing facts receipt.
+- `plans[]` contains per-sender lane decisions and itinerary details.
+- `globalActionQueue[]` is a dry-run sequence only.
+- `evergreen.laneOrder[].source` uses `managed_waterfall`,
+  `dashboard_evergreen`, or `active_campaign`.
+- `evergreen.senderLaneSelections[].laneChain` records the ordered lane chain
+  when a regular active campaign chain is selected.
+- Terminals can include `done` or `no_refillable_campaigns`.
+- A membership 403 must return the structured `workspace_access` blocker; report
+  it as a read-only blocker, not a login retry.
+- `journalPath` points to the dry-run markdown journal written by the MCP.
+- `sideEffects` must be all false.
+
+Report campaign names and sender names first, ids second. Include the lane
+source, lane chain when present, chosen rung, itinerary, plan revision, journal
+path, and any blockers or warnings. Stop after the report; do not execute the
+action queue.

package/skills/refill-sends-v2-workflow/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: refill-sends-v2-workflow
+description: Internal read-only workflow for refill sends v2 dry-run planning.
+visibility: internal
+allowed-tools:
+  - mcp__sellable__refill_sends_v2
+  - mcp__sellable__get_refill_plan_v2
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends V2 Workflow
+
+This internal workflow is the read-only, dry-run, zero mutations plan surface
+for refill sends v2. The workflow has three gates: bootstrap, plan, and report.
+It covers product-managed evergreen workspaces, dashboard evergreen workspaces,
+and non-evergreen active campaign workspaces without creating new campaigns.
+
+Runtime flow asset: after loading this prompt, load
+`get_subskill_asset({ subskillName: "refill-sends-v2-workflow", assetPath: "core/flow.v1.json" })`
+through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
+`workflow:"refill-sends-v2-workflow"` with a `v1` version before any planner
+call. If the asset cannot load or parse, stop with
+`blocked:refill_sends_v2_workflow_asset_unavailable`; do not emulate it from
+local files or memory.
+
+## G0 Bootstrap Facts
+
+Resolve the request-scoped `workspaceId` using read-only auth and workspace
+tools. Scheduled or autonomous runs must not rely on implicit workspace state.
+Call `refill_sends_v2({ workspaceId })` first to receive the command contract,
+then call `get_refill_plan_v2({ workspaceId, intent:"auto" })` for the dry-run
+packet.
+
+Optional inputs:
+
+- `senderIds`: exact sender scope when the user named senders.
+- `intent`: defaults to `auto`. Use explicit `evergreen`, `plain`, or `active`
+  only for a what-if comparison.
+- `runState`: synthetic v1 lane memory for what-if dry runs. Use it only when
+  the user intentionally wants a hypothetical cursor, pin, cooldown state, or
+  laneChain replay.
+- `journal:false`: skip the local journal only when explicitly requested.
+- `journalNote`: append operator context to the dry-run terminal section.
+
+## G1 Lane Sources
+
+The planner reports the lane source for every selected lane:
+
+1. `managed_waterfall`: product-managed evergreen waterfall lanes.
+2. `dashboard_evergreen`: dashboard-visible evergreen campaigns that are not in
+   the managed waterfall snapshot.
+3. `active_campaign`: regular active campaigns ranked into a deterministic
+   laneChain for non-evergreen refill planning.
+
+If no lane family has refillable campaigns, report `no_refillable_campaigns`.
+If the user lacks membership on a requested workspace, report the structured
+`workspace_access` blocker with the workspace id and journal path.
+
+## G2 Refill Ladder
+
+The planner chooses from this locked rung order:
+
+1. `start_campaign`: a paused selected lane has scheduler-ready supply but must
+   be live before the scheduler can pick it up.
+2. `approve_messages`: generated rows are ready for a bounded approval step.
+3. `wait_for_active_work`: enrichment, generation, import, or preparation is
+   already active, so the next honest action is to wait for that work to finish.
+4. `enrich_more`: exact-set enrichment can close the current ready gap.
+5. `reconcile_source_copy`: same-source rows exist and can be copied without
+   changing source family or source fingerprint.
+6. `add_leads_same_source`: the same source path can add bounded new supply.
+7. `paid_lane_fallback`: paid InMail is blocked or below threshold, so the same
+   waterfall can fall back to an existing supported lane.
+8. `next_campaign`: the current lane is exhausted, cooling down, pinned away, or
+   unsafe, and the next surviving campaign lane should be inspected.
+9. `wait_for_scheduler`: ready or projected supply covers the target, and only
+   scheduler pickup remains.
+10. `done`: the sender or lane is complete for the selected target window, a
+    scheduler cap makes additional preparation unnecessary, or
+    `no_refillable_campaigns` is the honest terminal.
+
+Forward-only lane rule: a lane can move to a later rung or a later surviving
+campaign, but the dry-run packet must not jump backward to invent work that the
+facts do not support. Pinned-campaign rule: a pinned campaign stays selected
+until the planner proves a blocker, cooldown, exhaustion, or safer next lane.
+Capped-is-complete rule: when scheduler capacity is lower than the requested
+target and ready/projected coverage satisfies that cap, report `done` with the
+cap reason. Honest-itinerary rule: show what was checked, what was skipped, and
+why; never hide uncertainty behind a confident source recommendation.
+
+Guardrails: no campaign creation, no provider-family switch, no threshold
+lowering, no scheduler writes, no launch/send/archive/delete, no
+brief/filter/message/sequence/sender mutation, no message preparation, no
+message approval, no paid InMail credit refresh, no source mutation, no row
+queueing, and no campaign status change.
+
+## Journal
+
+`get_refill_plan_v2` writes a local dry-run journal unless `journal:false` is
+passed. Read the returned `journalPath` from the tool result and include it in
+the report. The journal contains bootstrap, plan, and terminal sections plus an
+index line under the run journal directory. If the tool returns
+`journalPath:null` with a `journalWriteFailed` warning, report the warning and
+continue with the dry-run packet; do not retry by writing local files yourself.
+
+## Report Contract
+
+Completion means packet reviewed and journal written. Merely calling
+`get_refill_plan_v2` is not completion proof.
+
+Report these facts:
+
+- workspace id and selected sender scope;
+- plan revision and state revision;
+- selected campaign, lane source, and laneChain per sender;
+- chosen rung and dry-run action queue;
+- itinerary, skipped lanes, blockers, cooldowns, and warnings;
+- `no_refillable_campaigns` terminals and `workspace_access` blockers;
+- journal path;
+- side effects proof, which must show all false values.
+
+Stop after the report. This workflow never executes the action queue.

package/skills/refill-sends-v2-workflow/core/flow.v1.json

@@ -0,0 +1,266 @@
+{
+  "version": "v1.0",
+  "workflow": "refill-sends-v2-workflow",
+  "principle": "Plan refill sends v2 as a read-only dry-run with zero mutations across managed_waterfall, dashboard_evergreen, and active_campaign lane sources.",
+  "laneSources": ["managed_waterfall", "dashboard_evergreen", "active_campaign"],
+  "terminalReasons": ["done", "no_refillable_campaigns"],
+  "blockers": ["workspace_access"],
+  "enumeratedRungs": [
+    "start_campaign",
+    "approve_messages",
+    "wait_for_active_work",
+    "enrich_more",
+    "reconcile_source_copy",
+    "add_leads_same_source",
+    "paid_lane_fallback",
+    "next_campaign",
+    "wait_for_scheduler",
+    "done"
+  ],
+  "requiredBootstrap": [
+    {
+      "tool": "get_auth_status",
+      "purpose": "Confirm MCP auth before reading workspace or plan facts."
+    },
+    {
+      "tool": "get_active_workspace",
+      "purpose": "Resolve explicit workspace evidence when the request did not provide workspaceId."
+    },
+    {
+      "tool": "refill_sends_v2",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}"
+      },
+      "requiredOutput": [
+        "readOnly true",
+        "approvalContract says Phase 86 handles execution"
+      ]
+    },
+    {
+      "tool": "get_subskill_prompt",
+      "requiredValues": {
+        "subskillName": "refill-sends-v2-workflow"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-v2-workflow",
+        "assetPath": "core/flow.v1.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "workflow": "refill-sends-v2-workflow",
+        "versionPrefix": "v1",
+        "requiredTopLevelKeys": [
+          "states",
+          "gateOrder",
+          "enumeratedRungs",
+          "verification",
+          "laneSources",
+          "terminalReasons",
+          "blockers"
+        ]
+      }
+    },
+    {
+      "tool": "get_refill_plan_v2",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}",
+        "intent": "auto"
+      },
+      "requiredOutput": [
+        "planRevision or workspace_access blocker",
+        "stateRevision",
+        "packet",
+        "journalPath",
+        "sideEffects"
+      ]
+    }
+  ],
+  "gateOrder": ["bootstrap", "plan", "report"],
+  "states": [
+    {
+      "id": "bootstrap",
+      "description": "Load the read-only command contract, workflow prompt, flow asset, and workspace facts.",
+      "allowedTools": [
+        "get_auth_status",
+        "get_active_workspace",
+        "list_workspaces",
+        "get_workspace",
+        "refill_sends_v2",
+        "get_subskill_prompt",
+        "get_subskill_asset",
+        "get_refill_plan_v2"
+      ],
+      "onEnter": [
+        {
+          "tool": "get_auth_status"
+        },
+        {
+          "tool": "refill_sends_v2",
+          "requiredFields": ["workspaceId"]
+        },
+        {
+          "tool": "get_subskill_prompt",
+          "requiredValues": {
+            "subskillName": "refill-sends-v2-workflow"
+          }
+        },
+        {
+          "tool": "get_subskill_asset",
+          "requiredValues": {
+            "subskillName": "refill-sends-v2-workflow",
+            "assetPath": "core/flow.v1.json"
+          }
+        }
+      ],
+      "transitions": {
+        "contract_loaded": "plan"
+      }
+    },
+    {
+      "id": "plan",
+      "description": "Call the read-only refill sends v2 dry-run planner exactly once for this invocation.",
+      "allowedTools": ["get_refill_plan_v2"],
+      "onEnter": [
+        {
+          "tool": "get_refill_plan_v2",
+          "requiredFields": ["workspaceId"],
+          "optionalFields": [
+            "intent",
+            "senderIds",
+            "runState",
+            "journal",
+            "journalNote"
+          ]
+        }
+      ],
+      "requiredOutput": [
+        "sideEffects all false",
+        "planRevision starts with pr1: unless blocker is workspace_access",
+        "journalPath reported",
+        "chosen evergreenRung is in enumeratedRungs",
+        "lane sources are managed_waterfall, dashboard_evergreen, or active_campaign",
+        "terminal can be no_refillable_campaigns"
+      ],
+      "allowedRungsSource": "enumeratedRungs",
+      "doNotAllow": [
+        "add_column",
+        "add_on_demand_leads",
+        "add_rubric_item",
+        "add_teammate",
+        "add_to_comment_campaign",
+        "add_to_connection_campaign",
+        "add_to_inmail_campaign",
+        "archive_campaign",
+        "attach_recommended_sequence",
+        "attach_sequence",
+        "bulk_enrich_with_prospeo",
+        "cancel_campaign_message_preparation",
+        "cancel_lead_import",
+        "capture_post_idea",
+        "check_rubric",
+        "commit_blueprint",
+        "confirm_harvest_job_companies",
+        "confirm_lead_list",
+        "confirm_prospeo_company_accounts",
+        "copy_sender_config",
+        "create_campaign",
+        "create_on_demand_campaign",
+        "create_on_demand_table",
+        "create_workspace",
+        "create_workflow_table",
+        "delete_column",
+        "delete_rubric_item",
+        "duplicate_campaign",
+        "enrich_with_prospeo",
+        "fill_campaign_horizon",
+        "get_or_create_direct_campaign_table",
+        "import_leads",
+        "load_csv_dnc_entries",
+        "load_csv_domains",
+        "load_csv_linkedin_leads",
+        "mark_post_published",
+        "migrate_flat_configs",
+        "pause_campaign",
+        "pause_direct_campaign",
+        "pause_on_demand_campaign",
+        "prepare_campaign_ab_test",
+        "queue_campaign_cells",
+        "queue_cells",
+        "record_campaign_review_batch",
+        "record_engage_proven_search",
+        "refill_sends",
+        "refresh_paid_inmail_credits",
+        "revise_message_template_and_rerun",
+        "save_domain_filters",
+        "save_hook_research",
+        "save_post_draft",
+        "save_rubrics",
+        "send_inbox_draft",
+        "send_inbox_manual_reply",
+        "set_active_workspace",
+        "set_campaign_waterfall_order",
+        "set_company_info",
+        "set_engage_state",
+        "set_engage_style_guide",
+        "set_headline_icp_criteria",
+        "set_sender_routing",
+        "setup_evergreen_campaigns",
+        "start_campaign",
+        "start_campaign_message_preparation",
+        "start_direct_campaign",
+        "start_on_demand_campaign",
+        "update_campaign",
+        "update_campaign_brief",
+        "update_cell",
+        "update_column",
+        "update_inbox_draft",
+        "update_post_draft",
+        "update_published_post_metrics",
+        "update_rubric_item",
+        "upsert_engage_tracked_person",
+        "upsert_rubric"
+      ],
+      "transitions": {
+        "packet_returned": "report",
+        "workspace_access": "report"
+      }
+    },
+    {
+      "id": "report",
+      "description": "Present packet, lane source, laneChain, itinerary, warnings, blockers, plan revision, and journal path; then stop.",
+      "allowedTools": [],
+      "onEnter": [
+        {
+          "action": "present_packet_itinerary_and_journal_path"
+        }
+      ],
+      "terminal": true
+    }
+  ],
+  "verification": {
+    "requiredProof": [
+      "sideEffects all false in get_refill_plan_v2 response",
+      "planRevision has pr1: prefix unless blocker is workspace_access",
+      "journalPath reported or journalWriteFailed warning surfaced",
+      "chosen evergreenRung belongs to enumeratedRungs",
+      "lane source belongs to managed_waterfall, dashboard_evergreen, active_campaign",
+      "laneChain recorded when active_campaign chain is selected",
+      "no_refillable_campaigns terminal reported when no lane is refillable",
+      "packet reviewed with itinerary and blockers"
+    ],
+    "notCompletionProof": [
+      "called get_refill_plan_v2 alone",
+      "action queue exists",
+      "ready rows alone",
+      "operator wants execution"
+    ]
+  }
+}