clawskills-mcp 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP (Model Context Protocol) server that exposes [ClawSkills](https://github.com/Shanksg/clawskills) API integration skill docs to AI agents.
 
-ClawSkills currently contains 14 structured Markdown skill docs for SaaS APIs such as Salesforce, HubSpot, GitHub, Jira, Stripe, Notion, Slack, and Linear. Each skill tracks its own API version and `Last validated` date, while `clawskills-mcp` has its own npm version for the server itself.
+ClawSkills currently contains 14 structured Markdown skill docs plus workflow playbooks for cross-tool automations. Each skill tracks its own API version and `Last validated` date, while `clawskills-mcp` has its own npm version for the server itself.
 
 ---
 
@@ -46,6 +46,9 @@ docker run --rm -i clawskills-mcp
 | `list_skills` | List all available skill slugs with descriptions |
 | `get_skill` | Fetch a full skill doc or a specific section |
 | `search_skills` | Full-text search across all skill docs |
+| `list_playbooks` | List all available cross-tool workflow playbooks |
+| `get_playbook` | Fetch a full playbook by slug |
+| `search_playbooks` | Full-text search across all workflow playbooks |
 
 ### `list_skills`
 
@@ -71,17 +74,36 @@ Examples:
 
 Returns matching excerpts (±3 lines of context) grouped by skill, capped at 5 matches per skill.
 
+### `list_playbooks`
+
+No arguments. Returns all available playbooks.
+
+### `get_playbook`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | yes | Playbook slug: `zendesk-jira-bug-escalation`, `hubspot-asana-onboarding`, etc. Fuzzy matched. |
+
+### `search_playbooks`
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `query` | string | yes | Search string, e.g. `"idempotency"`, `"rollback"`, `"closed won"` |
+
+Returns matching excerpts (±3 lines of context) grouped by playbook, capped at 5 matches per playbook.
+
 ---
 
 ## Configuration
 
-Skills are bundled inside the npm package — no `SKILLS_DIR` configuration needed for the standard `npx` setup.
+Skills and playbooks are bundled inside the npm package — no extra configuration is needed for the standard `npx` setup.
 
-`SKILLS_DIR` is available if you want to point the server at a custom or local skills directory (e.g. your own forks of the docs):
+`SKILLS_DIR` and `PLAYBOOKS_DIR` are available if you want to point the server at custom or local content directories:
 
 | Env var | Default | Description |
 |---------|---------|-------------|
 | `SKILLS_DIR` | bundled `skills/` inside the package | Absolute path to a directory of `{slug}/skill.md` files |
+| `PLAYBOOKS_DIR` | bundled `playbooks/` inside the package | Absolute path to a directory of `{slug}.md` playbook files |
 
 ```json
 {
@@ -90,7 +112,8 @@ Skills are bundled inside the npm package — no `SKILLS_DIR` configuration need
       "command": "npx",
       "args": ["-y", "clawskills-mcp"],
       "env": {
-        "SKILLS_DIR": "/path/to/your/skills"
+        "SKILLS_DIR": "/path/to/your/skills",
+        "PLAYBOOKS_DIR": "/path/to/your/playbooks"
       }
     }
   }

package/dist/index.js

@@ -25,6 +25,19 @@ function resolveSkillsDir() {
     }
     return candidates[0];
 }
+function resolvePlaybooksDir() {
+    if (process.env.PLAYBOOKS_DIR)
+        return process.env.PLAYBOOKS_DIR;
+    const candidates = [
+        path.resolve(__dirname, "../../playbooks"),
+        path.resolve(__dirname, "../playbooks"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+}
 function resolvePackageVersion() {
     const packageJsonPath = path.resolve(__dirname, "../package.json");
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
@@ -49,6 +62,23 @@ function loadSkills(skillsDir) {
     process.stderr.write(`[clawskills-mcp] Loaded ${skills.size} skills: ${[...skills.keys()].join(", ")}\n`);
     return skills;
 }
+function loadPlaybooks(playbooksDir) {
+    const playbooks = new Map();
+    if (!fs.existsSync(playbooksDir)) {
+        process.stderr.write(`[clawskills-mcp] Playbooks directory not found: ${playbooksDir}\n`);
+        return playbooks;
+    }
+    const entries = fs.readdirSync(playbooksDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "INDEX.md")
+            continue;
+        const slug = entry.name.replace(/\.md$/, "");
+        const content = fs.readFileSync(path.join(playbooksDir, entry.name), "utf-8");
+        playbooks.set(slug, content);
+    }
+    process.stderr.write(`[clawskills-mcp] Loaded ${playbooks.size} playbooks: ${[...playbooks.keys()].join(", ")}\n`);
+    return playbooks;
+}
 // ---------------------------------------------------------------------------
 // Section extraction
 // ---------------------------------------------------------------------------
@@ -115,12 +145,15 @@ function findSkill(skills, name) {
     }
     return undefined;
 }
-function searchSkills(skills, query) {
+function findPlaybook(playbooks, name) {
+    return findSkill(playbooks, name);
+}
+function searchDocuments(documents, query) {
     const results = [];
     const lowerQuery = query.toLowerCase();
     const CONTEXT_LINES = 3;
     const MAX_PER_SKILL = 5;
-    for (const [slug, content] of skills.entries()) {
+    for (const [name, content] of documents.entries()) {
         const lines = content.split("\n");
         const excerpts = [];
         const usedRanges = [];
@@ -140,11 +173,17 @@ function searchSkills(skills, query) {
                 break;
         }
         if (excerpts.length > 0) {
-            results.push({ skill: slug, excerpts });
+            results.push({ name, excerpts });
         }
     }
     return results;
 }
+function searchSkills(skills, query) {
+    return searchDocuments(skills, query);
+}
+function searchPlaybooks(playbooks, query) {
+    return searchDocuments(playbooks, query);
+}
 // ---------------------------------------------------------------------------
 // Skill summary (first meaningful line)
 // ---------------------------------------------------------------------------
@@ -159,13 +198,15 @@ function skillSummary(content) {
 // ---------------------------------------------------------------------------
 // Exports for testing
 // ---------------------------------------------------------------------------
-export { resolveSkillsDir, resolvePackageVersion, loadSkills, extractSection, findSkill, searchSkills, skillSummary };
+export { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, };
 // ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
 const SKILLS_DIR = resolveSkillsDir();
+const PLAYBOOKS_DIR = resolvePlaybooksDir();
 const PACKAGE_VERSION = resolvePackageVersion();
 const skills = loadSkills(SKILLS_DIR);
+const playbooks = loadPlaybooks(PLAYBOOKS_DIR);
 const server = new Server({ name: "clawskills-mcp", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
 // List tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -201,11 +242,40 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["query"],
             },
         },
+        {
+            name: "list_playbooks",
+            description: "List all available ClawSkills workflow playbooks.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "get_playbook",
+            description: "Retrieve a ClawSkills workflow playbook by name (slug).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Playbook slug, e.g. 'zendesk-jira-bug-escalation'" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "search_playbooks",
+            description: "Search across workflow playbooks for a query string and return matching excerpts with context.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search query, e.g. 'idempotency', 'rollback', 'customer impact'" },
+                },
+                required: ["query"],
+            },
+        },
     ],
 }));
 // Call tools
 const GetSkillSchema = z.object({ name: z.string(), section: z.string().optional() });
+const GetPlaybookSchema = z.object({ name: z.string() });
 const SearchSkillsSchema = z.object({ query: z.string() });
+const SearchPlaybooksSchema = z.object({ query: z.string() });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     if (name === "list_skills") {
@@ -218,6 +288,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         });
         return { content: [{ type: "text", text: `Available skills (${skills.size}):\n\n${lines.join("\n")}` }] };
     }
+    if (name === "list_playbooks") {
+        if (playbooks.size === 0) {
+            return { content: [{ type: "text", text: "No playbooks loaded. Check PLAYBOOKS_DIR." }] };
+        }
+        const lines = [...playbooks.entries()].map(([slug, content]) => `• **${slug}** — ${skillSummary(content)}`);
+        return { content: [{ type: "text", text: `Available playbooks (${playbooks.size}):\n\n${lines.join("\n")}` }] };
+    }
     if (name === "get_skill") {
         const parsed = GetSkillSchema.safeParse(args);
         if (!parsed.success) {
@@ -256,13 +333,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return { content: [{ type: "text", text: `No results found for "${query}".` }] };
         }
         const output = results
-            .map(({ skill, excerpts }) => {
+            .map(({ name: skill, excerpts }) => {
             const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
             return `### ${skill}\n\n${blocks}`;
         })
             .join("\n\n---\n\n");
         return { content: [{ type: "text", text: `Search results for "${query}":\n\n${output}` }] };
     }
