@growthub/cli 0.3.53 → 0.3.55

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

@@ -0,0 +1,155 @@
+# CRM Playbook — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Version:** v1
+
+---
+
+## ABOUT THIS PLAYBOOK
+
+This playbook is the operating manual for the [CLIENT NAME] Twenty CRM workspace. It defines roles, daily workflows, pipeline procedures, enrichment cadences, and data hygiene rules. Every team member with CRM access should read and follow this document.
+
+---
+
+## 1. TEAM ROLES AND PERMISSIONS
+
+| Role | Name | Access level | Responsibilities |
+|---|---|---|---|
+| CRM Admin | [name] | Full access | Object configuration, user management, integration maintenance |
+| Sales Rep | [name] | Create/edit own records | Lead creation, pipeline updates, note-taking |
+| CS Manager | [name] | Read + edit post-close | Customer success tracking, renewal management |
+
+**Onboarding new members:** CRM Admin creates workspace member in Settings > Members and assigns the correct role.
+
+---
+
+## 2. DAILY WORKFLOW
+
+### Sales rep daily workflow
+
+1. Log in to Twenty and open the Opportunity pipeline view
+2. Review any new leads assigned to you (filter: `assignee = me`, `stage = LEAD`)
+3. Update stage for any leads that progressed since yesterday
+4. Add a Note for every contact or company you spoke with
+5. Check open Tasks due today and complete or reschedule them
+6. Before end of day: all new contacts from today's calls must be in Twenty
+
+### CRM admin daily workflow
+
+1. Check the import error log (if enrichment pipeline is running)
+2. Review any automation failures in the workflow logs
+3. Confirm new workspace members have correct permissions
+4. Spot-check 3–5 records for data quality (no blank required fields)
+
+---
+
+## 3. PIPELINE MANAGEMENT PROCEDURES
+
+### Creating a new Opportunity
+
+1. Navigate to Opportunities
+2. Click `+ New`
+3. Fill in: name, stage, linked Person (pointOfContact), linked Company, amount, close date
+4. Set the assignee to the responsible sales rep
+5. Add a first Note with context
+
+### Moving a stage
+
+1. Open the Opportunity record
+2. Click the stage selector and choose the new stage
+3. Add a Note explaining the stage change (what happened, next step)
+4. If moving to `CLOSED_WON`: confirm amount and close date are accurate
+5. If moving to `CLOSED_LOST`: add a Note with the loss reason
+
+### Pipeline review (weekly — team)
+
+Run the pipeline report query (see API Query Plan) or filter in Twenty:
+- All Opportunities: stage in [QUALIFIED, DEMO, PROPOSAL]
+- Sort by close date ascending
+- Review top 10 by close date
+
+---
+
+## 4. ENRICHMENT CADENCE
+
+**Enrichment schedule:** [one-time / weekly on [day] / monthly on [day] / event-triggered]
+
+**Enrichment procedure (if CSV-based):**
+
+1. Export contacts from [Apollo / Clay / source] with the filters defined in the Lead Enrichment Pipeline doc
+2. Open the CSV and remove any test or duplicate entries
+3. Import via Twenty: navigate to [Person / Company] > Import
+4. Select the field mapping profile saved as `[mapping-profile-name]`
+5. Run the import
+6. After import: check the error log and resolve skipped records
+
+**Enrichment procedure (if API/webhook-based):**
+
+The enrichment pipeline runs automatically via [webhook / scheduled API call]. Review the error log weekly and resolve any skipped records.
+
+---
+
+## 5. REPORTING AND DASHBOARD INSTRUCTIONS
+
+### Pipeline health view
+
+**Filter:** Opportunities where stage is in [LEAD, QUALIFIED, DEMO, PROPOSAL]  
+**Group by:** Stage  
+**Sort by:** Close date ascending
+
+**Reading the view:**
+- Count of opportunities in each stage = pipeline coverage
+- Total amount in DEMO + PROPOSAL = near-term revenue signal
+- Opportunities with no stage update in 14+ days = stale — review and update or close
+
+### Contact view
+
+**Filter:** Persons created in the last 30 days  
+**Sort:** Created at descending
+
+Use this view weekly to confirm all new contacts are properly linked to Companies and have no missing required fields.
+
+---
+
+## 6. ESCALATION AND HANDOFF PROTOCOLS
+
+### CRM data dispute
+
+If a record looks incorrect (wrong company, wrong stage, stale data):
+1. Do not delete — add a Note documenting the issue
+2. Tag `@[CRM Admin]` in the note
+3. CRM Admin resolves within 2 business days
+
+### Integration failure
+
+If the enrichment pipeline or a webhook stops working:
+1. CRM Admin checks the workflow logs in Twenty > Settings > Workflows
+2. If logs are inconclusive, check the error log from the enrichment provider
+3. Escalate to [developer contact] with the error message and timestamp
+
+### Offboarding a team member
+
+1. CRM Admin reassigns all open Opportunities from the departing member
+2. Reassign all open Tasks
+3. Deactivate the workspace member in Settings > Members
+
+---
+
+## 7. MAINTENANCE AND DATA HYGIENE CHECKLIST
+
+**Weekly:**
+- [ ] Review import error log — resolve skipped records
+- [ ] Check open Opportunities for stale records (no update in 14 days)
+- [ ] Confirm all Closed Won / Closed Lost opportunities have a close reason Note
+
+**Monthly:**
+- [ ] Audit duplicate Person records (same email) — merge or remove
+- [ ] Audit Companies with no linked Persons — flag for review
+- [ ] Review workflow automation logs for failures
+- [ ] Update the CRM Playbook if any procedures have changed
+
+**Quarterly:**
+- [ ] Review custom object field usage — deprecate unused fields
+- [ ] Review pipeline stage definitions — adjust if the sales process has changed
+- [ ] Evaluate enrichment provider quality and coverage

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

@@ -0,0 +1,94 @@
+# CRM Setup Brief — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Operator:** `twenty-crm-operator`  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## 1. CLIENT CONTEXT AND CRM OBJECTIVE
+
+**Client:** [CLIENT NAME]  
+**Industry:** [industry]  
+**Company size:** [N employees]  
+**CRM objective:** [primary objective — e.g. "Build a structured outbound sales pipeline with automated lead enrichment from Apollo"]
+
+**Why Twenty:**
+- [reason 1]
+- [reason 2]
+
+---
+
+## 2. DEPLOYMENT MODE
+
+**Selected mode:** `[cloud / self-hosted / local-fork]`  
+**API URL:** [URL or TBD]  
+**Environment:** [production / staging / development]
+
+**Prerequisites confirmed:**
+- [ ] Twenty workspace created
+- [ ] API token generated
+- [ ] `node setup/verify-env.mjs` passes
+
+---
+
+## 3. TEAM SIZE AND USER ROLES
+
+| Role | User | Permissions |
+|---|---|---|
+| CRM Admin | [name] | Full access |
+| Sales Rep | [name] | Create/edit Opportunities and Persons |
+| CS Manager | [name] | Read/edit Opportunities post-close |
+
+**Total workspace members:** [N]
+
+---
+
+## 4. DATA SOURCES AND VOLUME ESTIMATES
+
+| Source | Object type | Estimated volume | Import method |
+|---|---|---|---|
+| [Apollo CSV export] | Person + Company | [N contacts] | CSV import |
+| [Stripe webhooks] | [custom object or Note] | [events/month] | Webhook |
+| [Intercom] | Note | [conversations/month] | Webhook |
+
+---
+
+## 5. INTEGRATION SCOPE
+
+| Integration | Direction | Priority |
+|---|---|---|
+| [Apollo] | Inbound enrichment | High |
+| [Stripe] | Inbound webhook | High |
+| [Intercom] | Inbound webhook | Medium |
+| [Slack] | Outbound notification | Low |
+
+---
+
+## 6. GO-LIVE TIMELINE AND MILESTONES
+
+| Milestone | Target date | Owner |
+|---|---|---|
+| Data model finalized | YYYY-MM-DD | [CRM admin] |
+| Initial import complete | YYYY-MM-DD | [CRM admin] |
+| Enrichment pipeline live | YYYY-MM-DD | [developer] |
+| Automations active | YYYY-MM-DD | [developer] |
+| Team onboarded | YYYY-MM-DD | [CRM admin] |
+
+---
+
+## 7. SUCCESS CRITERIA
+
+- [ ] All [N] contacts imported and deduplicated against domain
+- [ ] Pipeline visible with [N] stages
+- [ ] At least [N] automations active (stage transitions, follow-up tasks)
+- [ ] Enrichment pipeline running on [cadence] cadence
+- [ ] All team members onboarded and using the CRM daily
+
+---
+
+## OPEN QUESTIONS
+
+- [ ] [Open question 1]
+- [ ] [Open question 2]

package/assets/worker-kits/growthub-twenty-crm-v1/templates/custom-object-design.md

@@ -0,0 +1,115 @@
+# Custom Object Design — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## CUSTOM OBJECT: [OBJECT NAME]
+
+**Purpose:** [What problem this custom object solves — e.g. "Track partner accounts separate from customer companies"]  
+**Creation method:** `[Settings > Objects (UI) / metadata API]`  
+**Scope:** `[per-workspace / this client only]`
+
+---
+
+## FIELD TABLE
+
+| Field name (camelCase) | Display label | Type | Required | Options / Notes |
+|---|---|---|---|---|
+| `[fieldName]` | [Label] | `TEXT` | [Yes / No] | |
+| `[fieldName]` | [Label] | `NUMBER` | [Yes / No] | |
+| `[fieldName]` | [Label] | `SELECT` | [Yes / No] | Options: [A, B, C] |
+| `[fieldName]` | [Label] | `RELATION` | [Yes / No] | Links to `[Object]` |
+| `[fieldName]` | [Label] | `DATE` | [Yes / No] | |
+| `[fieldName]` | [Label] | `BOOLEAN` | [Yes / No] | |
+| `[fieldName]` | [Label] | `LINK` | [Yes / No] | |
+| `[fieldName]` | [Label] | `EMAILS` | [Yes / No] | |
+| `[fieldName]` | [Label] | `CURRENCY` | [Yes / No] | Store in micros |
+
+**Select field options (if any):**
+
+| Field | Option value (SCREAMING_SNAKE_CASE) | Display label |
+|---|---|---|
+| `[fieldName]` | `[OPTION_A]` | [Label A] |
+| `[fieldName]` | `[OPTION_B]` | [Label B] |
+
+---
+
+## RELATIONSHIP DEFINITIONS
+
+| Relation field | Direction | Target object | Cardinality | Notes |
+|---|---|---|---|---|
+| `[relationField]` | outgoing | `[TargetObject]` | many-to-one | [notes] |
+| `[relationField]` | incoming | `[TargetObject]` | one-to-many | [notes] |
+
+**Relationship map:**
+
+```text
+[CustomObject] ──── [relationField] ────> [TargetObject]
+[AnotherObject] <─── [inverseField] ─── [CustomObject]
+```
+
+---
+
+## DISPLAY CONFIGURATION
+
+| Property | Value |
+|---|---|
+| Label (singular) | [e.g. Partner Account] |
+| Label (plural) | [e.g. Partner Accounts] |
+| Icon | [Twenty icon name — e.g. `building`, `user`, `star`] |
+| Default view | `[list / kanban]` |
+| Kanban grouping field (if kanban) | `[fieldName]` |
+
+---
+
+## CREATION PROCEDURE
+
+### Via UI (Settings > Objects)
+
+1. Go to Settings > Objects
+2. Click `+ New custom object`
+3. Set label (singular and plural), icon
+4. Add each field from the field table above
+5. Configure select options for any SELECT fields
+6. Add relation fields and select the target object
+7. Save and activate the object
+
+### Via Metadata API
+
+```graphql
+mutation CreateCustomObject {
+  createOneObject(input: {
+    labelSingular: "[Label Singular]"
+    labelPlural: "[Label Plural]"
+    nameSingular: "[objectName]"
+    namePlural: "[objectNames]"
+    icon: "[icon-name]"
+    description: "[description]"
+  }) {
+    id
+    nameSingular
+    labelSingular
+  }
+}
+```
+
+Then add fields with `createOneField` mutations per field.
+
+---
+
+## VALIDATION RULES
+
+| Rule | Field | Condition | Behavior |
+|---|---|---|---|
+| [Rule 1] | `[field]` | [condition] | [show error / block save] |
+| [Rule 2] | `[field]` | [condition] | [behavior] |
+
+---
+
+## OPEN QUESTIONS
+
+- [ ] [Decision needed — e.g. "Should this object be visible to all team members or only admins?"]
+- [ ] [Question 2]

package/assets/worker-kits/growthub-twenty-crm-v1/templates/data-model-design.md

@@ -0,0 +1,112 @@
+# Data Model Design — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## 1. STANDARD OBJECTS IN USE
+
+| Object | In use? | Configuration notes |
+|---|---|---|
+| `Person` | [Yes / No] | [e.g. "primary contact object — email as dedup key"] |
+| `Company` | [Yes / No] | [e.g. "linked to Person via relation"] |
+| `Opportunity` | [Yes / No] | [e.g. "6-stage pipeline: Lead → Closed Won"] |
+| `Note` | [Yes / No] | [e.g. "used for Intercom conversation summaries"] |
+| `Task` | [Yes / No] | [e.g. "auto-created by stage-change automation"] |
+| `Workspace Member` | Yes | [roles: admin, sales, cs] |
+
+---
+
+## 2. CUSTOM OBJECTS
+
+### [Custom Object Name 1]
+
+**Purpose:** [description]  
+**Creation method:** [UI (Settings > Objects) / metadata API]
+
+| Field name | Type | Required | Options / Notes |
+|---|---|---|---|
+| `[fieldName]` | `[TEXT / NUMBER / SELECT / RELATION / ...]` | [Yes / No] | [options or notes] |
+| `[fieldName]` | `[TYPE]` | [Yes / No] | |
+
+**Relationships:**
+- Links to `[Object]` via `[fieldName]` (one-to-one / one-to-many / many-to-many)
+
+**Display configuration:**
+- Label (singular): [label]
+- Label (plural): [label plural]
+- Icon: [Twenty icon name]
+- Default view: [list / kanban]
+
+---
+
+## 3. PERSON OBJECT — FIELD CONFIGURATION
+
+| Field name | Type | Required | Notes |
+|---|---|---|---|
+| `name.firstName` | `TEXT` | Yes | |
+| `name.lastName` | `TEXT` | Yes | |
+| `emails.primaryEmail` | `EMAILS` | Yes | Dedup key |
+| `phones.primaryPhoneNumber` | `PHONES` | No | |
+| `company` | `RELATION` | No | Links to Company |
+| `position` | `TEXT` | No | Job title |
+| `linkedInLink.url` | `LINK` | No | |
+| `city` | `TEXT` | No | |
+| `[customField]` | `[TYPE]` | [Yes/No] | [source: enrichment provider] |
+
+---
+
+## 4. COMPANY OBJECT — FIELD CONFIGURATION
+
+| Field name | Type | Required | Notes |
+|---|---|---|---|
+| `name` | `TEXT` | Yes | |
+| `domain` | `TEXT` | No | Dedup key |
+| `employees` | `NUMBER` | No | |
+| `annualRecurringRevenue.amountMicros` | `CURRENCY` | No | |
+| `address` | `ADDRESS` | No | |
+| `linkedInLink.url` | `LINK` | No | |
+| `[customField]` | `[TYPE]` | [Yes/No] | |
+
+---
+
+## 5. OPPORTUNITY OBJECT — FIELD CONFIGURATION
+
+| Field name | Type | Required | Notes |
+|---|---|---|---|
+| `name` | `TEXT` | Yes | |
+| `stage` | `SELECT` | Yes | See stage options below |
+| `amount.amountMicros` | `CURRENCY` | No | Store in micros (×1,000,000) |
+| `closeDate` | `DATE` | No | ISO 8601 |
+| `pointOfContact` | `RELATION` | No | Links to Person |
+| `[customField]` | `[TYPE]` | [Yes/No] | |
+
+**Stage options (SELECT values):**
+
+| Value | Label | Order |
+|---|---|---|
+| `LEAD` | Lead | 1 |
+| `QUALIFIED` | Qualified | 2 |
+| `DEMO` | Demo | 3 |
+| `PROPOSAL` | Proposal | 4 |
+| `CLOSED_WON` | Closed Won | 5 |
+| `CLOSED_LOST` | Closed Lost | 6 |
+
+---
+
+## 6. RELATIONSHIP MAP
+
+```text
+Person ──── company ────> Company
+Person <─── pointOfContact ─── Opportunity
+Company <─── [relation] ─── [CustomObject]
+```
+
+---
+
+## 7. OPEN QUESTIONS / DECISIONS REQUIRED
+
+- [ ] [Decision 1 — e.g. "Should LeadSource be a custom field on Person or a separate custom object?"]
+- [ ] [Decision 2]

package/assets/worker-kits/growthub-twenty-crm-v1/templates/enrichment-field-map.md

