@growthub/cli 0.3.53 → 0.3.55

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

@@ -0,0 +1,108 @@
+{
+  "schemaVersion": 2,
+  "kit": {
+    "id": "growthub-twenty-crm-v1",
+    "version": "1.0.0",
+    "name": "Growthub Agent Worker Kit — Twenty CRM",
+    "description": "Self-contained local execution environment for Twenty CRM — the open-source Salesforce/Apollo alternative. Produces CRM setup plans, data model designs, lead enrichment pipelines, pipeline automation briefs, webhook integration specs, API query plans, and client-ready CRM playbooks for teams adopting Twenty as their growth stack foundation.",
+    "type": "worker",
+    "visibility": "public-open-source",
+    "sourceRepo": "growthub-local",
+    "family": "studio"
+  },
+  "entrypoint": {
+    "workerId": "twenty-crm-operator",
+    "path": "workers/twenty-crm-operator/CLAUDE.md"
+  },
+  "workerIds": [
+    "twenty-crm-operator"
+  ],
+  "agentContractPath": "workers/twenty-crm-operator/CLAUDE.md",
+  "brandTemplatePath": "brands/_template/brand-kit.md",
+  "publicExampleBrandPaths": [
+    "brands/growthub/brand-kit.md"
+  ],
+  "frozenAssetPaths": [
+    "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"
+  ],
+  "setupPaths": {
+    "quickstart": "QUICKSTART.md",
+    "envExample": ".env.example",
+    "setupDir": "setup/",
+    "outputDir": "output/"
+  },
+  "outputStandard": {
+    "type": "working-directory",
+    "description": "Exported folder is intended to be pointed at directly by the agent Working Directory. All outputs are Markdown files written to output/<client-slug>/<project-slug>/.",
+    "requiredPaths": [
+      "QUICKSTART.md",
+      ".env.example",
+      "kit.json",
+      "bundles/growthub-twenty-crm-v1.json",
+      "skills.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",
+      "docs",
+      "growthub-meta"
+    ]
+  },
+  "bundles": [
+    {
+      "id": "growthub-twenty-crm-v1",
+      "version": "1.0.0",
+      "path": "bundles/growthub-twenty-crm-v1.json"
+    }
+  ],
+  "executionMode": "export",
+  "activationModes": [
+    "export"
+  ],
+  "compatibility": {
+    "cliMinVersion": "0.3.50"
+  },
+  "provenance": {
+    "sourceRepo": "growthub-local",
+    "frozenAt": "2026-04-15T00:00:00.000Z"
+  }
+}

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

@@ -0,0 +1,46 @@
+# Output Directory — Twenty CRM v1
+
+This directory is where the agent writes all client deliverables.
+
+---
+
+## Structure
+
+```text
+output/
+└── <client-slug>/
+    └── <project-slug>/
+        ├── <ClientSlug>_CRMSetupBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_DataModelDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_LeadEnrichmentPipeline_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_PipelineAutomationBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WebhookIntegrationSpec_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_APIQueryPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_CustomObjectDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ImportMapping_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WorkspaceConfigChecklist_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_IntegrationHandoff_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_EnrichmentFieldMap_v<N>_<YYYYMMDD>.md
+        └── <ClientSlug>_CRMPlaybook_v<N>_<YYYYMMDD>.md
+```
+
+---
+
+## File naming
+
+Pattern: `<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md`
+
+- `ClientSlug` is PascalCase (e.g. `AcmeCorp`, `Growthub`)
+- `OutputType` matches the artifact type exactly (e.g. `CRMSetupBrief`, `DataModelDesign`)
+- `v<N>` is the version number (start at `v1`, increment on revision)
+- `YYYYMMDD` is the date of production
+
+---
+
+## Rules
+
+- never overwrite an existing version file — create a new version
+- keep one artifact per file
+- Markdown only
+- no placeholder text in any delivered file
+- brand kit DELIVERABLES LOG must be updated after each delivery

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

