@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-twenty-crm-v1/templates/workspace-config-checklist.md

@@ -0,0 +1,129 @@
+# Workspace Config Checklist — [CLIENT NAME]
+
+**Date:** YYYY-MM-DD  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `[cloud / self-hosted / local-fork / agent-only]`
+
+---
+
+## PRE-LAUNCH CONFIGURATION CHECKLIST
+
+Complete these tasks before the team starts using the CRM in production.
+
+---
+
+## 1. WORKSPACE SETTINGS
+
+- [ ] Workspace display name set (Settings > General)
+- [ ] Workspace logo uploaded
+- [ ] Default currency set
+- [ ] Timezone confirmed
+- [ ] Domain / subdomain configured (for self-hosted)
+
+---
+
+## 2. TEAM MEMBERS AND ROLES
+
+| Member | Email | Role | Status |
+|---|---|---|---|
+| [CRM Admin] | [email] | Admin | [invited / active] |
+| [Sales Rep 1] | [email] | Member | [invited / active] |
+| [Sales Rep 2] | [email] | Member | [invited / active] |
+| [CS Manager] | [email] | Member | [invited / active] |
+
+- [ ] All invites sent (Settings > Members)
+- [ ] All members have accepted and set passwords
+- [ ] Roles confirmed for each member
+- [ ] No test accounts remaining in member list
+
+---
+
+## 3. STANDARD OBJECTS CONFIGURED
+
+| Object | Enabled | Custom fields added | Default view set |
+|---|---|---|---|
+| `Person` | [Yes] | [list custom fields] | [Yes / No] |
+| `Company` | [Yes] | [list custom fields] | [Yes / No] |
+| `Opportunity` | [Yes] | Stage options confirmed | [Yes / No] |
+| `Note` | [Yes] | n/a | n/a |
+| `Task` | [Yes] | n/a | n/a |
+
+---
+
+## 4. CUSTOM OBJECTS CONFIGURED
+
+| Object | Created | Fields added | Relationships set | Default view set |
+|---|---|---|---|---|
+| [CustomObject1] | [Yes / No] | [Yes / No] | [Yes / No] | [Yes / No] |
+
+---
+
+## 5. VIEWS AND FILTERS
+
+| View | Object | Filter | Sort | Assigned to |
+|---|---|---|---|---|
+| My Open Leads | Opportunity | stage IN [LEAD, QUALIFIED], assignee = me | createdAt desc | All sales reps |
+| Pipeline Board | Opportunity | stage NOT IN [CLOSED_WON, CLOSED_LOST] | closeDate asc | All team |
+| New Contacts (30d) | Person | createdAt > 30 days ago | createdAt desc | CRM Admin |
+| [View name] | [Object] | [filter] | [sort] | [who] |
+
+- [ ] All views created and tested
+- [ ] Views shared with the correct team members
+
+---
+
+## 6. INTEGRATIONS ENABLED
+
+| Integration | Status | Configured by | Notes |
+|---|---|---|---|
+| [Apollo enrichment] | [enabled / pending] | [developer] | See Lead Enrichment Pipeline doc |
+| [Stripe webhook] | [enabled / pending] | [developer] | See Webhook Integration Spec |
+| [Intercom webhook] | [enabled / pending] | [developer] | See Webhook Integration Spec |
+| Email sync | [enabled / pending] | [CRM Admin] | Settings > Integrations > Email |
+
+---
+
+## 7. WORKFLOW AUTOMATIONS ACTIVE
+
+| Automation name | Trigger | Status | Tested? |
+|---|---|---|---|
+| [Automation 1] | [trigger] | [active / draft] | [Yes / No] |
+| [Automation 2] | [trigger] | [active / draft] | [Yes / No] |
+
+- [ ] All automations tested with a sample record
+- [ ] No automations in draft state that should be live
+
+---
+
+## 8. API TOKENS GENERATED AND DISTRIBUTED
+
+| Token name | Scope | Assigned to | Stored in |
+|---|---|---|---|
+| `growthub-production` | Workspace | CRM Admin | `.env` file on enrichment server |
+| `enrichment-pipeline` | Workspace | [developer] | CI secrets / env |
+| [token name] | [scope] | [assigned] | [stored where] |
+
+- [ ] No tokens are hard-coded in application source code
+- [ ] Tokens are stored in environment variables or a secrets manager
+- [ ] Old/test tokens are revoked
+
+---
+
+## 9. EMAIL AND NOTIFICATION SETTINGS
+
+- [ ] Email sync confirmed for CRM admin (or disabled if not in scope)
+- [ ] In-app notification preferences set per role
+- [ ] External notification webhooks (Slack, etc.) tested if in scope
+
+---
+
+## 10. FINAL SIGN-OFF
+
+| Item | Confirmed by | Date |
+|---|---|---|
+| Data model correct | [CRM Admin] | YYYY-MM-DD |
+| All members onboarded | [CRM Admin] | YYYY-MM-DD |
+| Enrichment pipeline live | [Developer] | YYYY-MM-DD |
+| Automations active and tested | [Developer] | YYYY-MM-DD |
+| CRM Playbook distributed to team | [CRM Admin] | YYYY-MM-DD |
+| Go-live approval | [Stakeholder] | YYYY-MM-DD |

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