@@ -0,0 +1,100 @@
+# Enrichment Field Map — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Provider:** [Apollo / Clearbit / Clay / Hunter / other]
+
+---
+
+## PERSON FIELD MAP
+
+**Dedup key:** `emails.primaryEmail`  
+**Update frequency:** [weekly / monthly / on-trigger]
+
+| Provider field | Provider type | → | Twenty object | Twenty field | Twenty type | Transformation | Required |
+|---|---|---|---|---|---|---|---|
+| `first_name` | string | → | `Person` | `name.firstName` | `TEXT` | none | Yes |
+| `last_name` | string | → | `Person` | `name.lastName` | `TEXT` | none | Yes |
+| `email` | string | → | `Person` | `emails.primaryEmail` | `EMAILS` | lowercase, trim | Yes (dedup key) |
+| `phone_numbers[0].raw_number` | string | → | `Person` | `phones.primaryPhoneNumber` | `PHONES` | none | No |
+| `title` | string | → | `Person` | `position` | `TEXT` | none | No |
+| `linkedin_url` | string | → | `Person` | `linkedInLink.url` | `LINK` | none | No |
+| `city` | string | → | `Person` | `city` | `TEXT` | none | No |
+| `seniority` | string | → | `Person` | `[custom field: seniority]` | `SELECT` | map to SELECT options | No |
+| `departments` | array | → | `Person` | `[custom field: department]` | `TEXT` | join with comma | No |
+| `[provider field]` | [type] | → | `Person` | `[field]` | `[type]` | [transform] | [Yes/No] |
+
+---
+
+## COMPANY FIELD MAP
+
+**Dedup key:** `domain`  
+**Update frequency:** [same as person / separate cadence]`
+
+| Provider field | Provider type | → | Twenty object | Twenty field | Twenty type | Transformation | Required |
+|---|---|---|---|---|---|---|---|
+| `organization.name` | string | → | `Company` | `name` | `TEXT` | none | Yes |
+| `organization.website_url` | string | → | `Company` | `domain` | `TEXT` | strip protocol, strip trailing slash | Yes (dedup key) |
+| `organization.estimated_num_employees` | integer | → | `Company` | `employees` | `NUMBER` | integer cast | No |
+| `organization.annual_revenue` | number | → | `Company` | `annualRecurringRevenue.amountMicros` | `CURRENCY` | multiply by 1,000,000 | No |
+| `organization.industry` | string | → | `Company` | `[custom field: industry]` | `SELECT` | map to SELECT options | No |
+| `organization.linkedin_url` | string | → | `Company` | `linkedInLink.url` | `LINK` | none | No |
+| `[provider field]` | [type] | → | `Company` | `[field]` | `[type]` | [transform] | [Yes/No] |
+
+---
+
+## SELECT OPTION MAPPINGS
+
+### seniority → Person.seniority
+
+| Provider value | → | Twenty SELECT value |
+|---|---|---|
+| `founder` | → | `FOUNDER` |
+| `c_suite` | → | `C_SUITE` |
+| `vp` | → | `VP` |
+| `director` | → | `DIRECTOR` |
+| `manager` | → | `MANAGER` |
+| `individual_contributor` | → | `INDIVIDUAL_CONTRIBUTOR` |
+| `[value]` | → | `[TWENTY_VALUE]` |
+
+### industry → Company.industry
+
+| Provider value | → | Twenty SELECT value |
+|---|---|---|
+| `software` | → | `SOFTWARE` |
+| `saas` | → | `SOFTWARE` |
+| `fintech` | → | `FINTECH` |
+| `healthtech` | → | `HEALTHTECH` |
+| `ecommerce` | → | `ECOMMERCE` |
+| `[value]` | → | `[TWENTY_VALUE]` |
+
+---
+
+## FIELDS EXCLUDED FROM ENRICHMENT
+
+| Provider field | Reason for exclusion |
+|---|---|
+| `id` | Internal provider ID — not stored in Twenty |
+| `photo_url` | Not mapped — no avatar field in standard Twenty |
+| `[field]` | [reason] |
+
+---
+
+## EDGE CASES AND NOTES
+
+| Case | Handling |
+|---|---|
+| Email is null | Skip record — log to error file |
+| Domain is null on company | Attempt to extract from email domain — if still null, skip |
+| Multiple emails returned | Use `email` field as primary; log additional emails |
+| Revenue value is 0 | Do not import — leave `annualRecurringRevenue` blank |
+| [Case] | [handling] |
+
+---
+
+## ENRICHMENT MATCH KEY SUMMARY
+
+| Object | Primary key | Secondary key | Fallback |
+|---|---|---|---|
+| `Person` | `emails.primaryEmail` | `linkedInLink.url` | Skip and log |
+| `Company` | `domain` | `name` (exact match) | Create new |