@@ -0,0 +1,175 @@
+# Output Standards — Twenty CRM v1
+
+This document defines the output contract for every artifact produced by this kit.
+
+---
+
+## OUTPUT FOLDER STRUCTURE
+
+```text
+output/
+└── <client-slug>/
+    └── <project-slug>/
+        ├── <ClientSlug>_CRMSetupBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_DataModelDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_LeadEnrichmentPipeline_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_PipelineAutomationBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WebhookIntegrationSpec_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_APIQueryPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_CustomObjectDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ImportMapping_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WorkspaceConfigChecklist_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_IntegrationHandoff_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_EnrichmentFieldMap_v<N>_<YYYYMMDD>.md
+        └── <ClientSlug>_CRMPlaybook_v<N>_<YYYYMMDD>.md
+```
+
+---
+
+## REQUIRED OUTPUT TYPES
+
+Every full CRM implementation package must include:
+- CRM setup brief
+- data model design
+- lead enrichment pipeline
+- pipeline automation brief
+- webhook integration spec
+- API query plan
+- workspace config checklist
+- integration handoff
+- CRM playbook
+
+Custom object design and import mapping are included when the scope requires them.
+
+---
+
+## REQUIRED SECTIONS
+
+### CRM setup brief
+1. Client context and CRM objective
+2. Deployment mode (cloud / self-hosted / local-fork)
+3. Team size and user roles
+4. Data sources and volume estimates
+5. Integration scope
+6. Go-live timeline and milestones
+7. Success criteria
+
+### Data model design
+1. Standard objects in use and configuration notes
+2. Custom objects (if any) with full field definitions
+3. Relationship map (which objects link to which)
+4. Field type table per object
+5. Display configuration (labels, icons, default views)
+6. Open questions / decisions required
+
+### Lead enrichment pipeline
+1. Enrichment provider(s) and auth mechanism
+2. Source fields provided
+3. Target Twenty fields
+4. Deduplication strategy and match key
+5. Insert vs. merge behavior
+6. Update frequency
+7. Error and failure handling
+
+### Pipeline automation brief
+1. Pipeline name and purpose
+2. Trigger type and object
+3. Trigger conditions (field, value, timing)
+4. Action sequence
+5. Failure / timeout behavior
+6. Monitoring and alerting plan
+
+### Webhook integration spec
+1. Inbound vs. outbound classification
+2. Event name and trigger object
+3. Payload schema
+4. Target endpoint or source
+5. Auth mechanism
+6. Retry policy
+7. Test procedure
+
+### API query plan
+1. Query type (GraphQL / REST)
+2. Object(s) targeted
+3. Filter conditions
+4. Field selection
+5. Expected response structure
+6. Use case and consumer
+
+### Custom object design
+1. Object name and purpose
+2. Field table (name, type, required, options)
+3. Relationship definitions
+4. Creation method (UI vs. metadata API)
+5. Default view configuration
+6. Validation rules
+
+### Import mapping
+1. Source CRM / export format
+2. Column-by-column mapping table
+3. Transformation rules
+4. Deduplication key
+5. Import mode (insert / merge)
+6. Post-import validation steps
+
+### Workspace config checklist
+1. Settings to configure (auth, members, roles, branding)
+2. Integrations to enable
+3. Objects to activate or create
+4. Views and filters to configure
+5. Email and notification settings
+6. API token generation and distribution
+
+### Integration handoff
+1. System integration diagram
+2. Auth credentials required (types only — no values)
+3. Endpoint contracts
+4. Sequence diagram for data flow
+5. Environment checklist (dev / staging / prod)
+6. Rollback plan
+
+### Enrichment field map
+1. Provider name
+2. Provider field → Twenty field table with types and transformations
+3. Deduplication key
+4. Update frequency
+5. Notes and edge cases
+
+### CRM playbook
+1. Team roles and permissions
+2. Daily workflow (record creation, updates, activities)
+3. Pipeline management procedures
+4. Enrichment cadence
+5. Reporting and dashboard instructions
+6. Escalation and handoff protocols
+7. Maintenance and data hygiene checklist
+
+---
+
+## FILE NAMING RULES
+
+Pattern:
+
+```text
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+Rules:
+- `ClientSlug` is PascalCase
+- never overwrite an existing version
+- keep one artifact per file
+- Markdown only
+
+---
+
+## QUALITY BAR
+
+An output is complete when:
+- no placeholder text remains
+- all object and field names match Twenty's naming conventions
+- deduplication keys are named in every enrichment or import artifact
+- every automation trigger-action pair has a documented failure path
+- webhook specs include full payload schemas
+- GraphQL queries are syntactically correct
+- the CRM playbook is written at a level a non-technical team member can execute
+- integration handoff provides enough detail for a developer to implement without asking follow-up questions

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

@@ -0,0 +1,150 @@
+# Runtime Assumptions — Twenty CRM v1
+
+This document defines the runtime boundary for this kit.
+
+---
+
+## OVERVIEW
+
+This kit targets a self-contained local working directory used by an agent operating against one of four execution surfaces:
+
+| Mode | When to use | Assumption |
+|---|---|---|
+| `local-fork` | local checkout of Twenty via Docker Compose | repo files can be inspected before planning |
+| `self-hosted` | Twenty deployed on the team's own infrastructure | API is live and accessible via token |
+| `cloud` | Twenty Cloud workspace at app.twenty.com | API is live, no repo inspection required |
+| `agent-only` | no live Twenty instance | produce planning artifacts only, label as assumption-based |
+
+Default planning mode is `agent-only` when no deployment info is provided. Escalate to `local-fork` if a checkout path is confirmed.
+
+---
+
+## TWENTY CRM FROZEN ASSUMPTIONS
+
+Frozen upstream assumptions for this kit (based on Twenty v0.35+, MIT, TypeScript/React/NestJS):
+
+- Standard objects are: `Person`, `Company`, `Opportunity`, `Note`, `Task`, `Workspace Member`
+- Custom objects are supported via `Settings > Objects` (UI) and the metadata API
+- GraphQL is the primary query and mutation surface
+- REST API exists at `/api/objects/<object-name>` for CRUD operations
+- App tokens are generated in `Settings > API > Tokens` and must be sent as `Bearer` in the `Authorization` header
+- The workflow engine supports trigger types: `on_create`, `on_update`, `on_field_change`, `on_delete`, `on_schedule`, `on_webhook`
+- Outbound webhook actions are a supported workflow action type
+- The CLI (`@twenty-crm/cli`) exposes `twenty` commands for workspace management
+- Docker Compose is the canonical local development stack (PostgreSQL + Redis + server + frontend)
+- The default local development port for the Twenty server is `3000` and for the frontend is `3001`
+- The GraphQL endpoint is at `<TWENTY_API_URL>/graphql` (authenticated via Bearer token)
+- The metadata API is at `<TWENTY_API_URL>/metadata` (authenticated via Bearer token)
+
+If the local fork or live deployment differs, those actual values win.
+
+---
+
+## DEPLOYMENT MODE DETAILS
+
+### Local fork
+
+Expected operator flow:
+1. clone via `bash setup/clone-fork.sh`
+2. Docker Compose starts PostgreSQL, Redis, server, and frontend
+3. navigate to `http://localhost:3001` to configure workspace
+4. generate an API token in Settings
+5. set `TWENTY_API_TOKEN` and `TWENTY_API_URL=http://localhost:3000` in `.env`
+6. run `node setup/verify-env.mjs` to confirm connectivity
+7. proceed with data model inspection and implementation
+
+### Self-hosted
+
+Expected operator flow:
+1. confirm deployment URL and auth mechanism
+2. generate API token from the hosted workspace
+3. set `TWENTY_API_TOKEN` and `TWENTY_API_URL` to the deployed endpoint
+4. verify with `node setup/verify-env.mjs`
+5. proceed — no local fork inspection required
+
+### Cloud
+
+Expected operator flow:
+1. log in to Twenty Cloud at [app.twenty.com](https://app.twenty.com)
+2. go to Settings > API > Tokens and generate a token
+3. set `TWENTY_API_TOKEN` and `TWENTY_API_URL=https://api.twenty.com` in `.env`
+4. verify with `node setup/verify-env.mjs`
+5. proceed — no local fork inspection required
+
+### Agent-only
+
+- produce all planning artifacts using the frozen assumptions in this document
+- label every output with `mode: agent-only` at the top
+- note that implementation requires a live Twenty instance before any data or automation work can execute
+
+---
+
+## API AUTHENTICATION
+
+Twenty uses Bearer token authentication for all API access.
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+For the metadata API, the same token is used:
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+```
+
+Tokens are workspace-scoped. One token per workspace. Generate new tokens if the workspace membership changes.
+
+---
+
+## GRAPHQL ENDPOINT
+
+```
+POST <TWENTY_API_URL>/graphql
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+Example:
+
+```bash
+curl -X POST https://api.twenty.com/graphql \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ people { edges { node { id name { firstName lastName } } } } }"}'
+```
+
+---
+
+## METADATA API ENDPOINT
+
+The metadata API is used to create and manage custom objects and fields.
+
+```
+POST <TWENTY_API_URL>/metadata
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+---
+
+## DATA VOLUME ASSUMPTIONS
+
+- Small team (1–10 users): up to 10,000 Person records, 2,000 Company records
+- Mid-market (10–100 users): up to 100,000 Person records, 20,000 Company records
+- Enterprise (100+ users): requires infrastructure review before recommending Twenty without dedicated devops
+
+For enrichment pipelines above 50,000 records, recommend batched imports over direct CSV upload.
+
+---
+
+## OUTPUT WRITING ASSUMPTION
+
+All deliverables are written as Markdown in:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+The kit does not require its own npm install or custom CLI to be operational. API connectivity requires only `node` for `setup/verify-env.mjs`.

package/assets/worker-kits/growthub-twenty-crm-v1/setup/check-deps.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify local dependencies required for Twenty CRM local-fork and self-hosted workflows.
+# Run before your first local-fork session.
+set -e
+
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  local install_hint="$3"
+  if command -v "$cmd" >/dev/null 2>&1; then
+    echo "OK   $name ($(command -v "$cmd"))"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  $name — $install_hint"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+check_docker_running() {
+  if docker info >/dev/null 2>&1; then
+    echo "OK   Docker daemon (running)"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  Docker daemon — start Docker Desktop or the Docker service"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== Growthub Twenty CRM — Dependency Check ==="
+echo ""
+check "git"    "git"    "https://git-scm.com/downloads"
+check "node"   "node"   "https://nodejs.org (v18+ required)"
+check "npm"    "npm"    "Comes with Node.js"
+check "docker" "docker" "https://docs.docker.com/get-docker/"
+echo ""
+
+if command -v docker >/dev/null 2>&1; then
+  check_docker_running
+fi
+
+echo ""
+echo "Passed: $PASS  |  Missing: $FAIL"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Install missing tools before running local-fork workflows."
+  echo "Agent-only mode does not require Docker or a local fork."
+  exit 1
+fi
+
+echo ""
+echo "All dependencies present."
+echo "You are ready for local-fork execution. Run: bash setup/clone-fork.sh"

package/assets/worker-kits/growthub-twenty-crm-v1/setup/clone-fork.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# clone-fork.sh — Clone the Twenty CRM repo and boot the local development environment
+# Usage: bash setup/clone-fork.sh
+# Requires: git, node, npm, docker, docker-compose
+set -e
+
+FORK_DIR="${TWENTY_FORK_PATH:-$HOME/twenty}"
+REPO_URL="https://github.com/twentyhq/twenty"
+
+echo "=== Growthub Twenty CRM Studio — Fork Setup ==="
+echo ""
+
+# Dependency checks
+for cmd in git node npm docker; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "ERROR: $cmd is required but not found."
+    echo "Install it before running this script."
+    exit 1
+  fi
+done
+
+if ! docker info >/dev/null 2>&1; then
+  echo "ERROR: Docker daemon is not running."
+  echo "Start Docker Desktop or the Docker service before running this script."
+  exit 1
+fi
+
+if [ -d "$FORK_DIR" ]; then
+  echo "Fork already exists at $FORK_DIR — skipping clone."
+  echo "To re-clone, remove the directory first: rm -rf $FORK_DIR"
+else
+  echo "Cloning Twenty CRM → $FORK_DIR"
+  git clone "$REPO_URL" "$FORK_DIR"
+  echo "Clone complete."
+fi
+
+cd "$FORK_DIR"
+
+echo ""
+echo "Copying environment config..."
+if [ ! -f ".env" ]; then
+  if [ -f ".env.example" ]; then
+    cp .env.example .env
+    echo "Copied .env.example → .env"
+    echo "Review .env and set any required values before starting."
+  else
+    echo "WARNING: .env.example not found — you may need to configure .env manually."
+  fi
+else
+  echo ".env already exists — skipping copy."
+fi
+
+echo ""
+echo "Starting Twenty via Docker Compose..."
+echo "This pulls images for PostgreSQL, Redis, the Twenty server, and frontend."
+echo "First run may take several minutes."
+echo ""
+
+if command -v docker-compose >/dev/null 2>&1; then
+  docker-compose up -d
+else
+  docker compose up -d
+fi
+
+echo ""
+echo "=== Twenty CRM is starting ==="
+echo ""
+echo "Frontend will be available at: http://localhost:3001"
+echo "Server API will be available at: http://localhost:3000"
+echo ""
+echo "Next steps:"
+echo "  1. Open http://localhost:3001 and create your workspace."
+echo "  2. Go to Settings > API > Tokens and generate an API token."
+echo "  3. Set TWENTY_API_TOKEN and TWENTY_API_URL=http://localhost:3000 in your kit .env file."
+echo "  4. Run: node setup/verify-env.mjs"
+echo ""
+echo "To stop Twenty: docker-compose down (or docker compose down)"