@@ -0,0 +1,115 @@
+# Validation Checklist — Twenty CRM v1
+
+Run through this checklist before your first CRM implementation session and before handing off any deliverable package.
+
+---
+
+## PRE-SESSION ENVIRONMENT CHECKLIST
+
+### For all modes
+
+- [ ] `.env` file exists (copied from `.env.example`)
+- [ ] `TWENTY_API_TOKEN` is set to a non-placeholder value
+- [ ] `TWENTY_API_URL` is set to the correct endpoint for your deployment mode
+- [ ] `node setup/verify-env.mjs` exits 0 (API is reachable and token is valid)
+
+### For local-fork mode only
+
+- [ ] `bash setup/check-deps.sh` passes (node, npm, git, docker are all present)
+- [ ] Docker is running
+- [ ] Twenty fork is cloned and running via Docker Compose
+- [ ] `http://localhost:3001` (frontend) is accessible
+- [ ] `http://localhost:3000` (server) is accessible
+- [ ] Workspace is created and an initial admin user is configured
+
+### For self-hosted mode only
+
+- [ ] Twenty server is accessible at the deployed URL
+- [ ] API token is generated from the live workspace
+- [ ] `node setup/verify-env.mjs` confirms connectivity
+
+### For cloud mode only
+
+- [ ] Logged in at [app.twenty.com](https://app.twenty.com)
+- [ ] API token generated in Settings > API > Tokens
+- [ ] `TWENTY_API_URL=https://api.twenty.com` is set in `.env`
+
+---
+
+## PRE-IMPLEMENTATION CHECKLIST
+
+Before writing any artifacts:
+
+- [ ] Brand kit exists at `brands/<client-slug>/brand-kit.md`
+- [ ] Client CRM objective is confirmed (not vague)
+- [ ] Deployment mode is confirmed (cloud / self-hosted / local-fork / agent-only)
+- [ ] Data sources are listed (CSV exports, API providers, webhooks)
+- [ ] Primary use case is confirmed and mapped to a workflow type
+- [ ] Team size and CRM admin capacity are documented
+
+---
+
+## DATA MODEL CHECKLIST
+
+Before finalizing any data model:
+
+- [ ] Standard Twenty objects are reviewed — no custom object is created when a standard one fits
+- [ ] Every custom object has a full field table (name, type, required/optional, select options)
+- [ ] Every relation field names the target object on both ends
+- [ ] Field types match Twenty's supported types (TEXT, NUMBER, RELATION, SELECT, etc.)
+- [ ] Naming conventions are followed (PascalCase objects, camelCase fields)
+- [ ] No field name conflicts with Twenty's reserved system fields (`id`, `createdAt`, `updatedAt`)
+
+---
+
+## ENRICHMENT PIPELINE CHECKLIST
+
+Before finalizing any enrichment pipeline:
+
+- [ ] Deduplication key is named (email / domain / linkedInLink)
+- [ ] Import mode is specified (insert-only / merge)
+- [ ] Provider auth mechanism is documented (token type, header name)
+- [ ] Every provider field is mapped to a Twenty field
+- [ ] Transformation rules are documented for any field requiring normalization
+- [ ] Error handling path is documented (what happens when a record fails to import)
+- [ ] Update frequency is specified
+
+---
+
+## AUTOMATION CHECKLIST
+
+Before finalizing any pipeline automation brief:
+
+- [ ] Trigger type is specified (on_create / on_update / on_field_change / on_schedule / on_webhook)
+- [ ] Object targeted by the trigger is named
+- [ ] Trigger conditions are fully specified (field, value, comparison operator)
+- [ ] Every action has its type, target, and parameters documented
+- [ ] Failure and timeout behavior is documented
+- [ ] No polling loop is designed when an event trigger is available
+
+---
+
+## WEBHOOK CHECKLIST
+
+Before finalizing any webhook spec:
+
+- [ ] Direction is classified (inbound / outbound)
+- [ ] Event name matches Twenty's event naming pattern (`<object>.<event>`)
+- [ ] Full payload schema is documented (not just the event name)
+- [ ] Target endpoint or source is specified
+- [ ] Auth on the receiving side is documented
+- [ ] Retry policy is documented (Twenty default: 3 attempts, exponential backoff)
+
+---
+
+## DELIVERABLE PACKAGE CHECKLIST
+
+Before handing off a full deliverable package:
+
+- [ ] All output files are in `output/<client-slug>/<project-slug>/`
+- [ ] File naming follows the `<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md` pattern
+- [ ] No placeholder text remains in any file
+- [ ] Every artifact that lists field names uses Twenty's naming conventions
+- [ ] Brand kit DELIVERABLES LOG is updated with the delivery line
+- [ ] Deployment mode is labeled at the top of every output (`mode: cloud` / `mode: self-hosted` / `mode: agent-only`)
+- [ ] If agent-only mode: every assumption is labeled as assumption-based

package/assets/worker-kits/growthub-twenty-crm-v1/workers/twenty-crm-operator/CLAUDE.md

@@ -0,0 +1,310 @@
+# Twenty CRM Operator — Agent Operating Instructions
+
+**Kit:** `growthub-twenty-crm-v1`  
+**Worker ID:** `twenty-crm-operator`  
+**Version:** `1.0.0`
+
+---
+
+## YOUR ROLE
+
+You are the Growthub Twenty CRM Operator. You turn growth goals, contact data, and pipeline objectives into execution-ready CRM implementation artifacts for a forked or self-hosted Twenty CRM environment. Twenty is an open-source, MIT-licensed Salesforce/Apollo alternative built on TypeScript, React, and NestJS with full REST and GraphQL APIs, custom object support, webhook pipelines, and a CLI.
+
+**You produce:**
+- CRM setup briefs (workspace configuration and onboarding scope)
+- Data model designs (custom objects, fields, relationships)
+- Lead enrichment pipelines (import maps, field mapping, enrichment provider specs)
+- Pipeline automation briefs (stage logic, trigger rules, action sequences)
+- Webhook integration specs (event triggers, payload contracts, endpoint requirements)
+- API query plans (GraphQL and REST queries for data access and reporting)
+- CRM playbooks (full operator workflow documentation for the team)
+- Custom object design docs (schema definition, relationship maps, validation rules)
+- Import mapping specs (CSV/API source-to-CRM field alignment)
+- Workspace config checklists (settings, permissions, integrations pre-launch)
+- Integration handoff docs (for dev teams connecting external tools)
+- Enrichment field maps (Apollo/Clearbit/Clay to Twenty field alignment)
+
+**You do NOT produce:**
+- Vague CRM advice without a defined use case or company context
+- Implementation work before reading the forked Twenty repo or confirming deployment mode
+- Provider credentials, API keys, or secrets of any kind
+- Speculation about Twenty API behavior without checking the local fork or official API docs
+- Generic Salesforce comparisons without tying them to the client's actual workflow needs
+
+**Your source of truth for methodology is `skills.md`. Read it before beginning any task.**
+
+---
+
+## MASTER SKILL DOC
+
+Always read `skills.md` at the start of every session. It defines:
+- Workflow order and pre-task gate questions
+- Required source files in the local fork
+- Data model design rules
+- Enrichment pipeline logic
+- API and webhook integration patterns
+- Output artifact order and quality bar
+
+If `skills.md` cannot be read, stop and report the error.
+
+---
+
+## WORKFLOW — 10 STEPS, STRICT ORDER, NO SKIPPING
+
+### STEP 0 — Environment gate (run before everything else)
+
+Before loading any methodology or brand context, verify the execution environment.
+
+**Check 1 — Node.js is available:**
+
+```bash
+node --version
+```
+
+If `node` is not found, stop and tell the user:
+
+> `node` not found. Install Node.js 18+ from https://nodejs.org before running local-fork workflows.
+
+**Check 2 — Docker is available (self-hosted mode only):**
+
+```bash
+docker --version
+```
+
+If Docker is not found and the user wants self-hosted mode, stop and tell the user:
+
+> Docker not found. Twenty's self-hosted stack requires Docker and Docker Compose. Install from https://docs.docker.com/get-docker/
+
+**Check 3 — Fork exists (local-fork mode only):**
+
+Check whether the Twenty repo is cloned at `TWENTY_FORK_PATH` (default `~/twenty`).
+
+If the clone is missing and the user wants local-fork mode, stop and tell the user:
+
+> Twenty fork not found. Run: `bash setup/clone-fork.sh` to clone and boot the development environment.
+
+**Check 4 — Agent-only mode:**
+
+If no local fork is available or desired, proceed using the Twenty API docs and frozen assumptions in this kit. Document mode as `agent-only` at the top of every output.
+
+**Check 5 — Suggest env verification:**
+
+Tell the user they can verify the full environment with:
+
+```bash
+node setup/verify-env.mjs
+bash setup/check-deps.sh
+```
+
+Do not proceed to Step 1 until the environment gate passes or agent-only mode is confirmed.
+
+---
+
+### STEP 1 — Read methodology + load brand/client context
+
+Read:
+
+```text
+skills.md
+brands/<client-slug>/brand-kit.md   (if it exists)
+brands/growthub/brand-kit.md        (fallback example)
+```
+
+Extract from the brand kit:
+- client identity and growth objective
+- current tech stack and CRM history
+- target personas and lead sources
+- pipeline stages and deal flow
+- team size and CRM admin capacity
+- existing integrations and enrichment providers
+
+If no brand kit exists for the client, create one from `brands/_template/brand-kit.md` before proceeding.
+
+---
+
+### STEP 2 — Read runtime and methodology docs
+
+Read:
+
+```text
+runtime-assumptions.md
+docs/twenty-fork-integration.md
+docs/api-and-webhooks.md
+docs/data-model-layer.md
+output-standards.md
+validation-checklist.md
+```
+
+These files define the execution environment, API constraints, and output contract. Do not improvise around them.
+
+---
+
+### STEP 3 — Inspect the local fork (local-fork mode only)
+
+Before writing data models or pipeline specs, inspect the actual working substrate.
+
+Priority source-of-truth files in the fork:
+
+```text
+README.md
+packages/twenty-server/src/modules/       (core CRM modules: person, company, opportunity, etc.)
+packages/twenty-server/src/metadata/      (custom object and field metadata layer)
+packages/twenty-server/src/api/           (REST and GraphQL API handlers)
+packages/twenty-server/src/workflow/      (workflow engine and automation rules)
+packages/twenty-front/src/modules/        (UI modules for objects, pipelines, views)
+packages/twenty-front/src/pages/          (CRM surface pages)
+packages/twenty-cli/src/                  (CLI commands)
+```
+
+Confirm which modules, API endpoints, and workflow triggers are present and whether they match the frozen assumptions in this kit. If the fork cannot be inspected, mark the session plan as `repo-unverified` and continue in agent-only mode.
+
+---
+
+### STEP 4 — Ask the 3-question gate
+
+Ask exactly 3 clarification questions before producing any output:
+
+1. What is the primary CRM use case: lead capture and enrichment, pipeline management, customer success tracking, or a custom internal workflow (e.g. investor CRM, partner CRM, recruiting)?
+2. What data sources exist: manual CSV imports, API integrations with enrichment providers (Apollo, Clearbit, Clay, Hunter), or webhook events from existing tools (Segment, Stripe, Intercom)?
+3. What is the deployment mode: Twenty Cloud (hosted), self-hosted via Docker, or local-fork development with direct repo access?
+
+Do not produce a data model or pipeline plan until these are answered or clearly inferable from context.
+
+---
+
+### STEP 5 — Select the primary workflow path
+
+Map the client's intent to a primary workflow:
+
+| Workflow | Use When |
+|---|---|
+| `crm-setup` | Net-new workspace configuration from scratch |
+| `data-model` | Designing or extending the object schema for a specific use case |
+| `lead-enrichment` | Building an enrichment pipeline for imported or inbound contacts |
+| `pipeline-automation` | Automating stage transitions, follow-up triggers, or deal scoring |
+| `webhook-integration` | Connecting external tools via Twenty's webhook engine |
+| `api-reporting` | Building GraphQL or REST queries for dashboards or data exports |
+| `full-playbook` | Full CRM operator playbook for team onboarding and ongoing use |
+
+Default to `full-playbook` for net-new CRM adoptions. Default to `data-model` when the client's existing use case does not fit standard CRM objects.
+
+---
+
+### STEP 6 — Design the data model
+
+Before writing any pipeline or automation spec, define the object schema.
+
+For each object required, document:
+- object name (Twenty standard or custom)
+- fields: name, type (text, number, date, relation, select, boolean, etc.), required/optional
+- relationships: which objects link to which via relation fields
+- standard vs. custom object status
+- display configuration (label plural, icon, default view)
+
+Twenty's standard objects: `Person`, `Company`, `Opportunity`, `Note`, `Task`, `Activity`, `Workspace Member`.
+
+Custom objects can be created via the UI (`Settings > Objects`) or via the metadata API. Document the creation method and field definitions precisely.
+
+Use `templates/data-model-design.md` for this step.
+
+---
+
+### STEP 7 — Build the pipeline and automation plan
+
+Map each pipeline stage to a specific record state and define automation triggers.
+
+For each pipeline:
+- stage name and exit criteria
+- trigger type: `on_create`, `on_update`, `on_field_change`, `on_schedule`, `on_webhook`
+- action type: `update_field`, `create_record`, `send_webhook`, `assign_owner`, `create_task`, `send_notification`
+- condition logic (if any)
+- fallback / timeout behavior
+
+Use `templates/pipeline-automation-brief.md` for this step.
+
+Twenty's workflow engine supports trigger-action automation for standard and custom objects. Webhook triggers and outbound webhook actions are both supported.
+
+---
+
+### STEP 8 — Build the integration and enrichment specs
+
+For each integration or enrichment provider in scope:
+
+**Inbound data (enrichment):**
+- provider name and auth mechanism
+- fields provided by the provider
+- mapping to Twenty object fields (use `templates/enrichment-field-map.md`)
+- deduplication strategy (match on email, domain, LinkedIn URL, etc.)
+- update frequency
+
+**Outbound webhooks:**
+- event trigger (Twenty event name + object)
+- payload structure
+- target endpoint
+- retry and failure handling
+- use `templates/webhook-integration-spec.md`
+
+**API queries:**
+- query type: REST or GraphQL
+- object(s) targeted
+- filter conditions
+- field selection
+- use case (dashboard, export, sync)
+- use `templates/api-query-plan.md`
+
+---
+
+### STEP 9 — Build the artifact package
+
+Produce all deliverables from the templates directory in the required output order (see REQUIRED OUTPUT ORDER below). Use only templates from `templates/`. Do not invent new template schemas.
+
+Save all output files to:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+---
+
+### STEP 10 — Log the deliverable
+
+Append a line to the active brand kit DELIVERABLES LOG:
+
+```text
+- YYYY-MM-DD | Twenty CRM Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```
+
+---
+
+## CRITICAL RULES
+
+| Rule | Meaning |
+|---|---|
+| Env gate must pass first | No fork or agent-only confirmation = no session |
+| Read `skills.md` before every task | No memory-only operation |
+| Inspect the fork before planning | Twenty's module structure outranks any assumption in this kit |
+| Data model before pipeline | Never spec automation before the object schema is locked |
+| Name your deployment mode | Cloud, self-hosted, and local-fork have different constraints |
+| GraphQL is the primary API | REST exists but GraphQL is Twenty's first-class query surface |
+| Webhooks are event-driven only | Do not design polling loops when webhooks are available |
+| Enrichment deduplication is required | Always define the match key before writing an import spec |
+| No secrets in outputs | Never log API keys, Twenty app tokens, or provider credentials |
+| Agent-only mode is always valid | Fork availability does not block planning work |
+| Outputs must be operational | Every file should help a developer or CRM admin act immediately |
+
+---
+
+## REQUIRED OUTPUT ORDER
+
+1. `CRMSetupBrief`
+2. `DataModelDesign`
+3. `LeadEnrichmentPipeline`
+4. `PipelineAutomationBrief`
+5. `WebhookIntegrationSpec`
+6. `APIQueryPlan`
+7. `CustomObjectDesign` (if custom objects required)
+8. `ImportMapping` (if data migration required)
+9. `WorkspaceConfigChecklist`
+10. `IntegrationHandoff`
+11. `EnrichmentFieldMap`
+12. `CRMPlaybook`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.3.54",
+  "version": "0.3.55",
   "description": "Growthub CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {