@sellable/mcp 0.1.0

package/skills/building-gtm-tables/references/common-blueprints.fixtures.ts

@@ -0,0 +1,199 @@
+import type { Blueprint } from "@/lib/workflow-tables/blueprint/schema";
+
+export type CommonBlueprintEntry = {
+  slug: string;
+  description: string;
+  blueprint: Blueprint;
+};
+
+const enrichmentRubric = [
+  {
+    checkName: "vp_or_c_level",
+    criterion: "Must be VP or C-level in revenue, sales, marketing, or GTM.",
+    description: "Senior GTM operators with buying authority.",
+    reason: "Decision makers can approve workflow automation purchases.",
+    isRequiredCheck: "true",
+    allowPartialCredit: "false",
+  },
+  {
+    checkName: "active_outbound_motion",
+    criterion: "Company shows evidence of outbound or pipeline-building work.",
+    description: "Outbound motion is visible in role, hiring, or messaging.",
+    reason: "The table is most useful when outbound volume creates ops pain.",
+    isRequiredCheck: "false",
+    allowPartialCredit: "true",
+  },
+];
+
+const httpEnrichConfig = {
+  inputMapping: {
+    method: { value: "POST" },
+    endpoint: { value: "/api/v4/enrich-prospect" },
+    body: { value: '{"linkedinUrl":"{{LinkedIn URL}}"}' },
+  },
+};
+
+export const COMMON_BLUEPRINTS: CommonBlueprintEntry[] = [
+  {
+    slug: "enrich-and-score",
+    description: "Rank a prospect list against an ICP rubric.",
+    blueprint: {
+      columns: [
+        { id: "c1", type: "text", name: "LinkedIn URL", config: {} },
+        {
+          id: "c2",
+          type: "http_request",
+          name: "Enrich Prospect",
+          config: httpEnrichConfig,
+          inputMapping: { linkedinUrl: "c1" },
+        },
+        {
+          id: "c3",
+          type: "score_icp_mcp",
+          name: "ICP Score",
+          config: { rubric: enrichmentRubric },
+          inputMapping: { enrichedProspectId: "c2" },
+        },
+      ],
+      edges: [
+        { from: "c1", to: "c2", via: "linkedinUrl" },
+        { from: "c2", to: "c3", via: "enrichedProspectId" },
+      ],
+    },
+  },
+  {
+    slug: "enrich-score-send-invite",
+    description: "Enrich + score + conditionally send invite to top scorers.",
+    blueprint: {
+      columns: [
+        { id: "c1", type: "text", name: "LinkedIn URL", config: {} },
+        {
+          id: "c2",
+          type: "http_request",
+          name: "Enrich Prospect",
+          config: httpEnrichConfig,
+          inputMapping: { linkedinUrl: "c1" },
+        },
+        {
+          id: "c3",
+          type: "score_icp_mcp",
+          name: "ICP Score",
+          config: { rubric: enrichmentRubric },
+          inputMapping: { enrichedProspectId: "c2" },
+        },
+        {
+          id: "c4",
+          type: "send_invite",
+          name: "Invite",
+          config: {
+            actionConfig: {
+              actionType: "INVITE",
+              waitForEvent: {
+                event: "connection_created",
+                timeoutDays: 14,
+              },
+            },
+            runCondition: "{{ICP Score.score}} >= 70",
+          },
+          inputMapping: { linkedinUrl: "c1" },
+          runCondition: "{{ICP Score.score}} >= 70",
+        },
+      ],
+      edges: [
+        { from: "c1", to: "c2", via: "linkedinUrl" },
+        { from: "c2", to: "c3", via: "enrichedProspectId" },
+        { from: "c1", to: "c4", via: "linkedinUrl" },
+        { from: "c3", to: "c4", via: "runCondition" },
+      ],
+    },
+  },
+  {
+    slug: "enrich-score-generate-message",
+    description:
+      "Enrich + score + generate campaign-backed messages for qualified prospects.",
+    blueprint: {
+      columns: [
+        { id: "c1", type: "text", name: "LinkedIn URL", config: {} },
+        {
+          id: "c2",
+          type: "text",
+          name: "Campaign Offer ID",
+          config: {},
+        },
+        {
+          id: "c3",
+          type: "http_request",
+          name: "Enrich Prospect",
+          config: httpEnrichConfig,
+          inputMapping: { linkedinUrl: "c1" },
+        },
+        {
+          id: "c4",
+          type: "score_icp_mcp",
+          name: "ICP Score",
+          config: { rubric: enrichmentRubric },
+          inputMapping: { enrichedProspectId: "c3" },
+        },
+        {
+          id: "c5",
+          type: "generate_message",
+          name: "Generate Message",
+          config: {
+            runCondition: "{{ICP Score.score}} >= 70",
+          },
+          inputMapping: {
+            campaignOfferId: "c2",
+            enrichedProspectId: "c3",
+          },
+          runCondition: "{{ICP Score.score}} >= 70",
+        },
+      ],
+      edges: [
+        { from: "c1", to: "c3", via: "linkedinUrl" },
+        { from: "c3", to: "c4", via: "enrichedProspectId" },
+        { from: "c2", to: "c5", via: "campaignOfferId" },
+        { from: "c3", to: "c5", via: "enrichedProspectId" },
+        { from: "c4", to: "c5", via: "runCondition" },
+      ],
+    },
+  },
+  {
+    slug: "ai-column-escape-hatch",
+    description:
+      "Bring-your-own-prompt AI Column writes a one-line research summary per prospect.",
+    blueprint: {
+      columns: [
+        { id: "c1", type: "text", name: "LinkedIn URL", config: {} },
+        {
+          id: "c2",
+          type: "text",
+          name: "Research Prompt",
+          config: {},
+        },
+        {
+          id: "c3",
+          type: "ai_column",
+          name: "Post Summary",
+          config: {
+            aiConfig: {
+              modelName: "google/gemini-3.1-flash-lite-preview",
+              systemPrompt:
+                "Summarize only observable public LinkedIn evidence.",
+              userPrompt:
+                "Using {{LinkedIn URL}} and {{Research Prompt}}, write one sentence about the prospect's latest relevant LinkedIn activity.",
+              outputFields: [{ name: "summary", type: "text" }],
+              enableWebSearch: true,
+              maxSearchQueries: 3,
+            },
+            processing: { autoUpdate: true },
+          },
+          inputMapping: { linkedinUrl: "c1", prompt: "c2" },
+        },
+      ],
+      edges: [
+        { from: "c1", to: "c3", via: "linkedinUrl" },
+        { from: "c2", to: "c3", via: "prompt" },
+      ],
+    },
+  },
+];

