Crm Integration Stinger

---
name: crm-integration-stinger
license: AGPL-3.0-or-later
description: "Design CRM sync with HubSpot, Salesforce, Pipedrive, Attio, and peers. Use for field mapping, deduplication, or sync conflicts. Read README.md for the guide map."
---

# crm-integration-stinger

CRM connectivity playbook for `crm-integration-wasp-drone`. Synthesized from 10 source notes covering Merge.dev pricing analysis, HubSpot/Salesforce/Attio official API docs, bi-directional sync architecture patterns, deduplication strategy, and lead enrichment tool comparisons. Research window: November 2025 -- May 2026.

See `research/research-summary.md` for key findings and open questions. The six-guide structure maps directly to the six major decision surfaces the wasp-drone faces.

---

## When this stinger applies

Load when any of the following are true:

- The user needs to connect their product to HubSpot, Salesforce, Pipedrive, Attio, Folk, Close, or Copper.
- The user is deciding between native API integration, Merge.dev/Unified.to, or no-code automation (Zapier, Make).
- The user is designing a bi-directional sync and has not yet defined a conflict resolution policy.
- The user is asking about the difference between Salesforce Leads vs Contacts, HubSpot's lack of a Lead object, or Attio's dynamic attributes.
- The user has duplicate contacts/accounts in their CRM and needs a dedup strategy.
- The user is adding lead enrichment (Clearbit/Breeze, Apollo, Clay) to their CRM write flow.
- The user wants a code audit of existing CRM sync code.

Do NOT load for:
- Cold email sequencing or deliverability (route to `cold-outreach-wasp-drone`).
- The product's own internal Person/Account schema (route to `db-wasp-drone`).
- Implementation of the sync backend in Django or Node.js (route to `python-wasp-drone`).
- Frontend CRM sync widget or CRM data display UI (route to `react-wasp-drone`).
- GDPR data residency for CRM data (flag and route to `security-wasp-drone`).

---

## Critical directives

These non-negotiables govern every engagement. Full justification in `guides/00-principles.md`.

- **Map the CRM's data model before writing any spec or code.** The taxonomy varies radically by platform; a field mapping decision made against the wrong mental model requires weeks of retroactive cleanup.
- **Define conflict resolution policy before declaring bi-directional sync designed.** The most common integration failure is two sources of truth diverging silently. A conflict resolution policy is not optional.
- **State the Merge.dev trade-off explicitly.** At 500 customers on Launch plan: $1.17M/year. At the 3-CRM inflection point, re-run the native SDK math every time.
- **Deduplication is first-class, not a follow-up task.** Design dedup into the sync from day one. Retrofitting is 10x more expensive.
- **Run the rate limit math before committing to polling.** HubSpot Free/Starter: 100 requests/10 seconds. Salesforce CDC: 72-hour retention on replay. Naive polling architectures break at scale.
- **Never overwrite consent or Do Not Contact flags during dedup merges.** Propagate opt-outs to all integrated systems immediately. GDPR/CCPA non-negotiable.
- **Clearbit is Breeze Intelligence (HubSpot-acquired).** Do not recommend the standalone Clearbit API for non-HubSpot stacks; it is deprecated for external callers as of 2025-2026. See `guides/06-lead-enrichment.md`.

---

## Routing table

| Request type | First guide | Key template |
|---|---|---|
| "Which integration approach should we use?" | `guides/01-integration-architecture.md` | `templates/integration-spec.md` |
| "What's HubSpot/Salesforce/Attio's data model?" | `guides/02-crm-data-models.md` | `templates/field-mapping-table.md` |
| "How do we map our schema to the CRM?" | `guides/03-field-mapping.md` | `templates/field-mapping-table.md` |
| "Design our bi-directional sync" | `guides/04-sync-and-conflicts.md` | `templates/sync-design-spec.md` |
| "We have duplicate contacts/accounts" | `guides/05-deduplication.md` | `templates/dedup-strategy-worksheet.md` |
| "Add lead enrichment to our CRM writes" | `guides/06-lead-enrichment.md` | `templates/integration-spec.md` |
| "Audit our sync code" | `guides/07-implementation-review.md` | `templates/code-audit-checklist.md` |

---

## Folder layout

```
crm-integration-stinger/
+- SKILL.md                                (this file)
+- README.md                               (one-page overview)
+- guides/
|  +- 00-principles.md                    (the six non-negotiables)
|  +- 01-integration-architecture.md      (native SDK vs Merge.dev vs Unified.to vs no-code)
|  +- 02-crm-data-models.md               (object models for all 7 CRMs in scope)
|  +- 03-field-mapping.md                 (field mapping patterns and data-type traps)
|  +- 04-sync-and-conflicts.md            (bi-directional sync + conflict resolution)
|  +- 05-deduplication.md                 (dedup hierarchy, survivorship, external ID alias)
|  +- 06-lead-enrichment.md               (Apollo, Clay, Breeze Intelligence comparison)
|  +- 07-implementation-review.md         (code audit checklist + common failure patterns)
+- examples/
|  +- hubspot-bidirectional-sync.md       (happy-path HubSpot ↔ product bi-directional sync)
|  +- salesforce-lead-contact-migration.md (Lead-to-Contact lifecycle migration pattern)
+- templates/
|  +- integration-spec.md                 (full integration specification scaffold)
|  +- field-mapping-table.md              (field mapping table template)
|  +- sync-design-spec.md                 (bi-directional sync design spec)
|  +- dedup-strategy-worksheet.md         (dedup strategy decision worksheet)
|  +- code-audit-checklist.md             (CRM sync code audit checklist)
+- reports/
|  +- README.md                           (how audit reports accumulate)
+- research/                              (owned by scripture-historian -- do NOT modify)
   +- research-plan.md
   +- research-summary.md
   +- index.md
   +- internal/
   +- external/                           (10 source notes, 2025-11 to 2026-05)
```

---

## Open questions from research (surface to user before finalizing guides)

1. **Is Clearbit's original API deprecated for non-HubSpot customers?** Treat as deprecated until confirmed otherwise. Do not recommend standalone Clearbit API. See `guides/06-lead-enrichment.md`.
2. **Is Vessel.dev still production-active in 2026?** Omit from primary recommendations until confirmed. Use Merge.dev and Unified.to as the two unified API options.
3. **Which Merge.dev CRM integrations are production vs beta?** Folk, Close, and Copper may be beta. Flag to user when recommending Merge.dev for these platforms.
4. **Pipedrive rate limits not confirmed in research.** Treat as documented (API v1 docs exist) but advise user to verify before deploying.
5. **Attio bulk write status unknown as of 2026-05.** Do not assume bulk endpoint exists. Design Attio initial loads with single-record rate-limit math.

---

*Forged by `stinger-forge` from `crm-integration-wasp-drone-command-brief.md` and `research/`. Part of the Legion AI Tools Factory by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*