@growthub/cli 0.3.54 → 0.3.56

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

@@ -0,0 +1,90 @@
+# Quick Start — Twenty CRM Worker Kit
+
+This folder is your self-contained agent working directory for Twenty CRM implementation, enrichment pipeline design, and CRM playbook production.
+
+---
+
+## Step 1 — Point your Working Directory at this folder
+
+**Growthub local (primary):** Open Growthub local and set the **Working Directory** to this folder in your project settings. Every run you start from this working directory will load the Twenty CRM operator agent automatically.
+
+**Claude Code (alternative):** Open Claude Code settings and set the **Working Directory** to this folder. The operator agent loads from `workers/twenty-crm-operator/CLAUDE.md` on session start.
+
+---
+
+## Step 2 — Configure your Twenty credentials
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in:
+- `TWENTY_API_TOKEN` — your Twenty app token (generate in Twenty Settings > API)
+- `TWENTY_API_URL` — your workspace API URL (e.g. `https://api.twenty.com` for cloud, or `http://localhost:3000` for local)
+
+The agent checks for these values at the start of every session (Step 0 of the workflow). It will not proceed without them in API-connected mode. Agent-only mode does not require credentials.
+
+---
+
+## Step 3 — Verify your environment
+
+```bash
+node setup/verify-env.mjs
+```
+
+Confirms that `TWENTY_API_TOKEN` is set, tests connectivity to the Twenty API, and prints available workspace info. Exits 0 on success.
+
+---
+
+## Step 4 — Check local dependencies
+
+```bash
+bash setup/check-deps.sh
+```
+
+Checks for `node`, `npm`, `git`, and `docker`. Docker is required for self-hosted mode. All are recommended for local-fork development.
+
+---
+
+## Step 5 — Boot the local fork (local-fork mode only)
+
+```bash
+bash setup/clone-fork.sh
+```
+
+Clones the Twenty repo to `~/twenty`, installs dependencies, and starts the development environment (PostgreSQL, Redis, and the Twenty server + frontend) via Docker Compose.
+
+Skip this step if you are using Twenty Cloud or have an existing self-hosted deployment.
+
+---
+
+## Step 6 — Start a new session
+
+**Growthub local:** Start a new run from this working directory. The agent loads automatically.
+
+**Claude Code:** Open a new session with this folder as the Working Directory. The agent reads `skills.md` and the methodology automatically.
+
+In both cases the agent will ask you 3 clarifying questions before generating any CRM artifacts.
+
+---
+
+## Execution modes
+
+| Mode | When to use |
+|---|---|
+| `local-fork` | Local Twenty checkout running via Docker at localhost:3000 |
+| `self-hosted` | Twenty deployed on your own infrastructure |
+| `cloud` | Twenty Cloud workspace at app.twenty.com |
+| `agent-only` | No live Twenty instance — produce planning artifacts only |
+
+---
+
+## First-run checklist
+
+See `validation-checklist.md` for the full pre-session checklist before your first CRM implementation run.
+
+---
+
+## Creating a brand kit for a new client
+
+See `brands/NEW-CLIENT.md`.

package/assets/worker-kits/growthub-twenty-crm-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,57 @@
+# New Client — Brand Kit Setup Guide
+
+Use this guide to create a brand kit for a new client before running the Twenty CRM operator.
+
+---
+
+## Step 1 — Create the brand kit folder
+
+```bash
+mkdir -p brands/<client-slug>
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+```
+
+Replace `<client-slug>` with the client's slug — lowercase, hyphenated (e.g. `acme-corp`, `growth-agency`).
+
+---
+
+## Step 2 — Fill in the brand kit
+
+Open `brands/<client-slug>/brand-kit.md` and fill in:
+
+1. **IDENTITY** — client name, slug, industry, company size, primary offer, campaign owner, date onboarded
+2. **CRM OBJECTIVE** — what problem they are solving with Twenty, deployment mode, go-live target
+3. **AUDIENCE AND PIPELINE** — primary persona, pipeline stages in order
+4. **TECH STACK** — current tools, enrichment providers, data sources
+5. **TEAM** — CRM admin, team sizes, admin capacity
+
+Leave `DELIVERABLES LOG` empty for now. The operator will append a line after each session.
+
+---
+
+## Step 3 — Tell the agent
+
+When you start a new session, point the agent to the brand kit:
+
+> "Load `brands/<client-slug>/brand-kit.md` as the active client context."
+
+The agent loads it in Step 1 of the workflow and uses it to name outputs, set the pipeline stage vocabulary, and calibrate proposal scope.
+
+---
+
+## Naming convention
+
+- `client_name`: Full name (e.g. `Acme Corporation`)
+- `slug`: lowercase, hyphenated, no spaces (e.g. `acme-corporation`)
+- Output files use PascalCase ClientSlug (e.g. `AcmeCorporation_DataModelDesign_v1_20260415.md`)
+
+---
+
+## Required fields (session will not proceed without these)
+
+- `client_name`
+- `slug`
+- `primary_crm_objective`
+- `deployment_mode`
+- `pipeline_stages` (at least 3 stages)
+- `data_sources` (at least one)

package/assets/worker-kits/growthub-twenty-crm-v1/brands/_template/brand-kit.md

@@ -0,0 +1,88 @@
+# Brand Kit — [CLIENT NAME]
+
+Copy to `brands/<client-slug>/brand-kit.md` and fill before producing outputs.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: "[CLIENT NAME]"
+slug: "[client-slug]"
+industry: "[industry]"
+company_size: "[e.g. 10-50 employees]"
+primary_offer: "[offer]"
+campaign_owner: "[owner]"
+date_onboarded: "YYYY-MM-DD"
+```
+
+## CRM OBJECTIVE
+
+```yaml
+primary_crm_objective: "[e.g. lead pipeline management / customer success tracking / partner CRM]"
+current_crm_tool: "[e.g. Salesforce / HubSpot / Airtable / none]"
+reason_for_switching: "[reason or first-time adoption]"
+deployment_mode: "[cloud / self-hosted / local-fork]"
+go_live_target: "YYYY-MM-DD"
+```
+
+## AUDIENCE AND PIPELINE
+
+```yaml
+primary_persona:
+  role: "[role]"
+  company_type: "[company type]"
+  pain_point: "[pain]"
+  desired_outcome: "[desired outcome]"
+  awareness_level: "[awareness]"
+
+pipeline_stages:
+  - "[Stage 1 — e.g. Lead]"
+  - "[Stage 2 — e.g. Qualified]"
+  - "[Stage 3 — e.g. Demo]"
+  - "[Stage 4 — e.g. Proposal]"
+  - "[Stage 5 — e.g. Closed Won]"
+  - "[Stage 6 — e.g. Closed Lost]"
+```
+
+## TECH STACK
+
+```yaml
+current_tools:
+  email_provider: "[e.g. Gmail / Outlook]"
+  enrichment_providers:
+    - "[Apollo / Clearbit / Clay / Hunter / none]"
+  product_analytics: "[Segment / Amplitude / Mixpanel / none]"
+  billing: "[Stripe / Chargebee / none]"
+  support: "[Intercom / Zendesk / none]"
+  marketing: "[HubSpot / Mailchimp / none]"
+  data_sources:
+    - "[CSV exports from ...]"
+    - "[API connection from ...]"
+```
+
+## TEAM
+
+```yaml
+team:
+  crm_admin: "[name or role]"
+  sales_team_size: "[number]"
+  cs_team_size: "[number]"
+  admin_capacity: "[hours/week available for CRM maintenance]"
+```
+
+## MESSAGING
+
+```yaml
+voice_and_tone:
+  - "[direct]"
+  - "[data-driven]"
+messaging_guardrails:
+  - "[no-go claim or data privacy rule]"
+```
+
+## DELIVERABLES LOG
+
+```text
+- YYYY-MM-DD | Twenty CRM Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```

package/assets/worker-kits/growthub-twenty-crm-v1/brands/growthub/brand-kit.md

@@ -0,0 +1,92 @@
+# Brand Kit — Growthub
+
+Public example brand kit for the Twenty CRM Worker Kit.
+
+---
+
+## IDENTITY
+
+```yaml
+client_name: "Growthub"
+slug: "growthub"
+industry: "B2B SaaS / Growth Platform"
+company_size: "10-50 employees"
+primary_offer: "AI-native local intelligence platform for growth teams"
+campaign_owner: "Growthub Growth Team"
+date_onboarded: "2026-04-15"
+```
+
+## CRM OBJECTIVE
+
+```yaml
+primary_crm_objective: "lead pipeline management and partner CRM"
+current_crm_tool: "none (first-time CRM adoption)"
+reason_for_switching: "first-time adoption — scaling GTM motion requires structured CRM"
+deployment_mode: "cloud"
+go_live_target: "2026-05-01"
+```
+
+## AUDIENCE AND PIPELINE
+
+```yaml
+primary_persona:
+  role: "Head of Growth / GTM Lead"
+  company_type: "B2B SaaS startup (Series A–B)"
+  pain_point: "scattered lead data across spreadsheets, no pipeline visibility, no enrichment"
+  desired_outcome: "structured pipeline with automated enrichment and clear stage ownership"
+  awareness_level: "high — already evaluating CRM options"
+
+pipeline_stages:
+  - "Lead — new contact captured"
+  - "Qualified — ICP-fit confirmed"
+  - "Demo — intro call scheduled or completed"
+  - "Proposal — commercial terms under discussion"
+  - "Closed Won — deal signed"
+  - "Closed Lost — deal lost with reason recorded"
+```
+
+## TECH STACK
+
+```yaml
+current_tools:
+  email_provider: "Gmail (Google Workspace)"
+  enrichment_providers:
+    - "Apollo (primary outbound lead source)"
+    - "Clay (enrichment waterfall)"
+  product_analytics: "Segment"
+  billing: "Stripe"
+  support: "Intercom"
+  marketing: "none (using direct outbound only)"
+  data_sources:
+    - "Apollo CSV exports (contacts + companies)"
+    - "Stripe webhook events (customer created, subscription updated)"
+    - "Intercom webhook events (conversation started, resolved)"
+```
+
+## TEAM
+
+```yaml
+team:
+  crm_admin: "Head of Growth"
+  sales_team_size: "3"
+  cs_team_size: "2"
+  admin_capacity: "4 hours/week available for CRM maintenance"
+```
+
+## MESSAGING
+
+```yaml
+voice_and_tone:
+  - "direct"
+  - "data-driven"
+  - "operator-first"
+messaging_guardrails:
+  - "do not overstate pipeline values in examples"
+  - "do not log client data in shared artifacts"
+```
+
+## DELIVERABLES LOG
+
+```text
+- 2026-04-15 | Twenty CRM Package v1 — Growthub GTM Stack | output/growthub/gtm-crm-v1/
+```

package/assets/worker-kits/growthub-twenty-crm-v1/bundles/growthub-twenty-crm-v1.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 2,
+  "bundle": {
+    "id": "growthub-twenty-crm-v1",
+    "version": "1.0.0",
+    "kitId": "growthub-twenty-crm-v1",
+    "workerId": "twenty-crm-operator"
+  },
+  "briefType": "twenty-crm-growth-stack",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "requiredFrozenAssets": [
+    "QUICKSTART.md",
+    ".env.example",
+    "skills.md",
+    "output-standards.md",
+    "runtime-assumptions.md",
+    "validation-checklist.md",
+    "workers/twenty-crm-operator/CLAUDE.md",
+    "brands/_template/brand-kit.md",
+    "brands/growthub/brand-kit.md",
+    "brands/NEW-CLIENT.md",
+    "setup/clone-fork.sh",
+    "setup/verify-env.mjs",
+    "setup/check-deps.sh",
+    "output/README.md",
+    "templates/crm-setup-brief.md",
+    "templates/data-model-design.md",
+    "templates/lead-enrichment-pipeline.md",
+    "templates/pipeline-automation-brief.md",
+    "templates/webhook-integration-spec.md",
+    "templates/api-query-plan.md",
+    "templates/crm-playbook.md",
+    "templates/custom-object-design.md",
+    "templates/import-mapping.md",
+    "templates/workspace-config-checklist.md",
+    "templates/integration-handoff.md",
+    "templates/enrichment-field-map.md",
+    "examples/crm-setup-sample.md",
+    "examples/lead-enrichment-sample.md",
+    "examples/pipeline-automation-sample.md",
+    "examples/crm-playbook-sample.md",
+    "docs/twenty-fork-integration.md",
+    "docs/api-and-webhooks.md",
+    "docs/data-model-layer.md",
+    "growthub-meta/README.md",
+    "growthub-meta/kit-standard.md"
+  ],
+  "optionalPresets": [],
+  "export": {
+    "folderName": "growthub-agent-worker-kit-twenty-crm-v1",
+    "zipFileName": "growthub-agent-worker-kit-twenty-crm-v1.zip"
+  },
+  "activationModes": ["export"]
+}

package/assets/worker-kits/growthub-twenty-crm-v1/docs/api-and-webhooks.md

@@ -0,0 +1,296 @@
+# API and Webhooks — Twenty CRM
+
+**Kit:** `growthub-twenty-crm-v1`
+
+---
+
+## OVERVIEW
+
+Twenty CRM exposes two API surfaces:
+
+1. **GraphQL API** at `<TWENTY_API_URL>/graphql` — the primary data access surface for queries and mutations
+2. **REST API** at `<TWENTY_API_URL>/api/objects/<object-name>` — simpler CRUD operations
+
+Both require a Bearer token authentication header.
+
+---
+
+## AUTHENTICATION
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+Tokens are workspace-scoped and generated in:
+**Settings > API > Tokens > Generate API Token**
+
+---
+
+## GRAPHQL API
+
+### Endpoint
+
+```
+POST <TWENTY_API_URL>/graphql
+```
+
+### Common query patterns
+
+#### List all People
+
+```graphql
+query {
+  people {
+    edges {
+      node {
+        id
+        name { firstName lastName }
+        emails { primaryEmail }
+        position
+        company { name domain }
+        createdAt
+      }
+    }
+    totalCount
+  }
+}
+```
+
+#### Filter People by email domain
+
+```graphql
+query {
+  people(filter: {
+    emails: { primaryEmail: { like: "%@acme.com" } }
+  }) {
+    edges {
+      node {
+        id
+        name { firstName lastName }
+        emails { primaryEmail }
+      }
+    }
+  }
+}
+```
+
+#### Get open Opportunities by stage
+
+```graphql
+query {
+  opportunities(filter: {
+    stage: { in: ["LEAD", "QUALIFIED", "DEMO", "PROPOSAL"] }
+  }, orderBy: { closeDate: AscNullsLast }) {
+    edges {
+      node {
+        id
+        name
+        stage
+        amount { amountMicros currencyCode }
+        closeDate
+        assignee { name { firstName lastName } }
+        pointOfContact { name { firstName lastName } emails { primaryEmail } }
+      }
+    }
+    totalCount
+  }
+}
+```
+
+#### Create a Person
+
+```graphql
+mutation {
+  createPerson(data: {
+    name: { firstName: "Jane", lastName: "Doe" }
+    emails: { primaryEmail: "jane@example.com" }
+    position: "Head of Growth"
+    linkedInLink: { url: "https://linkedin.com/in/janedoe", label: "LinkedIn" }
+    companyId: "<company-uuid>"
+  }) {
+    id
+    name { firstName lastName }
+    createdAt
+  }
+}
+```
+
+#### Update an Opportunity stage
+
+```graphql
+mutation {
+  updateOpportunity(
+    id: "<opportunity-uuid>"
+    data: { stage: "CLOSED_WON" }
+  ) {
+    id
+    stage
+    updatedAt
+  }
+}
+```
+
+#### Create a Note linked to a Person
+
+```graphql
+mutation {
+  createNote(data: {
+    body: "Spoke on 2026-04-15 — interested in Growthub platform for their outbound motion."
+    noteTargets: {
+      createMany: {
+        data: [{ personId: "<person-uuid>" }]
+        skipDuplicates: true
+      }
+    }
+  }) {
+    id
+    body
+    createdAt
+  }
+}
+```
+
+---
+
+## REST API
+
+### Endpoint
+
+```
+GET/POST/PATCH/DELETE <TWENTY_API_URL>/api/objects/<object-name>
+```
+
+Object name is the plural lowercase form (e.g. `people`, `companies`, `opportunities`).
+
+### Examples
+
+#### List companies
+
+```bash
+curl -X GET "<TWENTY_API_URL>/api/objects/companies" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN"
+```
+
+#### Create a company via REST
+
+```bash
+curl -X POST "<TWENTY_API_URL>/api/objects/companies" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Acme Corp", "domainName": {"primaryLinkUrl": "acme.com"}}'
+```
+
+#### Update an opportunity
+
+```bash
+curl -X PATCH "<TWENTY_API_URL>/api/objects/opportunities/<id>" \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"stage": "PROPOSAL"}'
+```
+
+---
+
+## WEBHOOKS
+
+### Outbound webhooks (Twenty → external)
+
+Twenty can fire outbound webhooks on object lifecycle events. Configure in:  
+**Settings > API > Webhooks > Add Webhook**
+
+Or create via the workflow engine using the `SEND_HTTP_REQUEST` action type.
+
+**Event naming convention:** `<object>.<event>` (e.g. `opportunity.created`, `person.updated`)
+
+**Outbound webhook payload schema:**
+
+```json
+{
+  "targetUrl": "https://your-endpoint.com/webhook",
+  "eventName": "opportunity.created",
+  "workspaceId": "<workspace-uuid>",
+  "webhookId": "<webhook-uuid>",
+  "eventDate": "2026-04-15T10:00:00.000Z",
+  "objectMetadata": {
+    "id": "<object-uuid>",
+    "nameSingular": "opportunity"
+  },
+  "record": {
+    "id": "<record-uuid>",
+    "name": "Acme Corp — Deal",
+    "stage": "LEAD",
+    "createdAt": "2026-04-15T10:00:00.000Z"
+  }
+}
+```
+
+**Note:** The exact `record` payload structure depends on the object and Twenty version. Inspect the actual webhook in the Twenty UI or via a test event before finalizing payload parsing.
+
+### Inbound webhooks (external → Twenty)
+
+Twenty does not natively receive inbound webhooks — you must build a webhook receiver that:
+1. validates the incoming event signature (from the source system)
+2. transforms the payload to the Twenty GraphQL mutation format
+3. calls the Twenty API to create or update the relevant record
+
+See `docs/twenty-fork-integration.md` for the workflow engine's inbound webhook trigger, which can be used to trigger automations from external systems.
+
+### Retry policy
+
+Twenty's outbound webhooks retry on failure with exponential backoff. The default retry count and backoff schedule depend on the Twenty version. Check the workflow logs in Settings > Workflows for retry status.
+
+---
+
+## METADATA API
+
+Used to create and manage custom objects and fields programmatically.
+
+### Endpoint
+
+```
+POST <TWENTY_API_URL>/metadata
+Authorization: Bearer <TWENTY_API_TOKEN>
+```
+
+### Introspect existing metadata
+
+```graphql
+query {
+  objects {
+    edges {
+      node {
+        id
+        nameSingular
+        labelSingular
+        isActive
+        fields {
+          edges {
+            node {
+              id
+              name
+              type
+              isNullable
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## ERROR HANDLING
+
+| HTTP Status | Meaning | Action |
+|---|---|---|
+| 200 | Success | Check `errors` array in GraphQL response body |
+| 401 | Unauthorized | Token is missing, expired, or wrong workspace |
+| 403 | Forbidden | Token valid but lacks access to the resource |
+| 404 | Not found | Object ID does not exist |
+| 429 | Rate limited | Back off and retry after the period indicated in headers |
+| 500 | Server error | Log and retry; contact workspace admin if persistent |
+
+**GraphQL errors** are returned with HTTP 200 but include an `errors` array. Always check `body.errors` after parsing the response.