+    if (name === "get_playbook") {
+        const parsed = GetPlaybookSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const slug = findPlaybook(playbooks, parsed.data.name);
+        if (!slug) {
+            const available = [...playbooks.keys()].join(", ");
+            return {
+                content: [{ type: "text", text: `Playbook "${parsed.data.name}" not found. Available playbooks: ${available}` }],
+                isError: true,
+            };
+        }
+        return { content: [{ type: "text", text: playbooks.get(slug) }] };
+    }
+    if (name === "search_playbooks") {
+        const parsed = SearchPlaybooksSchema.safeParse(args);
+        if (!parsed.success) {
+            return { content: [{ type: "text", text: `Invalid arguments: ${parsed.error.message}` }], isError: true };
+        }
+        const { query } = parsed.data;
+        const results = searchPlaybooks(playbooks, query);
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: `No playbook results found for "${query}".` }] };
+        }
+        const output = results
+            .map(({ name: playbook, excerpts }) => {
+            const blocks = excerpts.map((e, i) => `--- match ${i + 1} ---\n${e}`).join("\n\n");
+            return `### ${playbook}\n\n${blocks}`;
+        })
+            .join("\n\n---\n\n");
+        return { content: [{ type: "text", text: `Playbook search results for "${query}":\n\n${output}` }] };
+    }
     return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
 });
 // ---------------------------------------------------------------------------