package/skills/building-gtm-tables/references/common-blueprints.md

@@ -0,0 +1,44 @@
+# Common Blueprints
+
+The worked examples are defined once as a typed fixture at
+[`./common-blueprints.fixtures.ts`](./common-blueprints.fixtures.ts). The
+contract test imports `COMMON_BLUEPRINTS` directly and validates every blueprint
+against the validator, so drift is caught by TypeScript or by an assertion.
+
+Each entry has:
+
+- `slug` - stable identifier
+- `description` - one-line summary
+- `blueprint` - full Blueprint object
+
+## 1. Enrich + Score (`enrich-and-score`)
+
+Rank a prospect list against an ICP rubric. Three columns: `text` for LinkedIn
+URL, `http_request` named "Enrich Prospect" for `/api/v4/enrich-prospect`, then
+`score_icp_mcp` with a natural-language rubric.
+
+See `COMMON_BLUEPRINTS[0].blueprint` in the fixture.
+
+## 2. Enrich + Score + Send Invite (`enrich-score-send-invite`)
+
+Build the same enrichment and scoring spine, then add `send_invite` gated on the
+ICP score. This is the default pattern when the table should both qualify and
+act on high-fit prospects.
+
+See `COMMON_BLUEPRINTS[1].blueprint` in the fixture.
+
+## 3. Enrich + Score + Generate Message (`enrich-score-generate-message`)
+
+Build the enrichment and scoring spine, then add `generate_message` for
+campaign-backed production copy. Both `score_icp_mcp` and `generate_message`
+map `enrichedProspectId` from the same `http_request` column named "Enrich
+Prospect".
+
+See `COMMON_BLUEPRINTS[2].blueprint` in the fixture.
+
+## 4. AI Column Escape Hatch (`ai-column-escape-hatch`)
+
+Use `ai_column` only when the user needs a bespoke prompt that is not covered by
+fixed enrichment, scoring, or LinkedIn action columns.
+
+See `COMMON_BLUEPRINTS[3].blueprint` in the fixture.

package/skills/building-gtm-tables/references/failure-taxonomy.md

