@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-twenty-crm-v1/templates/import-mapping.md

@@ -0,0 +1,139 @@
+# Import Mapping — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Source CRM / tool:** [e.g. Salesforce / HubSpot / Apollo CSV / Airtable]  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## 1. SOURCE EXPORT FORMAT
+
+**Format:** `[CSV / JSON / API response]`  
+**Export method:** [e.g. "Apollo: Settings > Exports > All Contacts as CSV"]  
+**Encoding:** `UTF-8`  
+**Record count (estimated):** [N]  
+**Date of export:** YYYY-MM-DD
+
+---
+
+## 2. PERSON RECORD MAPPING
+
+**Dedup key:** `emails.primaryEmail`  
+**Import mode:** `[insert-only / merge]`
+
+| Source column | Source type | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|---|
+| `First Name` | string | → | `Person` | `name.firstName` | none |
+| `Last Name` | string | → | `Person` | `name.lastName` | none |
+| `Email` | string | → | `Person` | `emails.primaryEmail` | lowercase, trim |
+| `Phone` | string | → | `Person` | `phones.primaryPhoneNumber` | none |
+| `Title` | string | → | `Person` | `position` | none |
+| `LinkedIn URL` | string | → | `Person` | `linkedInLink.url` | none |
+| `Company Name` | string | → | `Company` | `name` | create or link |
+| `[Source column]` | [type] | → | `[Object]` | `[field]` | [transformation] |
+
+**Columns to skip (no mapping):**
+
+| Source column | Reason |
+|---|---|
+| `[column]` | [reason — e.g. "internal ID not needed in Twenty"] |
+
+---
+
+## 3. COMPANY RECORD MAPPING
+
+**Dedup key:** `domain`  
+**Import mode:** `[insert-only / merge]`
+
+| Source column | Source type | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|---|
+| `Company Name` | string | → | `Company` | `name` | none |
+| `Website` | string | → | `Company` | `domain` | strip `https://` prefix, strip trailing `/` |
+| `Employee Count` | integer | → | `Company` | `employees` | integer cast |
+| `Industry` | string | → | `Company` | `[custom field]` | none |
+| `[Source column]` | [type] | → | `Company` | `[field]` | [transformation] |
+
+---
+
+## 4. OPPORTUNITY RECORD MAPPING (if applicable)
+
+**Dedup key:** [opportunity name + company combination — no direct dedup key]  
+**Import mode:** `[insert-only]`
+
+| Source column | Source type | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|---|
+| `Deal Name` | string | → | `Opportunity` | `name` | none |
+| `Stage` | string | → | `Opportunity` | `stage` | see stage map below |
+| `Amount` | number | → | `Opportunity` | `amount.amountMicros` | multiply by 1,000,000 |
+| `Currency` | string | → | `Opportunity` | `amount.currencyCode` | uppercase (e.g. USD) |
+| `Close Date` | date | → | `Opportunity` | `closeDate` | ISO 8601 (YYYY-MM-DD) |
+
+**Stage mapping:**
+
+| Source stage value | → | Twenty stage value |
+|---|---|---|
+| `[New]` | → | `LEAD` |
+| `[Qualified]` | → | `QUALIFIED` |
+| `[Discovery Call]` | → | `DEMO` |
+| `[Proposal Sent]` | → | `PROPOSAL` |
+| `[Won]` | → | `CLOSED_WON` |
+| `[Lost]` | → | `CLOSED_LOST` |
+
+---
+
+## 5. TRANSFORMATION RULES
+
+| Rule | Field | Input pattern | Output pattern |
+|---|---|---|---|
+| Domain normalization | `Company.domain` | `https://acme.com/` | `acme.com` |
+| Email lowercase | `Person.emails.primaryEmail` | `Jane@ACME.COM` | `jane@acme.com` |
+| Amount to micros | `Opportunity.amount.amountMicros` | `10000` | `10000000000` |
+| Date to ISO 8601 | `Opportunity.closeDate` | `04/15/2026` | `2026-04-15` |
+
+---
+
+## 6. IMPORT SEQUENCE
+
+1. **Pre-import clean:**
+   - Remove records with blank email (Person) or blank domain (Company)
+   - Deduplicate within the CSV itself (keep most recent by modification date)
+   - Normalize email addresses to lowercase
+
+2. **Company import first:**
+   - Import Company CSV before Person CSV so that Person-Company links can be resolved
+
+3. **Person import:**
+   - Run Person import with company linking enabled
+   - Review linked count vs. unlinked count in import summary
+
+4. **Opportunity import (if applicable):**
+   - Run after Person and Company imports
+   - Confirm `pointOfContact` and company relations are set
+
+5. **Post-import audit:** see section 7
+
+---
+
+## 7. POST-IMPORT VALIDATION
+
+| Check | Expected result | Action if failed |
+|---|---|---|
+| Total record count | Within ±2% of source count | Check error log |
+| Duplicate email check | 0 duplicates | Merge or remove duplicates |
+| Company linkage | ≥ 90% of Persons linked to a Company | Review unlinked persons |
+| Required fields | 0 blank required fields | Enrich manually |
+| Stage mapping | All stages are valid Twenty values | Fix mapping and re-import affected rows |
+
+---
+
+## 8. ROLLBACK PLAN
+
+If the import produces significant data quality issues:
+
+1. Note the import timestamp
+2. Use the Twenty audit log to identify all records created after that timestamp
+3. Bulk delete the affected records via the GraphQL API using a `deleteMany` mutation
+4. Fix the source CSV and re-import
+
+**Contact the developer** if bulk delete is needed — do not manually delete records one by one.

