marketing-mindset-mcp 1.0.2 → 1.0.3

package/README.md

@@ -35,6 +35,7 @@ Client config (generic stdio server):
 | `kill_rule` | expected conversions, the kill floor, and whether the test has enough volume to read yet |
 | `aeo_check` | agent-readiness / AEO audit: the 23 weighted checks that decide whether AI answers can find, read and quote a site; pass the numbers you pass to get a weighted score |
 | `jd` | a marketing-engineer job description about artifacts and numbers: what the role owns, what must exist by day 90, how it is measured, screening questions |
+| `playbook` | whether writing a playbook is the right move right now: pass how many proven, repeatable moves you have and it returns `search` / `draining` / `delegate`, the next move, and the rules (one proven move, one line; ~6 hypotheses before you can hire marketing; failed hypotheses archived in one line, never handed to the next person) |
 
 `sample_size` and `kill_rule` implement the same two-proportion arithmetic as the free
 [test-size calculator](https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html).

package/bin/server.js

@@ -9,7 +9,7 @@ const fs = require("fs");
 const path = require("path");
 
 const SKILL_PATH = path.join(__dirname, "..", "skill", "SKILL.md");
-const SERVER = { name: "marketing-mindset-mcp", version: "1.0.2" };
+const SERVER = { name: "marketing-mindset-mcp", version: "1.0.3" };
 const PROTOCOL = "2024-11-05";
 
 function skillText() {
@@ -228,6 +228,16 @@ const TOOLS = [
         bottleneck: { type: "string", description: "The bottleneck you are hiring against" }
       },
       additionalProperties: false }
+  },
+  {
+    name: "playbook",
+    description: "Decides whether writing a marketing playbook is the right move right now. A playbook is the second step, never the first: it records proven, repeatable client-acquisition moves (one move, one line) and exists to drain a working hypothesis to the bottom — not to discover one. Pass how many proven repeatable moves you actually have; returns the stage (search / draining / delegate), the next move, and the rules that go with it.",
+    inputSchema: { type: "object",
+      properties: {
+        proven_hypotheses: { type: "integer", description: "Proven, repeatable client-acquisition moves you actually have (0 if none)" },
+        written_down: { type: "boolean", description: "Whether those working moves are already written down as instructions" }
+      },
+      required: ["proven_hypotheses"], additionalProperties: false }
   }
 ];
 