@@ -0,0 +1,197 @@
+# Failure Taxonomy
+
+## TOC
+
+- [Validator failure modes (what the Plan 04 validator catches)](#validator-failure-modes-what-the-plan-04-validator-catches)
+- [LLM tool-calling failure modes (from 98-RESEARCH.md)](#llm-tool-calling-failure-modes-from-98-researchmd)
+
+## Validator failure modes (what the Plan 04 validator catches)
+
+### 1. Shape
+
+What the LLM did wrong: emitted a blueprint that does not match the Zod shape.
+
+Example:
+
+```json
+{ "column": [] }
+```
+
+How to fix: emit `{ "columns": [...], "edges": [...] }` with every column
+containing `id`, `type`, `name`, and `config`.
+
+### 2. Phantom type
+
+What the LLM did wrong: invented or pluralized a type.
+
+Example:
+
+```json
+{
+  "id": "enrich",
+  "type": "http_requests",
+  "name": "Enrich Prospect",
+  "config": {}
+}
+```
+
+How to fix: pick the active registry key from `column-type-catalog.md`, such as
+`http_request`.
+
+### 3. Deprecated type
+
+What the LLM did wrong: used an old type such as `enrich_person`.
+
+Example:
+
+```json
+{
+  "id": "enrich",
+  "type": "enrich_person",
+  "name": "Enrich Prospect",
+  "config": {}
+}
+```
+
+How to fix: use the `migrateToType` target, normally `http_request`, and preserve
+the intended behavior in config.
+
+### 4. Required field
+
+What the LLM did wrong: omitted required config.
+
+Example:
+
+```json
+{
+  "id": "enrich",
+  "type": "http_request",
+  "name": "Enrich Prospect",
+  "config": { "method": "POST" }
+}
+```
+
+How to fix: include the required field, for example `endpoint:
+"/api/v4/enrich-prospect"` plus the mapped body.
+
+### 5. Missing producer
+
+What the LLM did wrong: referenced a column id or template token that no column
+produces.
+
+Example:
+
+```json
+{
+  "id": "score",
+  "type": "score_icp_mcp",
+  "name": "ICP Score",
+  "config": { "rubric": ["VP sales"] },
+  "inputMapping": { "enrichedProspectId": "ghost_enrich" }
+}
+```
+
+How to fix: add the producer column or change the mapping to the actual producer
+id.
+
+### 6. Cycle
+
+What the LLM did wrong: created two columns that depend on each other.
+
+Example:
+
+```json
+{
+  "edges": [
+    { "from": "a", "to": "b", "via": "x" },
+    { "from": "b", "to": "a", "via": "y" }
+  ]
+}
+```
+
+How to fix: choose one true upstream source and remove the reverse dependency.
+
+### 7. Wrong order
+
+What the LLM did wrong: put a consumer before the producer in a way that the
+commit planner cannot safely resolve.
+
+Example: `score_icp_mcp` appears before `enrich_prospect` while mapping
+`enrichedProspectId` from `enrich_prospect`.
+
+How to fix: order columns topologically and keep `edges` consistent with
+`inputMapping`.
+
+### 8. Recommended producer missing
+
+What the LLM did wrong: produced a valid but low-quality scoring blueprint.
+
+Example: `score_icp_mcp` scores from only a LinkedIn URL even though Enrich Prospect
+would provide richer data.
+
+How to fix: this is a warning, not an error. Consider adding "Enrich Prospect"
+as a `http_request` producer before scoring.
+
+## LLM tool-calling failure modes (from 98-RESEARCH.md)
+
+### 9. Non-existent tool name
+
+Observable symptom: the agent calls a made-up configuration tool.
+
+Defense mechanism: use the fully qualified tool inventory in `SKILL.md`; never
+invent tools.
+
+### 10. Wrong tool chosen
+
+Observable symptom: the agent tries to update cells or run queueing instead of
+authoring a blueprint.
+
+Defense mechanism: the phase gates say BLUEPRINT before COMMIT before VERIFY,
+and the catalog says when to use and when NOT to use each column type.
+
+### 11. Invalid parameters
+
+Observable symptom: the tool call has the right name but the wrong shape.
+
+Defense mechanism: `core/blueprint-schema.json` constrains authoring, and the
+runtime Zod validator safe-parses before commit.
+
+### 12. Missing required arguments
+
+Observable symptom: a commit is attempted without column config that the runtime
+requires.
+
+Defense mechanism: Zod required fields plus the validator's `required_field`
+error report.
+
+### 13. Tool simulation
+
+Observable symptom: the agent says the blueprint is committed or verified but
+no MCP tool was actually called.
+
+Defense mechanism: phase gates require real `sellable:commit_blueprint` and
+`sellable:verify_table_row` calls. Always call the tool, never simulate it.
+
+### 14. Premature cell queueing
+
+Observable symptom: cells are queued before the dependency graph is valid.
+
+Defense mechanism: HARD INVARIANT forbids direct `sellable:queue_cells`; commit
+creates columns and lets the orchestrator queue cells after validation.
+
+### 15. Wait-column stall
+
+Observable symptom: verification hangs or appears blocked on a wait or long
+timer column.
+
+Defense mechanism: option (d) passes wait column ids through `skipColumnIds`.
+The skill does not override run conditions at runtime.
+
+### 16. Missing enrichment dependency
+
+Observable symptom: scoring works poorly or fails because the enriched prospect
+object was never produced.
+
+Defense mechanism: the `recommended_producer` warning surfaces "consider Enrich
+Prospect for score_icp_mcp"; fix by adding the Enrich Prospect `http_request`
+producer and mapping `enrichedProspectId`.

package/skills/building-gtm-tables/references/uat-seed-prompts.md

@@ -0,0 +1,37 @@
+# UAT Seed Prompts
+
+Use these prompts against a live workflow table to exercise the full
+BLUEPRINT -> COMMIT -> VERIFY lifecycle.
+
+## 1. Enrich + Score
+
+Build a workflow table for a prospect list with LinkedIn URLs. Enrich every
+prospect, then score ICP fit for VP+ revenue, sales, marketing, or GTM leaders
+at B2B companies with an active outbound motion. Verify one row, then ask me for
+2-5 more rows for batch confirmation.
+
+Expected shape: `LinkedIn URL` -> `Enrich Prospect` -> `ICP Score`.
+
+## 2. Enrich + Score + Invite
+
+Build a workflow table that enriches each LinkedIn URL, scores ICP fit, and sends
+a LinkedIn invite only when the ICP Score is at least 70. Skip deferred LinkedIn
+action columns during row verification and show me the skipped/deferred list.
+After single-row verification passes, ask me to choose 2-5 more rows.
+
+Expected shape: `LinkedIn URL` -> `Enrich Prospect` -> `ICP Score` -> `Invite`.
+
+## 3. AI Column Escape Hatch
+
+Build a workflow table that takes a LinkedIn URL and a short research prompt,
+then writes a one-sentence summary of the prospect's latest relevant LinkedIn
+activity using an AI Column. Verify one row, then ask me for 2-5 more rows.
+
+Expected shape: `LinkedIn URL` + `Research Prompt` -> `Post Summary`.
+
+## Seeded Fault
+
+Before committing, intentionally test the validator by changing one blueprint
+column type to `http_requests`. Confirm the validator returns a `phantom_type`
+error and that no columns are committed. Then fix the type to `http_request` and
+continue with commit and verify.

package/skills/building-gtm-tables/references/verify-loop.md

@@ -0,0 +1,74 @@
+# Verify Loop
+
+## TOC
+
+- [Purpose](#purpose)
+- [Step 1: single-row verify](#step-1-single-row-verify)
+- [Step 2: status interpretation](#step-2-status-interpretation)
+- [Step 3: fix-forward loop](#step-3-fix-forward-loop)
+- [Step 4: Phase gate 3b batch confirmation](#step-4-phase-gate-3b-batch-confirmation)
+- [Skipped columns policy: option (d)](#skipped-columns-policy-option-d)
+
+## Purpose
+
+Verification proves the committed table graph actually works against rows. A
+successful commit is not enough; it only proves the column shape was accepted.
+
+## Step 1: single-row verify
+
+Pick a representative row with the required seed inputs. Run:
+
+```json
+sellable:verify_table_row({ "rowId": "ROW_ID", "skipColumnIds": [], "forceRerun": true })
+```
+
+Use `forceRerun: true` for the first pass unless the user explicitly asks to
+preserve cache behavior.
+
+## Step 2: status interpretation
+
+Treat these statuses as green for the row-level `ok:true` result:
+
+- `success`: the column ran or had a valid completed value.
+- `skipped`: the caller intentionally skipped this column.
+- `deferred_to_sweeper`: the runtime accepted the work and the sweeper owns the long-running part.
+- `condition_not_met`: the production run condition correctly blocked execution.
+
+Treat `error` as a fix-forward signal. Inspect the column id, config, and input
+mapping. If the condition was not met, explain the branch to the user instead
+of forcing it to run.
+
+## Step 3: fix-forward loop
+
+For a failing column:
+
+1. Identify whether the issue is config, missing producer data, wrong input key,
+   wrong run condition, or an external service error.
+2. Apply the smallest supported column/table change.
+3. Re-run `sellable:verify_table_row` on the same row.
+4. Stop and escalate after 3 failed attempts on the same column.
+
+Keep the user-facing update concrete: name the failing column and the precise
+config or dependency being corrected.
+
+## Step 4: Phase gate 3b batch confirmation
+
+Once the representative row is green, ask the user to pick 2-5 rows for a batch
+confirmation pass. Run verification for every selected row.
+
+The skill declares done only when all selected rows return `ok:true`. This
+Phase gate 3b is required. The skill does NOT declare done on single-row green alone.
+
+If a batch row fails and the representative row passed, prefer row-specific
+diagnosis first: missing LinkedIn URL, private profile, malformed post URL, no
+message source, or condition not met. Fix table config only when the failure is
+structural across rows.
+
+## Skipped columns policy: option (d)
+
+Wait and long-timer columns are skipped by passing their ids in
+`skipColumnIds`. This is option (d): caller-supplied skip list.
+
+Do not override `runCondition` at runtime. The swap-and-restore pattern is
+brittle, can be interrupted, and changes the very production behavior the
+verify loop is meant to inspect.