package/assets/worker-kits/growthub-twenty-crm-v1/templates/integration-handoff.md

@@ -0,0 +1,190 @@
+# Integration Handoff — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Handoff from:** [CRM Operator / Consultant]  
+**Handoff to:** [Developer / DevOps]
+
+---
+
+## PURPOSE
+
+This document gives the implementing developer everything needed to connect [CLIENT NAME]'s external tools to their Twenty CRM workspace without needing to ask follow-up questions.
+
+---
+
+## 1. SYSTEM INTEGRATION DIAGRAM
+
+```text
+[Apollo / Clay]
+     |
+     | CSV export or API
+     ▼
+[Import Script / Enrichment Job]
+     |
+     | GraphQL mutation batch
+     ▼
+[Twenty CRM API] ─────── workspace: [workspace-id]
+     ▲
+     |
+     | Outbound webhooks
+     ▼
+[Slack / Notification endpoint]
+
+[Stripe]
+     |
+     | webhook: customer.created
+     ▼
+[Webhook handler endpoint]
+     |
+     | GraphQL mutation
+     ▼
+[Twenty CRM API]
+
+[Intercom]
+     |
+     | webhook: conversation.created
+     ▼
+[Webhook handler endpoint]
+     |
+     | GraphQL mutation (create Note)
+     ▼
+[Twenty CRM API]
+```
+
+---
+
+## 2. CREDENTIALS REQUIRED
+
+**Types only — do not store values in this document.**
+
+| Secret | Type | Where to get it | Where to store it |
+|---|---|---|---|
+| `TWENTY_API_TOKEN` | Bearer token | Twenty: Settings > API > Tokens | `.env` / secrets manager |
+| `TWENTY_API_URL` | URL string | Twenty workspace URL | `.env` |
+| `STRIPE_WEBHOOK_SECRET` | Webhook signing secret | Stripe: Developers > Webhooks | `.env` / secrets manager |
+| `INTERCOM_WEBHOOK_SECRET` | Webhook signing secret | Intercom: Settings > Developers | `.env` / secrets manager |
+| `APOLLO_API_KEY` | API key | Apollo: Settings > API | `.env` / secrets manager |
+
+---
+
+## 3. ENDPOINT CONTRACTS
+
+### Twenty GraphQL API
+
+```
+URL:     <TWENTY_API_URL>/graphql
+Method:  POST
+Auth:    Authorization: Bearer <TWENTY_API_TOKEN>
+Type:    application/json
+```
+
+### Twenty REST API
+
+```
+URL:     <TWENTY_API_URL>/api/objects/<object-name>
+Method:  GET / POST / PATCH / DELETE
+Auth:    Authorization: Bearer <TWENTY_API_TOKEN>
+Type:    application/json
+```
+
+### Inbound webhook receiver (to be built by developer)
+
+```
+URL:     https://[your-domain]/webhooks/stripe  (example)
+Method:  POST
+Auth:    Validate STRIPE_WEBHOOK_SECRET signature header
+Handles: customer.created, customer.subscription.updated
+```
+
+---
+
+## 4. DATA FLOW — ENRICHMENT PIPELINE
+
+**Sequence:**
+
+1. Enrichment job reads Apollo export (CSV or API)
+2. For each record:
+   a. Check if `email` already exists in Twenty (GraphQL query)
+   b. If match found: update Person record (GraphQL mutation: `updatePerson`)
+   c. If no match: create Person record (GraphQL mutation: `createPerson`)
+   d. Check if company domain already exists in Twenty
+   e. If no match: create Company record (`createCompany`) and link to Person
+3. Log all results (created, updated, skipped, error) to output file
+4. Report: total processed, errors, duplicates merged
+
+**Key GraphQL operations:**
+
+- `people` query — check for existing Person by email
+- `createPerson` mutation — insert new Person
+- `updatePerson` mutation — merge enrichment fields
+- `createCompany` mutation — insert new Company
+- `companies` query — check for existing Company by domain
+
+---
+
+## 5. DATA FLOW — STRIPE WEBHOOK
+
+**Sequence:**
+
+1. Stripe fires `customer.created` event to webhook receiver
+2. Receiver validates `Stripe-Signature` header using `STRIPE_WEBHOOK_SECRET`
+3. Receiver extracts: `email`, `name`, `metadata.company_name`
+4. Receiver queries Twenty for existing Person by email
+5. If not found: creates Person record with `createPerson` mutation
+6. Creates a Note on the Person: "Stripe customer created — ID: [stripe-id]"
+7. Returns HTTP 200 to Stripe
+
+---
+
+## 6. DATA FLOW — INTERCOM WEBHOOK
+
+**Sequence:**
+
+1. Intercom fires `conversation.created` event
+2. Receiver validates signature
+3. Receiver extracts: `contact.email`, `conversation.id`, `conversation.subject`
+4. Receiver queries Twenty for Person by email
+5. If found: creates Note on Person with conversation summary
+6. Returns HTTP 200 to Intercom
+
+---
+
+## 7. ENVIRONMENT CHECKLIST
+
+| Environment | Status | Twenty workspace | API token |
+|---|---|---|---|
+| Development | [ready / pending] | [dev workspace ID] | [dev token] |
+| Staging | [ready / pending] | [staging workspace ID] | [staging token] |
+| Production | [ready / pending] | [prod workspace ID] | [prod token] |
+
+---
+
+## 8. ROLLBACK PLAN
+
+If a bad data push occurs:
+
+1. Stop the enrichment job or webhook receiver
+2. Note the exact timestamp of the bad push
+3. Query Twenty for all records created/updated after that timestamp:
+   ```graphql
+   query {
+     people(filter: { createdAt: { gte: "YYYY-MM-DDTHH:MM:SSZ" } }) {
+       edges { node { id createdAt } }
+     }
+   }
+   ```
+4. Use `deleteManyPeople` mutation to remove the affected records
+5. Fix the source data and re-run the pipeline
+
+**Contact for rollback approvals:** [CRM Admin name and email]
+
+---
+
+## 9. OPEN ITEMS FOR DEVELOPER
+
+| Item | Owner | Due date | Notes |
+|---|---|---|---|
+| [Webhook receiver for Stripe] | [developer] | YYYY-MM-DD | |
+| [Enrichment job script] | [developer] | YYYY-MM-DD | |
+| [Secrets stored in CI] | [devops] | YYYY-MM-DD | |