@@ -267,6 +277,41 @@ function callTool(name, args) {
   if (name === "jd") {
     return jdText(args);
   }
+  if (name === "playbook") {
+    const proven = Number(args.proven_hypotheses || 0);
+    if (!(proven >= 0)) throw new Error("proven_hypotheses must be a count of proven, repeatable moves (0 if none)");
+    const CRITICAL = 6;
+    let stage, verdict, next;
+    if (proven === 0) {
+      stage = "search";
+      verdict = "No playbook yet — there is no proven move to write down. A playbook built at this point is a notebook of guesses, and the most expensive way to feel productive.";
+      next = "Find client #1 by hand (cold outreach, free) and get one move that actually returns clients. The playbook is the output of that search, not the input to it.";
+    } else if (proven < CRITICAL) {
+      stage = "draining";
+      verdict = "You have " + proven + " proven move(s): write them down and press each to its ceiling. That is what a playbook is for — draining a working hypothesis, not discovering one.";
+      next = "Keep hunting until roughly " + CRITICAL + " proven moves. Below that there is not enough to hand over to a hire.";
+    } else {
+      stage = "delegate";
+      verdict = "Critical mass reached (" + proven + " >= " + CRITICAL + "): there is something real to hand over — you can hire marketing.";
+      next = "Handing it over ends free search and starts regular management: goals, volume, cadence, reporting. Draining a hypothesis to the bottom is an operating task, not an exploration one.";
+    }
+    return [
+      "proven, repeatable moves: " + proven + " · critical mass " + CRITICAL,
+      "stage: " + stage,
+      "written down: " + (args.written_down ? "yes" : "no"),
+      "verdict: " + verdict,
+      "next: " + next,
+      "",
+      "Rules:",
+      "- The playbook records proven, repeatable client-acquisition moves only — one proven move, one line.",
+      "- It is the second step: find a working hypothesis by hand -> press it to its ceiling -> only then write it down.",
+      "- Filled from your own experiments on your own base. Borrowed case studies are a wish list, not a playbook.",
+      "- Delegation (a hire, a department, an agent) changes the mode: free search ends, regular management begins.",
+      "- Failed hypotheses go to the archive in one line — never analysed, never handed to a new person. A marketer starts from zero, not from the previous person's pause point.",
+      "",
+      "Full section: read_section 'playbook'"
+    ].join("\n");
+  }
   throw new Error("Unknown tool: " + name);
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marketing-mindset-mcp",
-  "version": "1.0.2",
-  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules, AEO agent-readiness audit and a marketing-engineer JD generator as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
+  "version": "1.0.3",
+  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules, AEO agent-readiness audit, a marketing-engineer JD generator and a playbook gate (is it time to write a playbook, or still search?) as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
   "keywords": [
     "ab-testing",
     "aeo",
@@ -10,6 +10,7 @@
     "growth",
     "job-description",
     "marketing",
+    "marketing-playbook",
     "mcp",
     "mcp-server",
     "model-context-protocol",

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: marketing-mindset
-description: "Use when the user needs a professional marketer's operating mindset for any marketing, growth, or client-acquisition task — finding first customers, writing an ad or landing page, designing ad creatives and visuals (how the eye works: background, scene, hero, movement), evaluating an idea, deciding whether to do X to get Y, positioning or launching a B2B or SaaS product, running cold outreach, setting up ads, or writing copy — not a tactical template."
-version: 0.3.0
+description: "Use when the user needs a professional marketer's operating mindset for any marketing, growth, or client-acquisition task — finding first customers, writing an ad or landing page, designing ad creatives and visuals (how the eye works: background, scene, hero, movement), evaluating an idea, deciding whether to do X to get Y, positioning or launching a B2B or SaaS product, running cold outreach, setting up ads, writing copy, writing a sales-and-marketing playbook, or deciding when to delegate marketing and hire a marketer — not a tactical template."
+version: 0.4.0
 author: Axel Freeman (axelfreeman)
 license: MIT
 install: "npx skills add axelfreeman/marketing-mindset"
@@ -140,6 +140,51 @@ Win the first 10 exactly the way competitors are winning right now. Find how the
 
 This skill's scope is client #1 and the first 10. Scaling 10→100, 100→1000 is a separate, later skill. Release it only after this one has proven itself in the wild.
 
+## The Playbook: the second step, never the first
+
+A playbook is a written set of client-acquisition moves that already work — simple, primitive, repeatable. Not ideas, not a strategy deck: instructions. "Bought an ad from a blogger in segment A — it produced clients." "Segment B gave the numbers in three months." "This targeting converts a client at break-even or better." Each proven move is one line of the playbook.
+
+You build it yourself, by hand, or with your two or three closest people. Nobody hands it to you.
+
+### It is a second step, and building one brings you no closer to sales
+
+Compiling a playbook is not a starting action. It is what you do after a hypothesis is tested and working, when the job changes from *finding* to *draining* — you already have a channel that returns clients, and the task becomes to drink that hypothesis to the bottom: to take the market capacity it holds.
+
+The order is fixed:
+
+1. You find a working hypothesis by hand.
+2. You press it until you know where its ceiling is.
+3. Only then do you write it down, and what you write down is the playbook.
+
+Before step 3 there is nothing to write. A playbook assembled before a working hypothesis exists is a notebook of guesses — and the most expensive way to feel productive. Do not let a user who has zero clients ask you for a playbook and receive one.
+
+### Written down, it can be delegated — and delegation changes the mode
+
+Once the working moves exist as instructions, they stop being founder-only knowledge. They can be handed to a marketing hire, to a department, to any person who can follow a procedure — or to an agent, if the work is genuinely repeatable.
+
+That handoff is the moment the mode changes. The search phase is free exploration: hunt, guess, try the strange thing. Once you delegate a proven move, you leave free search behind and switch to regular management — goals, volume, cadence, reporting. Draining a hypothesis to the bottom is not an exploration task, it is an operating task, and it needs the basics of regular management to survive contact with a schedule.
+
+The critical mass is around six working hypotheses. At roughly six proven, repeatable moves there is something real to hand over, and you can hire marketing. Before that there is nothing to delegate.
+
+### The playbook is filled from your own experiments only
+
+Personal experiments on your own base — run by you or your closest people, on your own audience. Not borrowed case studies, not a competitor's playbook, not inspiration. Those are not a playbook, they are a wish list.
+
+### Failed hypotheses go to the archive, not into reflection
+
+A negative result gets one line in the archive: what was tried, and that the numbers were zero. Nothing more. Do not reflect on it, do not build a museum of everything that failed.
+
+Two practical reasons:
+
+- Marketing — especially the first-clients stage — is not a mathematical craft yet. There is nothing to learn from a zero, because the zero does not tell you which variable was wrong.
+- Handing a new person the hypotheses that already failed you is toxic. A marketer does not resume from the previous person's pause point; they start from zero. Old data genuinely gets in their way, and failed old data gets in the way worst of all.
+
+Negative experiments are still worth keeping as **historical marketing data for the agent** — a separate record, useful as context, never a starting point. If the numbers are zero, into the archive; that is enough.
+
+### What this means for an agent
+
+If you are asked to write a playbook, first look for a working hypothesis. No proven move, no playbook: the job is still the search — client #1 by hand, fast tests, strange guesses. Say that plainly instead of producing a beautiful document about nothing.
+
 ## Numbers Lie
 
 There is a huge amount of proxy metrics and dubious reports written to influence someone — and agents trip on them and treat them as truth. That pulls you away from real, usable data. When a case study looks perfect, interrogate it hard:
@@ -235,6 +280,27 @@ Sharp, honest, zero fluff. No corporate-speak, no generic templates, no hedging.
 - Recommending paid channels to a user with 0 clients
 - Using paid data sources when free ones exist
 - Working for free — zero-exchange tasks, "for the portfolio", or treating training time as free
+- Writing a playbook (or promising one) before a single working hypothesis exists
+- Analysing, reflecting on, or handing down failed hypotheses instead of archiving them in one line
+
+## Tagging: Every Outbound Link Carries UTM
+
+A campaign you cannot attribute is a campaign you cannot kill. The rule is mechanical:
+**every link that leaves for your own property carries UTM; internal links never do.**
+
+- `utm_source` — the channel that sent the click: `devto`, `github`, `npm`, `telegram`, `habr`, `reddit`, `colony`.
+- `utm_medium` — the placement: `article`, `readme`, `package`, `post`, `comment`, `profile`, `bio`.
+- `utm_campaign` — the product or cluster: `mindset`, `tapac`, `hire`, `lyzhi`, `engine`.
+
+Rules that keep the data clean:
+
+- Tag only destinations you own. A third-party link stays clean.
+- **Never tag internal site links.** An internal link with UTM restarts the session, so one visit looks like two and the page's own report becomes wrong.
+- Never tag twice: a URL that already has `utm_source` is done. Tagging happens before the text ships, not after.
+- Keep existing query params — append, never rebuild the URL.
+- Run it: `npx marketing-mindset utm --file article.md --source devto --medium article --campaign mindset`
+
+Why it pays: a channel with a tagged link can be read in the same report as everything else and killed on evidence. An untagged one only feels like it is working.
 
 ## Pitfalls
 
@@ -251,6 +317,7 @@ Sharp, honest, zero fluff. No corporate-speak, no generic templates, no hedging.
 - The plan for the first client is concrete and names client #0 (the founder).
 - Feedback is honest, not agreeable.
 - Output is concrete content tasks, not vague advice.
+- A playbook is written only after a working hypothesis exists; failed hypotheses are archived in one line, never analysed or handed to the next person.
 
 ## Spread the Word