package/dist/index.test.js

@@ -3,9 +3,10 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { resolveSkillsDir, resolvePackageVersion, loadSkills, extractSection, findSkill, searchSkills, skillSummary } from "./index.js";
+import { resolveSkillsDir, resolvePlaybooksDir, resolvePackageVersion, loadSkills, loadPlaybooks, extractSection, findSkill, findPlaybook, searchSkills, searchPlaybooks, skillSummary, } from "./index.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REAL_SKILLS_DIR = path.resolve(__dirname, "../../skills");
+const REAL_PLAYBOOKS_DIR = path.resolve(__dirname, "../../playbooks");
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -18,6 +19,13 @@ function makeTempSkillsDir(skills) {
     }
     return dir;
 }
+function makeTempPlaybooksDir(playbooks) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawskills-playbooks-test-"));
+    for (const [slug, content] of Object.entries(playbooks)) {
+        fs.writeFileSync(path.join(dir, `${slug}.md`), content, "utf-8");
+    }
+    return dir;
+}
 const SAMPLE_CONTENT = `# GitHub Skill
 
 A skill doc for GitHub API.
@@ -44,11 +52,17 @@ Scopes: repo, read:user, etc.
 POST /repos/{owner}/{repo}/issues
 `;
 let tempDir;
+let tempPlaybooksDir;
 beforeAll(() => {
     tempDir = makeTempSkillsDir({ github: SAMPLE_CONTENT, salesforce: "# Salesforce\nCRM platform.\n## Overview\nSalesforce is a CRM." });
+    tempPlaybooksDir = makeTempPlaybooksDir({
+        "zendesk-jira": "# Zendesk -> Jira\n\nEscalate bugs from support into engineering.\n\n## Idempotency\n\nUse zendesk:{ticket_id}.",
+        "hubspot-asana": "# HubSpot -> Asana\n\nCreate onboarding work from closed won deals.",
+    });
 });
 afterAll(() => {
     fs.rmSync(tempDir, { recursive: true, force: true });
+    fs.rmSync(tempPlaybooksDir, { recursive: true, force: true });
 });
 // ---------------------------------------------------------------------------
 // loadSkills