package/assets/worker-kits/growthub-twenty-crm-v1/templates/lead-enrichment-pipeline.md

@@ -0,0 +1,128 @@
+# Lead Enrichment Pipeline — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## 1. ENRICHMENT PROVIDER(S)
+
+| Provider | Auth mechanism | Data tier | Primary use |
+|---|---|---|---|
+| [Apollo] | Bearer token | Person + Company | Outbound lead source |
+| [Clearbit] | Bearer token | Company | Company enrichment |
+| [Clay] | API key | Person + Company | Enrichment waterfall |
+| [Hunter] | API key | Person | Email verification |
+
+---
+
+## 2. SOURCE FIELDS PROVIDED
+
+### [Provider name] — Person fields
+
+| Provider field | Data type | Example value |
+|---|---|---|
+| `first_name` | string | `Jane` |
+| `last_name` | string | `Doe` |
+| `email` | string | `jane@example.com` |
+| `title` | string | `Head of Growth` |
+| `linkedin_url` | string | `https://linkedin.com/in/janedoe` |
+| `organization.name` | string | `Acme Corp` |
+| `organization.website_url` | string | `acme.com` |
+
+### [Provider name] — Company fields
+
+| Provider field | Data type | Example value |
+|---|---|---|
+| `name` | string | `Acme Corp` |
+| `website_url` | string | `acme.com` |
+| `employee_count` | integer | `250` |
+| `industry` | string | `Software` |
+
+---
+
+## 3. DEDUPLICATION STRATEGY
+
+**Person dedup key:** `emails.primaryEmail`  
+**Company dedup key:** `domain`  
+**Secondary person key (when email unavailable):** `linkedInLink.url`
+
+**Dedup behavior:**
+- Match found → **merge** (update existing record with enriched fields)
+- No match found → **insert** (create new record)
+- If both email and LinkedIn are absent → **skip and log** the record for manual review
+
+---
+
+## 4. IMPORT MODE
+
+**Selected mode:** `[insert-only / merge / merge-with-insert-fallback]`
+
+**Rationale:** [Why this mode was chosen for this client's data state]
+
+---
+
+## 5. IMPORT METHOD
+
+**Method:** `[CSV import via Twenty UI / GraphQL mutation batch / REST API batch / webhook ingest]`
+
+**Import sequence:**
+1. Export [source] as CSV
+2. Clean CSV: remove duplicates, normalize email format (lowercase), strip leading/trailing spaces
+3. Run field mapping (see section 6)
+4. Upload via Twenty UI (Settings > Import) or batch via API
+5. Run post-import audit (section 7)
+
+**Batch size recommendation:** [N] records per batch (to avoid rate limits)
+
+---
+
+## 6. FIELD MAPPING
+
+See `EnrichmentFieldMap` artifact for full field-by-field alignment table.
+
+Summary of key mappings:
+
+| Source field | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|
+| `email` | → | `Person` | `emails.primaryEmail` | none |
+| `first_name` | → | `Person` | `name.firstName` | none |
+| `last_name` | → | `Person` | `name.lastName` | none |
+| `title` | → | `Person` | `position` | none |
+| `linkedin_url` | → | `Person` | `linkedInLink.url` | none |
+| `organization.name` | → | `Company` | `name` | none |
+| `organization.website_url` | → | `Company` | `domain` | strip protocol prefix |
+| `employee_count` | → | `Company` | `employees` | integer cast |
+
+---
+
+## 7. POST-IMPORT VALIDATION
+
+After import completes:
+
+- [ ] Record count matches expected import total (within ±2%)
+- [ ] Duplicate check: no duplicate email addresses in Person
+- [ ] Relation integrity: all Person records with a company are linked to a Company record
+- [ ] Sample review: spot-check 10 records for correct field mapping
+- [ ] Error log reviewed: all skipped records documented with reason
+
+---
+
+## 8. ERROR AND FAILURE HANDLING
+
+| Error type | Behavior | Resolution |
+|---|---|---|
+| Invalid email format | Skip record, log to error file | Manual review |
+| Duplicate email (on insert-only) | Skip record, log | Merge manually or switch to merge mode |
+| Missing required field | Skip record, log | Enrich from secondary provider |
+| API rate limit hit | Pause [N] seconds, retry | Reduce batch size |
+| Company not found | Create new Company record | Review after import |
+
+---
+
+## 9. UPDATE FREQUENCY
+
+**Enrichment cadence:** [one-time import / weekly / monthly / on-trigger]
+
+**Trigger for re-enrichment (if event-driven):** [e.g. "when Opportunity stage changes to QUALIFIED"]

package/assets/worker-kits/growthub-twenty-crm-v1/templates/pipeline-automation-brief.md

@@ -0,0 +1,88 @@
+# Pipeline Automation Brief — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## AUTOMATION INVENTORY
+
+| # | Automation name | Trigger | Action | Status |
+|---|---|---|---|---|
+| 1 | [Name] | [trigger type] | [action type] | [planned / active] |
+| 2 | [Name] | [trigger type] | [action type] | [planned / active] |
+
+---
+
+## AUTOMATION 1 — [NAME]
+
+**Purpose:** [What problem this automation solves]
+
+### Trigger
+
+| Property | Value |
+|---|---|
+| Trigger type | `[on_create / on_update / on_field_change / on_schedule / on_webhook]` |
+| Target object | `[Person / Company / Opportunity / Note / Task / <custom>]` |
+| Condition | `[field] [operator] [value]` (e.g. `stage == "QUALIFIED"`) |
+| Previous value (if field change) | `[previous value]` |
+| New value (if field change) | `[new value]` |
+
+### Action sequence
+
+| Step | Action type | Target | Parameters |
+|---|---|---|---|
+| 1 | `[update_field]` | `[Opportunity]` | `[field: assignee, value: <sales-rep-id>]` |
+| 2 | `[create_task]` | `[Person]` | `[title: "Follow up", dueAt: +2 days, assignee: <sales-rep-id>]` |
+| 3 | `[send_webhook]` | external | See webhook spec |
+
+### Failure behavior
+
+**If step 1 fails:** [retry / skip / halt]  
+**If step 2 fails:** [retry / skip / halt]  
+**If webhook fails:** retry 3× with exponential backoff (5s, 15s, 45s), then log and alert
+
+### Monitoring
+
+**How to verify this automation is running:** [e.g. "Check Task creation count in Twenty dashboard daily"]
+
+---
+
+## AUTOMATION 2 — [NAME]
+
+**Purpose:** [What problem this automation solves]
+
+### Trigger
+
+| Property | Value |
+|---|---|
+| Trigger type | `[trigger type]` |
+| Target object | `[object]` |
+| Condition | `[condition]` |
+
+### Action sequence
+
+| Step | Action type | Target | Parameters |
+|---|---|---|---|
+| 1 | `[action type]` | `[target]` | `[parameters]` |
+
+### Failure behavior
+
+**If any action fails:** [behavior]
+
+---
+
+## AUTOMATION DESIGN DECISIONS
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| [Decision 1] | [Choice] | [Rationale] |
+| [Decision 2] | [Choice] | [Rationale] |
+
+---
+
+## OPEN QUESTIONS
+
+- [ ] [Open question 1 — e.g. "Should the assignment automation use round-robin or territory-based routing?"]
+- [ ] [Open question 2]

package/assets/worker-kits/growthub-twenty-crm-v1/templates/webhook-integration-spec.md

@@ -0,0 +1,129 @@
+# Webhook Integration Spec — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## WEBHOOK INVENTORY
+
+| # | Name | Direction | Event | Status |
+|---|---|---|---|---|
+| 1 | [Name] | [inbound / outbound] | [event] | [planned / active] |
+| 2 | [Name] | [inbound / outbound] | [event] | [planned / active] |
+
+---
+
+## WEBHOOK 1 — [NAME]
+
+**Direction:** `[inbound / outbound]`  
+**Purpose:** [What this webhook enables — e.g. "When a Stripe customer is created, create a Company record in Twenty"]
+
+### Event Definition
+
+| Property | Value |
+|---|---|
+| Event source | `[Stripe / Intercom / Segment / Twenty / other]` |
+| Event name | `[e.g. customer.created / opportunity.created]` |
+| Trigger object | `[Twenty object or external object]` |
+| Trigger condition | `[e.g. "all events" / "stage = CLOSED_WON"]` |
+
+### Payload Schema
+
+**Source payload (what the sender sends):**
+
+```json
+{
+  "event": "[event-name]",
+  "created": 1713000000,
+  "data": {
+    "object": {
+      "id": "[source-id]",
+      "email": "[email]",
+      "name": "[name]",
+      "[field]": "[value]"
+    }
+  }
+}
+```
+
+**Target payload (what Twenty or the receiver expects):**
+
+```json
+{
+  "name": "[value]",
+  "emails": { "primaryEmail": "[email]" },
+  "[field]": "[value]"
+}
+```
+
+### Endpoint
+
+| Property | Value |
+|---|---|
+| URL | `[https://api.twenty.com/graphql or external endpoint]` |
+| Method | `[POST]` |
+| Auth header | `Authorization: Bearer <TWENTY_API_TOKEN>` |
+| Content-Type | `application/json` |
+
+### Field Mapping (inbound to Twenty)
+
+| Source field | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|
+| `data.object.email` | → | `Person` | `emails.primaryEmail` | none |
+| `data.object.name` | → | `Company` | `name` | none |
+
+### Retry Policy
+
+| Property | Value |
+|---|---|
+| Max retries | 3 |
+| Backoff | 5s, 15s, 45s |
+| On max retry failure | log to error queue and alert CRM admin |
+
+### Test Procedure
+
+1. Use [Stripe CLI / webhook testing tool] to send a test event
+2. Verify the payload arrives at the endpoint
+3. Verify the Twenty record is created or updated correctly
+4. Check for any field mapping errors in the response
+
+---
+
+## WEBHOOK 2 — [NAME]
+
+**Direction:** `[inbound / outbound]`  
+**Purpose:** [Purpose]
+
+### Event Definition
+
+| Property | Value |
+|---|---|
+| Event source | `[source]` |
+| Event name | `[event]` |
+
+### Payload Schema
+
+[See payload schema above pattern]
+
+### Endpoint
+
+| Property | Value |
+|---|---|
+| URL | `[URL]` |
+| Auth | `[auth mechanism]` |
+
+### Retry Policy
+
+| Property | Value |
+|---|---|
+| Max retries | 3 |
+| On failure | [behavior] |
+
+---
+
+## OPEN QUESTIONS
+
+- [ ] [Open question 1 — e.g. "Does Intercom's webhook payload include the contact email consistently?"]
+- [ ] [Open question 2]