@@ -86,6 +100,12 @@ describe("resolveSkillsDir", () => {
         expect(loadSkills(resolveSkillsDir()).has("stripe")).toBe(true);
     });
 });
+describe("resolvePlaybooksDir", () => {
+    it("prefers the canonical repo-root playbooks directory", () => {
+        expect(path.basename(resolvePlaybooksDir())).toBe("playbooks");
+        expect(loadPlaybooks(resolvePlaybooksDir()).has("zendesk-jira-bug-escalation")).toBe(true);
+    });
+});
 describe("resolvePackageVersion", () => {
     it("matches package.json", () => {
         const packageJsonPath = path.resolve(__dirname, "../package.json");
@@ -94,6 +114,20 @@ describe("resolvePackageVersion", () => {
     });
 });
 // ---------------------------------------------------------------------------
+// loadPlaybooks
+// ---------------------------------------------------------------------------
+describe("loadPlaybooks", () => {
+    it("loads markdown files from a directory", () => {
+        const playbooks = loadPlaybooks(tempPlaybooksDir);
+        expect(playbooks.size).toBe(2);
+        expect(playbooks.has("zendesk-jira")).toBe(true);
+    });
+    it("returns empty map for missing directory", () => {
+        const playbooks = loadPlaybooks("/nonexistent/playbooks/path");
+        expect(playbooks.size).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
 // findSkill
 // ---------------------------------------------------------------------------
 describe("findSkill", () => {
@@ -119,6 +153,18 @@ describe("findSkill", () => {
         expect(findSkill(skills, "zzznomatch")).toBeUndefined();
     });
 });
+describe("findPlaybook", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(tempPlaybooksDir);
+    });
+    it("returns key for exact match", () => {
+        expect(findPlaybook(playbooks, "zendesk-jira")).toBe("zendesk-jira");
+    });
+    it("matches normalized input", () => {
+        expect(findPlaybook(playbooks, "zendesk jira")).toBe("zendesk-jira");
+    });
+});
 // ---------------------------------------------------------------------------
 // extractSection
 // ---------------------------------------------------------------------------
@@ -153,7 +199,7 @@ describe("searchSkills", () => {
     it("returns results for a matching query", () => {
         const results = searchSkills(skills, "Personal Access Token");
         expect(results.length).toBeGreaterThan(0);
-        expect(results[0].skill).toBe("github");
+        expect(results[0].name).toBe("github");
         expect(results[0].excerpts.length).toBeGreaterThan(0);
     });
     it("is case-insensitive", () => {
@@ -172,6 +218,17 @@ describe("searchSkills", () => {
         expect(results[0].excerpts.length).toBeLessThanOrEqual(5);
     });
 });
+describe("searchPlaybooks", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(tempPlaybooksDir);
+    });
+    it("returns results for a matching query", () => {
+        const results = searchPlaybooks(playbooks, "idempotency");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].name).toBe("zendesk-jira");
+    });
+});
 // ---------------------------------------------------------------------------
 // skillSummary
 // ---------------------------------------------------------------------------
@@ -234,3 +291,25 @@ describe("real skills", () => {
         }
     });
 });
+describe("real playbooks", () => {
+    let playbooks;
+    beforeAll(() => {
+        playbooks = loadPlaybooks(REAL_PLAYBOOKS_DIR);
+    });
+    it("loads all expected playbooks", () => {
+        const knownPlaybooks = [
+            "hubspot-asana-onboarding",
+            "salesforce-hubspot-lead-sync",
+            "zendesk-jira-bug-escalation",
+        ];
+        for (const slug of knownPlaybooks) {
+            expect(playbooks.has(slug), `Missing playbook: ${slug}`).toBe(true);
+        }
+    });
+    it("every playbook has a non-empty summary line", () => {
+        for (const [slug, content] of playbooks.entries()) {
+            const summary = skillSummary(content);
+            expect(summary, `${slug}: empty summary`).not.toBe("");
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "license": "MIT",
   "author": "ClawSkills Contributors",
@@ -30,7 +30,8 @@
   },
   "files": [
     "dist/",
-    "skills/"
+    "skills/",
+    "playbooks/"
   ],
   "scripts": {
     "sync:skills": "node scripts/sync-skills.mjs",

package/playbooks/INDEX.md

@@ -0,0 +1,32 @@
+# Playbooks Index
+
+Workflow playbooks are end-to-end guides for multi-system automations. They complement the per-tool `skill.md` files by defining the orchestration layer: trigger, source of truth, field mapping, idempotency, failure policy, and operational checks.
+
+## Available playbooks
+
+| Playbook | Systems | Primary use case |
+|----------|---------|------------------|
+| [Zendesk Ticket -> Jira Bug escalation](./zendesk-jira-bug-escalation.md) | Zendesk, Jira | Escalate support-confirmed defects into engineering workflow |
+| [HubSpot Deal Won -> Asana onboarding kickoff](./hubspot-asana-onboarding.md) | HubSpot, Asana | Start implementation or onboarding work when a deal closes |
+| [Salesforce Lead -> HubSpot Contact sync](./salesforce-hubspot-lead-sync.md) | Salesforce, HubSpot | Mirror new/updated leads into marketing automation without duplicates |
+
+## Playbook template
+
+Each playbook should define:
+- Business trigger
+- Systems involved
+- Source of truth
+- Sequence of operations
+- Field mapping
+- Idempotency and dedup keys
+- Retry / partial-failure policy
+- Reconciliation / rollback guidance
+- Observability checks
+
+## Next candidates
+
+- Slack incident -> Jira issue
+- GitHub PR -> Slack notification
+- Zendesk -> Salesforce case sync
+- Stripe payment failed -> HubSpot task
+- Notion request -> Asana task

package/playbooks/hubspot-asana-onboarding.md

@@ -0,0 +1,76 @@
+# HubSpot Deal Won -> Asana Onboarding Kickoff
+
+## Goal
+
+Create onboarding or implementation work in Asana as soon as a HubSpot Deal is marked closed won.
+
+## Systems involved
+
+- HubSpot: sales pipeline, deal state, customer/account context
+- Asana: delivery execution, onboarding tasks, project coordination
+
+## Trigger
+
+- HubSpot webhook `deal.propertyChange` where `dealstage` moves into the closed-won stage
+
+## Source of truth
+
+- Commercial state and customer/account metadata: HubSpot
+- Delivery execution and task/project state: Asana
+- Workflow linkage: integration database or HubSpot custom property storing the Asana `gid`
+
+## Sequence
+
+1. Receive the HubSpot webhook and verify it corresponds to the target pipeline/stage.
+2. Fetch the Deal, associated Company, and primary Contact.
+3. Check whether an Asana task/project already exists for the Deal ID.
+4. Create the onboarding project or kickoff task in Asana.
+5. Populate notes and custom fields with customer, owner, ARR, plan, and target launch details.
+6. Persist the Asana `gid` back to HubSpot or your integration store.
+7. Notify the implementation owner or CSM if required.
+
+## Field mapping
+
+| HubSpot | Asana |
+|---------|-------|
+| `dealId` | external mapping / custom field |
+| `dealname` | task/project name |
+| associated company name | notes / title suffix |
+| deal owner | assignee |
+| close date | kickoff anchor or due date |
+| ARR / amount | custom field |
+| onboarding tier | custom field / template choice |
+
+## Idempotency
+
+- Dedup key: HubSpot Deal ID
+- Webhook delivery is at-least-once, so check your mapping store before creation
+- If using project templates, ensure only one project is generated per Deal ID
+
+## Retry and partial failure policy
+
+- Retry transient Asana failures with bounded backoff
+- If Asana create succeeds but write-back to HubSpot fails, recover by searching the mapping store on the next run
+- Validation errors should move the record into a manual review queue with the Deal ID and failing field
+
+## Reconciliation
+
+- Daily job: compare all closed-won deals in the last 30 days against Asana kickoff artifacts
+- Backfill missing Asana `gid` values into HubSpot
+- Flag onboarding projects with no matching active deal
+
+## Rollback guidance
+
+- If a Deal reopens or is marked closed-lost shortly after creation, archive or cancel the Asana project/task rather than deleting it
+- Preserve the linkage so repeated stage churn does not create duplicates
+
+## Observability
+
+- Count created onboarding projects/tasks per day
+- Alert on webhook processing failures and duplicate prevention hits
+- Track time from closed won to Asana kickoff creation
+
+## Related skills
+
+- [`skills/hubspot/skill.md`](../skills/hubspot/skill.md)
+- [`skills/asana/skill.md`](../skills/asana/skill.md)

package/playbooks/salesforce-hubspot-lead-sync.md

@@ -0,0 +1,78 @@
+# Salesforce Lead -> HubSpot Contact Sync
+
+## Goal
+
+Mirror new or updated Salesforce Leads into HubSpot Contacts so marketing and lifecycle workflows stay current without creating duplicates.
+
+## Systems involved
+
+- Salesforce: CRM of record for lead capture and sales qualification
+- HubSpot: marketing automation, nurture, lifecycle segmentation
+
+## Trigger
+
+- Scheduled incremental sync using Salesforce `LastModifiedDate`
+- Optional near-real-time trigger from Salesforce CDC or platform events
+
+## Source of truth
+
+- Lead identity and sales-owned fields: Salesforce
+- Marketing engagement and automation state: HubSpot
+- Identity dedup anchor: email, with explicit mapping store as a secondary safeguard
+
+## Sequence
+
+1. Query Salesforce Leads modified since the last sync watermark, with a small overlap window.
+2. Skip converted Leads and Leads with no email.
+3. Search HubSpot Contacts by email.
+4. If a Contact exists, update it with mapped fields.
+5. If no Contact exists, create one and persist the mapping.
+6. Record sync outcome per Lead so failed rows can be retried independently.
+7. Advance the watermark only after all rows are processed or quarantined.
+
+## Field mapping
+
+| Salesforce Lead | HubSpot Contact |
+|-----------------|-----------------|
+| `Lead.Id` | custom property `salesforce_lead_id` or integration DB |
+| `Email` | `email` |
+| `FirstName` | `firstname` |
+| `LastName` | `lastname` |
+| `Company` | `company` |
+| `Phone` | `phone` |
+| `LeadSource` | custom source property |
+| `Status` | derived `lifecyclestage` mapping |
+
+## Idempotency
+
+- Primary dedup key: normalized email
+- Secondary correlation key: Salesforce Lead ID
+- Do not use HubSpot batch create blindly for unknown contacts; search first
+
+## Retry and partial failure policy
+
+- Retry transient HubSpot rate-limit and availability errors per shard
+- Quarantine `400` validation failures with Lead ID, email, and failing field names
+- If one row fails, continue the rest of the batch and surface a remediation report
+
+## Reconciliation
+
+- Daily compare: Salesforce Leads updated in the last 24 hours vs HubSpot Contacts carrying `salesforce_lead_id`
+- Repair records where the ID mapping is missing but email matches
+- Flag email collisions where multiple Salesforce Leads compete for one HubSpot Contact
+
+## Rollback guidance
+
+- Avoid destructive deletes across systems
+- If a bad sync overwrites HubSpot fields, restore from HubSpot history or your sync audit log and re-run the corrected mapping
+
+## Observability
+
+- Track processed, created, updated, quarantined, and retried rows per run
+- Alert on spikes in duplicate resolution or validation failures
+- Monitor watermark lag so the sync does not silently fall behind
+
+## Related skills
+
+- [`skills/salesforce/skill.md`](../skills/salesforce/skill.md)
+- [`skills/hubspot/skill.md`](../skills/hubspot/skill.md)

package/playbooks/zendesk-jira-bug-escalation.md

@@ -0,0 +1,79 @@
+# Zendesk Ticket -> Jira Bug Escalation
+
+## Goal
+
+Escalate a Zendesk support ticket into Jira when support determines the issue is a product defect that engineering must track and resolve.
+
+## Systems involved
+
+- Zendesk: intake, customer communication, support triage
+- Jira: engineering backlog, bug lifecycle, fix tracking
+
+## Trigger
+
+Any of:
+- Zendesk ticket gets tag `engineering`
+- Custom field `issue_type` changes to `bug`
+- Ticket priority becomes `urgent` and product area is set
+
+## Source of truth
+
+- Customer communication and ticket state: Zendesk
+- Engineering execution state: Jira
+- Escalation linkage: integration database or mirrored external ID field
+
+## Sequence
+
+1. Receive the Zendesk webhook or consume the ticket via Incremental Export.
+2. Build a deterministic correlation key: `zendesk:{ticket_id}`.
+3. Search Jira for an existing issue with that correlation key in a custom field or label.
+4. If no issue exists, create a Jira Bug with summary, reproduction notes, impact, and Zendesk URL.
+5. If an issue already exists, update priority, labels, assignee, and current reproduction context.
+6. Write the Jira issue key back to Zendesk as an internal note or custom field.
+7. Optionally mirror selected Jira status changes back to Zendesk after state mapping is finalized.
+
+## Field mapping
+
+| Zendesk | Jira |
+|---------|------|
+| `ticket.id` | custom external ID / label |
+| `subject` | `summary` |
+| latest public comment | `description` |
+| `priority` | `priority` |
+| `tags` | `labels` |
+| requester org / account | custom customer field or component |
+| product area custom field | component / label |
+
+## Idempotency
+
+- Dedup key: `zendesk:{ticket_id}`
+- Before create, always search Jira by dedup key
+- Zendesk webhooks are at-least-once delivery, so the create path must be safe to replay
+
+## Retry and partial failure policy
+
+- Retry transient Jira failures (`429`, `503`) with bounded exponential backoff
+- Do not retry `400` field validation errors blindly; quarantine and surface them
+- If Jira create succeeds but Zendesk write-back fails, reconcile by searching Jira with the dedup key on the next run
+
+## Reconciliation
+
+- Daily job: compare Zendesk tickets tagged `engineering` against Jira bugs with the dedup key
+- Repair missing backlinks in Zendesk
+- Flag Jira issues missing an active Zendesk ticket counterpart
+
+## Rollback guidance
+
+- If a Jira issue was created in error, transition it to a closed/cancelled state instead of deleting it
+- Remove the escalation tag or set a custom field in Zendesk to prevent automatic recreation
+
+## Observability
+
+- Count escalations per day
+- Alert on create failures, write-back failures, or rising duplicate-detection rates
+- Track mean time from Zendesk escalation to Jira issue creation
+
+## Related skills
+
+- [`skills/zendesk/skill.md`](../skills/zendesk/skill.md)
+- [`skills/jira/skill.md`](../skills/jira/skill.md)

package/skills/INDEX.md

@@ -3,6 +3,7 @@
 A curated library of integration skill documents for the most common SaaS platforms used in go-to-market and operations workflows. Each skill doc teaches an agent or automation builder how to reliably use that platform's API for high-value, production-grade workflows.
 
 → See [ROADMAP.md](./ROADMAP.md) for the prioritized build plan, phased milestones, and governance model.
+→ Cross-tool workflow guides now live in [`../playbooks/INDEX.md`](../playbooks/INDEX.md).
 
 ---
 

package/skills/ROADMAP.md

@@ -12,14 +12,14 @@ This skill set enables end-to-end automation and integration across the most com
 
 ---
 
-## Current state (as of 2026-03-10)
+## Current state (as of 2026-03-12)
 
 ### What's shipped
 
 | Layer | Status |
 |-------|--------|
 | **14 skill docs** — Monday.com, Salesforce, Jira, Dynamics 365, HubSpot, ServiceNow, Zendesk, Asana, GitHub, Figma, Slack, Stripe, Notion, Linear | ✅ Live |
-| **MCP server** — `clawskills-mcp` v0.3.6 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
+| **MCP server** — `clawskills-mcp` v0.4.0 on npm; `list_skills`, `get_skill`, `search_skills` | ✅ Live |
 | **CI pipeline** — build + test on every push/PR via `ci.yml` | ✅ Live |
 | **Release automation** — `release.yml` workflow_dispatch → bump, tag, npm publish via OIDC | ✅ Live |
 | **Test suite** — Vitest unit tests + real-skills validation (required sections, ≥5 KB, all 14 tools) | ✅ Live |
@@ -83,7 +83,7 @@ The repo now needs tighter alignment between the canonical `skills/` directory,
 | Channel | Status | Next action |
 |---------|--------|-------------|
 | GitHub (public) | Ready to flip | Make repo public |
-| npm (`clawskills-mcp`) | ✅ Live — v0.3.6 | Maintain via `release.yml` |
+| npm (`clawskills-mcp`) | ✅ Live — v0.4.0 | Maintain via `release.yml` |
 | MCP registry listings | Not submitted | Submit to glama.ai, mcp.so, smithery.ai after public launch |
 | Docs website | Planned | Mintlify — fastest path to SEO-friendly browsable docs |
 | Lane A vs B | TBD | Revisit after first traction signals from public launch |
@@ -108,6 +108,43 @@ Each recipe lives as a `## Cross-tool recipe` appendix section in the relevant p
 
 ---
 
+### Priority 5 — Workflow playbooks and retrieval UX
+
+The next product layer is workflow-first guidance, not only tool-by-tool references. This means shipping opinionated playbooks that show how multiple systems fit together operationally, then exposing them cleanly through MCP.
+
+**Backlog:**
+- Add a `playbooks/` directory with high-value cross-tool workflows
+- Ship 3 flagship playbooks first:
+  - Zendesk Ticket -> Jira Bug escalation
+  - HubSpot Deal Won -> Asana onboarding kickoff
+  - Salesforce Lead -> HubSpot Contact sync
+- Expand to additional high-frequency workflows:
+  - Slack incident -> Jira issue
+  - GitHub PR -> Slack notification
+  - Zendesk -> Salesforce case sync
+  - Stripe payment failed -> HubSpot task
+  - Notion request -> Asana task
+- Standardize each playbook format:
+  - business trigger
+  - systems involved
+  - source-of-truth decision
+  - field mapping
+  - idempotency strategy
+  - retry and partial-failure policy
+  - reconciliation and rollback guidance
+  - observability / alerting checks
+- Expose playbooks through MCP after the doc layer stabilizes:
+  - `list_playbooks`
+  - `get_playbook`
+  - search/ranking that prefers recipes and playbooks over generic mentions
+
+**Acceptance criteria:**
+- [ ] At least 3 production-grade playbooks checked into the repo
+- [ ] README and INDEX reference the playbooks layer
+- [ ] MCP server plan defined for playbook retrieval and discovery
+
+---
+
 ## Prioritization framework
 
 Each skill/recipe is scored on five dimensions (1–5 each):