@growthub/cli 0.3.54 → 0.3.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/README.md +56 -156
  2. package/assets/worker-kits/growthub-ai-website-cloner-v1/.env.example +7 -0
  3. package/assets/worker-kits/growthub-ai-website-cloner-v1/QUICKSTART.md +116 -0
  4. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/NEW-CLIENT.md +22 -0
  5. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/_template/brand-kit.md +27 -0
  6. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/growthub/brand-kit.md +26 -0
  7. package/assets/worker-kits/growthub-ai-website-cloner-v1/bundles/growthub-ai-website-cloner-v1.json +53 -0
  8. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/ai-website-cloner-fork-integration.md +118 -0
  9. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/design-token-system.md +135 -0
  10. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/multi-phase-pipeline.md +129 -0
  11. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/parallel-builder-dispatch.md +103 -0
  12. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/clone-brief-sample.md +54 -0
  13. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/component-spec-sample.md +123 -0
  14. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/platform-handoff-sample.md +102 -0
  15. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/visual-qa-sample.md +119 -0
  16. package/assets/worker-kits/growthub-ai-website-cloner-v1/growthub-meta/README.md +71 -0
  17. package/assets/worker-kits/growthub-ai-website-cloner-v1/growthub-meta/kit-standard.md +47 -0
  18. package/assets/worker-kits/growthub-ai-website-cloner-v1/kit.json +105 -0
  19. package/assets/worker-kits/growthub-ai-website-cloner-v1/output/README.md +26 -0
  20. package/assets/worker-kits/growthub-ai-website-cloner-v1/output-standards.md +75 -0
  21. package/assets/worker-kits/growthub-ai-website-cloner-v1/runtime-assumptions.md +70 -0
  22. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/check-deps.sh +50 -0
  23. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/clone-fork.sh +66 -0
  24. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/verify-env.mjs +78 -0
  25. package/assets/worker-kits/growthub-ai-website-cloner-v1/skills.md +186 -0
  26. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/asset-manifest.md +57 -0
  27. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/builder-dispatch-plan.md +92 -0
  28. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/clone-brief.md +59 -0
  29. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/component-spec.md +124 -0
  30. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/design-token-extraction.md +89 -0
  31. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/platform-handoff.md +114 -0
  32. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/reconnaissance-report.md +77 -0
  33. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/visual-qa-checklist.md +107 -0
  34. package/assets/worker-kits/growthub-ai-website-cloner-v1/validation-checklist.md +76 -0
  35. package/assets/worker-kits/growthub-ai-website-cloner-v1/workers/ai-website-cloner-operator/CLAUDE.md +256 -0
  36. package/assets/worker-kits/growthub-open-montage-studio-v1/.env.example +40 -0
  37. package/assets/worker-kits/growthub-open-montage-studio-v1/QUICKSTART.md +114 -0
  38. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/NEW-CLIENT.md +42 -0
  39. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/_template/brand-kit.md +49 -0
  40. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/growthub/brand-kit.md +50 -0
  41. package/assets/worker-kits/growthub-open-montage-studio-v1/bundles/growthub-open-montage-studio-v1.json +55 -0
  42. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/cms-node-bridge.md +152 -0
  43. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/open-montage-fork-integration.md +120 -0
  44. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/pipeline-reference.md +147 -0
  45. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/provider-adapter-layer.md +105 -0
  46. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/cms-node-video-gen-sample.md +109 -0
  47. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/pipeline-selection-sample.md +67 -0
  48. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/platform-ready-handoff-sample.md +101 -0
  49. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/video-production-brief-sample.md +68 -0
  50. package/assets/worker-kits/growthub-open-montage-studio-v1/growthub-meta/README.md +7 -0
  51. package/assets/worker-kits/growthub-open-montage-studio-v1/growthub-meta/kit-standard.md +45 -0
  52. package/assets/worker-kits/growthub-open-montage-studio-v1/kit.json +107 -0
  53. package/assets/worker-kits/growthub-open-montage-studio-v1/output/README.md +34 -0
  54. package/assets/worker-kits/growthub-open-montage-studio-v1/output-standards.md +79 -0
  55. package/assets/worker-kits/growthub-open-montage-studio-v1/runtime-assumptions.md +86 -0
  56. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/check-deps.sh +43 -0
  57. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/clone-fork.sh +53 -0
  58. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/verify-env.mjs +102 -0
  59. package/assets/worker-kits/growthub-open-montage-studio-v1/skills.md +254 -0
  60. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/asset-tracking.md +46 -0
  61. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/cms-node-pipeline-mapping.md +64 -0
  62. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/generation-batch-plan.md +70 -0
  63. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/pipeline-selection-brief.md +67 -0
  64. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/platform-ready-execution-handoff.md +103 -0
  65. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/prompt-matrix.md +48 -0
  66. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/provider-selection-brief.md +86 -0
  67. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/review-qa-checklist.md +59 -0
  68. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/scene-plan.md +65 -0
  69. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/video-production-brief.md +58 -0
  70. package/assets/worker-kits/growthub-open-montage-studio-v1/validation-checklist.md +46 -0
  71. package/assets/worker-kits/growthub-open-montage-studio-v1/workers/open-montage-studio-operator/CLAUDE.md +304 -0
  72. package/assets/worker-kits/growthub-twenty-crm-v1/.env.example +15 -0
  73. package/assets/worker-kits/growthub-twenty-crm-v1/QUICKSTART.md +90 -0
  74. package/assets/worker-kits/growthub-twenty-crm-v1/brands/NEW-CLIENT.md +57 -0
  75. package/assets/worker-kits/growthub-twenty-crm-v1/brands/_template/brand-kit.md +88 -0
  76. package/assets/worker-kits/growthub-twenty-crm-v1/brands/growthub/brand-kit.md +92 -0
  77. package/assets/worker-kits/growthub-twenty-crm-v1/bundles/growthub-twenty-crm-v1.json +56 -0
  78. package/assets/worker-kits/growthub-twenty-crm-v1/docs/api-and-webhooks.md +296 -0
  79. package/assets/worker-kits/growthub-twenty-crm-v1/docs/data-model-layer.md +172 -0
  80. package/assets/worker-kits/growthub-twenty-crm-v1/docs/twenty-fork-integration.md +213 -0
  81. package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-playbook-sample.md +172 -0
  82. package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-setup-sample.md +100 -0
  83. package/assets/worker-kits/growthub-twenty-crm-v1/examples/lead-enrichment-sample.md +117 -0
  84. package/assets/worker-kits/growthub-twenty-crm-v1/examples/pipeline-automation-sample.md +132 -0
  85. package/assets/worker-kits/growthub-twenty-crm-v1/growthub-meta/README.md +114 -0
  86. package/assets/worker-kits/growthub-twenty-crm-v1/growthub-meta/kit-standard.md +61 -0
  87. package/assets/worker-kits/growthub-twenty-crm-v1/kit.json +108 -0
  88. package/assets/worker-kits/growthub-twenty-crm-v1/output/README.md +46 -0
  89. package/assets/worker-kits/growthub-twenty-crm-v1/output-standards.md +175 -0
  90. package/assets/worker-kits/growthub-twenty-crm-v1/runtime-assumptions.md +150 -0
  91. package/assets/worker-kits/growthub-twenty-crm-v1/setup/check-deps.sh +56 -0
  92. package/assets/worker-kits/growthub-twenty-crm-v1/setup/clone-fork.sh +77 -0
  93. package/assets/worker-kits/growthub-twenty-crm-v1/setup/verify-env.mjs +105 -0
  94. package/assets/worker-kits/growthub-twenty-crm-v1/skills.md +401 -0
  95. package/assets/worker-kits/growthub-twenty-crm-v1/templates/api-query-plan.md +179 -0
  96. package/assets/worker-kits/growthub-twenty-crm-v1/templates/crm-playbook.md +155 -0
  97. package/assets/worker-kits/growthub-twenty-crm-v1/templates/crm-setup-brief.md +94 -0
  98. package/assets/worker-kits/growthub-twenty-crm-v1/templates/custom-object-design.md +115 -0
  99. package/assets/worker-kits/growthub-twenty-crm-v1/templates/data-model-design.md +112 -0
  100. package/assets/worker-kits/growthub-twenty-crm-v1/templates/enrichment-field-map.md +100 -0
  101. package/assets/worker-kits/growthub-twenty-crm-v1/templates/import-mapping.md +139 -0
  102. package/assets/worker-kits/growthub-twenty-crm-v1/templates/integration-handoff.md +190 -0
  103. package/assets/worker-kits/growthub-twenty-crm-v1/templates/lead-enrichment-pipeline.md +128 -0
  104. package/assets/worker-kits/growthub-twenty-crm-v1/templates/pipeline-automation-brief.md +88 -0
  105. package/assets/worker-kits/growthub-twenty-crm-v1/templates/webhook-integration-spec.md +129 -0
  106. package/assets/worker-kits/growthub-twenty-crm-v1/templates/workspace-config-checklist.md +129 -0
  107. package/assets/worker-kits/growthub-twenty-crm-v1/validation-checklist.md +115 -0
  108. package/assets/worker-kits/growthub-twenty-crm-v1/workers/twenty-crm-operator/CLAUDE.md +310 -0
  109. package/package.json +1 -1
@@ -0,0 +1,172 @@
1
+ # Data Model Layer — Twenty CRM
2
+
3
+ **Kit:** `growthub-twenty-crm-v1`
4
+
5
+ ---
6
+
7
+ ## OVERVIEW
8
+
9
+ Twenty CRM's data model layer controls how objects, fields, and relations are defined, stored, and exposed via the API. Understanding this layer is essential for designing accurate CRM schemas and writing reliable migration or enrichment scripts.
10
+
11
+ ---
12
+
13
+ ## STANDARD VS. CUSTOM OBJECTS
14
+
15
+ ### Standard objects
16
+
17
+ Standard objects ship with Twenty and cannot be deleted. Their core fields are fixed, but additional custom fields can be added.
18
+
19
+ | Object | Purpose | Key standard fields |
20
+ |---|---|---|
21
+ | `Person` | Individual contact | `name`, `emails`, `phones`, `company` (relation), `position`, `linkedInLink`, `city` |
22
+ | `Company` | Organization | `name`, `domainName`, `employees`, `annualRecurringRevenue`, `address`, `linkedInLink` |
23
+ | `Opportunity` | Sales pipeline item | `name`, `stage`, `amount`, `closeDate`, `pointOfContact` (relation), `company` (relation) |
24
+ | `Note` | Freeform text | `body`, `noteTargets` (polymorphic relation to any object) |
25
+ | `Task` | Action item | `title`, `body`, `dueAt`, `assignee` (relation to WorkspaceMember), `taskTargets` |
26
+ | `Workspace Member` | CRM user | `name`, `email`, `role` |
27
+
28
+ ### Custom objects
29
+
30
+ Custom objects are created via:
31
+ - **UI:** Settings > Objects > `+ New custom object`
32
+ - **Metadata API:** `createOneObject` mutation at `/metadata`
33
+
34
+ Once created and activated, custom objects are immediately queryable and mutable via the GraphQL API using automatically generated resolvers.
35
+
36
+ **Custom object naming:**
37
+ - `nameSingular`: camelCase (e.g. `partnerAccount`)
38
+ - `namePlural`: camelCase plural (e.g. `partnerAccounts`)
39
+ - `labelSingular`: Display name singular (e.g. `Partner Account`)
40
+ - `labelPlural`: Display name plural (e.g. `Partner Accounts`)
41
+
42
+ ---
43
+
44
+ ## FIELD TYPES
45
+
46
+ | Type | Description | Example values |
47
+ |---|---|---|
48
+ | `TEXT` | Single-line string | `"Jane Doe"`, `"San Francisco"` |
49
+ | `RICH_TEXT` | Multi-line rich text | Note body, description |
50
+ | `NUMBER` | Integer or decimal | `250`, `4.5` |
51
+ | `BOOLEAN` | True/false | `true`, `false` |
52
+ | `DATE` | Date only (ISO 8601) | `"2026-04-15"` |
53
+ | `DATE_TIME` | Date and time (ISO 8601) | `"2026-04-15T10:00:00.000Z"` |
54
+ | `SELECT` | Single choice from options | `"QUALIFIED"`, `"CLOSED_WON"` |
55
+ | `MULTI_SELECT` | Multiple choices | `["INBOUND", "REFERRAL"]` |
56
+ | `RELATION` | Link to another object | `{ id: "<uuid>" }` |
57
+ | `LINK` | URL with optional label | `{ url: "https://...", label: "LinkedIn" }` |
58
+ | `EMAILS` | Multi-email with primary | `{ primaryEmail: "jane@example.com" }` |
59
+ | `PHONES` | Multi-phone with primary | `{ primaryPhoneNumber: "+14155550100" }` |
60
+ | `CURRENCY` | Amount + currency code | `{ amountMicros: 10000000, currencyCode: "USD" }` |
61
+ | `ADDRESS` | Structured address | `{ addressStreet1: "...", addressCity: "...", addressCountryCode: "US" }` |
62
+ | `RATING` | Star rating (1–5) | `"RATING_4"` |
63
+ | `FULL_NAME` | First + last name pair | `{ firstName: "Jane", lastName: "Doe" }` |
64
+ | `UUID` | Universally unique identifier | `"a3d9f2..."` |
65
+
66
+ ---
67
+
68
+ ## RELATIONS
69
+
70
+ Twenty uses three types of relations between objects:
71
+
72
+ | Relation type | Description |
73
+ |---|---|
74
+ | One-to-one | One record on each side (rare) |
75
+ | One-to-many | One parent record links to many child records (e.g. Company → many Persons) |
76
+ | Many-to-many | Records on both sides can link to multiple records on the other side |
77
+
78
+ ### Relation field definition
79
+
80
+ When you add a RELATION field to an object, you define:
81
+ - **Source object** (where the field appears)
82
+ - **Target object** (what it links to)
83
+ - **Cardinality** (one-to-one, one-to-many, many-to-many)
84
+ - **Field name** on both the source and target sides
85
+
86
+ ### Standard relation examples
87
+
88
+ ```text
89
+ Person ─── company (manyToOne) ──> Company
90
+ Company ─── people (oneToMany) ──> [Person]
91
+
92
+ Opportunity ─── pointOfContact (manyToOne) ──> Person
93
+ Opportunity ─── company (manyToOne) ──> Company
94
+
95
+ Note ─── noteTargets (polymorphic) ──> [Person | Company | Opportunity | ...]
96
+ Task ─── taskTargets (polymorphic) ──> [Person | Company | Opportunity | ...]
97
+ ```
98
+
99
+ ---
100
+
101
+ ## SELECT FIELD OPTIONS
102
+
103
+ SELECT fields require predefined options. Each option has:
104
+ - `value`: internal identifier, `SCREAMING_SNAKE_CASE` (e.g. `CLOSED_WON`)
105
+ - `label`: display name (e.g. `Closed Won`)
106
+ - `color`: optional UI color for the badge
107
+ - `position`: display order
108
+
109
+ **Opportunity stage options (default):**
110
+
111
+ | Value | Label | Typical position |
112
+ |---|---|---|
113
+ | `LEAD` | Lead | 1 |
114
+ | `QUALIFIED` | Qualified | 2 |
115
+ | `MEETING` | Meeting | 3 |
116
+ | `PROPOSAL` | Proposal | 4 |
117
+ | `CUSTOMER` | Customer | 5 |
118
+ | `CLOSED` | Closed | 6 |
119
+
120
+ **Note:** The exact default stage values depend on the Twenty version and workspace seed. Inspect the actual Opportunity object in your workspace before mapping stage values in automation or import scripts.
121
+
122
+ ---
123
+
124
+ ## CURRENCY FIELD: MICROS FORMAT
125
+
126
+ Twenty stores currency amounts in **micros** (millionths of the base unit) to avoid floating-point precision issues.
127
+
128
+ **Conversion:**
129
+ - `$10,000` → `amountMicros: 10000000000` (multiply by 1,000,000)
130
+ - `amountMicros: 5000000` → `$5` (divide by 1,000,000)
131
+
132
+ Always convert amounts to micros before writing to the API. Always divide by 1,000,000 when reading amounts for display.
133
+
134
+ ---
135
+
136
+ ## ID FORMAT
137
+
138
+ All Twenty record IDs are UUIDs (version 4). Example:
139
+
140
+ ```
141
+ a3d9f2c1-4b5e-4a8b-9c7d-0e1f2a3b4c5d
142
+ ```
143
+
144
+ Never assume sequential IDs. Use the UUID when referencing related records in mutations.
145
+
146
+ ---
147
+
148
+ ## SYSTEM FIELDS
149
+
150
+ Every object (standard or custom) automatically includes these system fields:
151
+
152
+ | Field | Type | Notes |
153
+ |---|---|---|
154
+ | `id` | UUID | Primary key — auto-generated |
155
+ | `createdAt` | DATE_TIME | Set at creation — do not override |
156
+ | `updatedAt` | DATE_TIME | Set on every update — do not override |
157
+ | `deletedAt` | DATE_TIME | Set on soft delete — null if record is active |
158
+
159
+ Do not create custom fields with these names.
160
+
161
+ ---
162
+
163
+ ## DATABASE LAYER
164
+
165
+ Twenty uses PostgreSQL. Each workspace has its own schema (multi-tenant by schema). Custom objects create new tables within the workspace schema.
166
+
167
+ For local-fork development:
168
+ - PostgreSQL runs on `localhost:5432` (Docker)
169
+ - Default credentials are in `.env` (from `.env.example`)
170
+ - Use `npx nx run twenty-server:database:migrate` to run migrations after code changes
171
+
172
+ **Do not query the database directly in production.** Always use the GraphQL or REST API. Direct database access is only appropriate during local-fork development for schema inspection.
@@ -0,0 +1,213 @@
1
+ # Twenty Fork Integration — Developer Notes
2
+
3
+ **Kit:** `growthub-twenty-crm-v1`
4
+ **Repo:** `github.com/twentyhq/twenty`
5
+ **Stack:** TypeScript / React / NestJS / PostgreSQL / Redis
6
+
7
+ ---
8
+
9
+ ## OVERVIEW
10
+
11
+ Twenty is a fully open-source CRM built to replace Salesforce and Apollo-style tools for teams that want control over their data and growth stack. It ships with a REST and GraphQL API, a workflow engine, custom object support, and a CLI. This document defines how this kit targets the Twenty fork for local development and self-hosted deployments.
12
+
13
+ ---
14
+
15
+ ## REPOSITORY STRUCTURE (KEY PATHS)
16
+
17
+ ```text
18
+ twenty/
19
+ ├── packages/
20
+ │ ├── twenty-server/ # NestJS API server
21
+ │ │ ├── src/
22
+ │ │ │ ├── modules/ # CRM domain modules (Person, Company, Opportunity, etc.)
23
+ │ │ │ ├── metadata/ # Custom object and field metadata API
24
+ │ │ │ ├── api/ # REST and GraphQL endpoint handlers
25
+ │ │ │ └── workflow/ # Workflow engine (triggers, actions)
26
+ │ ├── twenty-front/ # React frontend (Vite)
27
+ │ │ ├── src/
28
+ │ │ │ ├── modules/ # UI modules per CRM object
29
+ │ │ │ └── pages/ # Page definitions
30
+ │ └── twenty-cli/ # CLI package (@twenty-crm/cli)
31
+ │ └── src/ # CLI commands (workspace management, etc.)
32
+ ├── docker-compose.yml # Local development stack
33
+ ├── .env.example # Server environment template
34
+ └── README.md
35
+ ```
36
+
37
+ ---
38
+
39
+ ## STANDARD OBJECT MODULES
40
+
41
+ Each standard CRM object lives in `packages/twenty-server/src/modules/<object>/`:
42
+
43
+ | Object module | Key files |
44
+ |---|---|
45
+ | `person` | `person.entity.ts`, `person.repository.ts`, `person.resolver.ts` |
46
+ | `company` | `company.entity.ts`, `company.repository.ts`, `company.resolver.ts` |
47
+ | `opportunity` | `opportunity.entity.ts`, `opportunity.resolver.ts` |
48
+ | `note` | `note.entity.ts`, `note.resolver.ts` |
49
+ | `task` | `task.entity.ts`, `task.resolver.ts` |
50
+
51
+ **Inspecting standard object fields:** Read the entity file (e.g. `person.entity.ts`) to confirm which fields are available, their types, and which are required.
52
+
53
+ ---
54
+
55
+ ## METADATA API (CUSTOM OBJECTS)
56
+
57
+ Custom objects and fields are managed via the metadata API at `/metadata`.
58
+
59
+ ### Creating a custom object
60
+
61
+ ```graphql
62
+ POST <TWENTY_API_URL>/metadata
63
+ Authorization: Bearer <token>
64
+
65
+ mutation CreateObject {
66
+ createOneObject(input: {
67
+ labelSingular: "Partner Account"
68
+ labelPlural: "Partner Accounts"
69
+ nameSingular: "partnerAccount"
70
+ namePlural: "partnerAccounts"
71
+ icon: "IconBuilding"
72
+ description: "Tracks partner organizations separately from customers"
73
+ }) {
74
+ id
75
+ nameSingular
76
+ isActive
77
+ }
78
+ }
79
+ ```
80
+
81
+ ### Adding a field to a custom object
82
+
83
+ ```graphql
84
+ mutation CreateTextField {
85
+ createOneField(input: {
86
+ objectMetadataId: "<object-id>"
87
+ type: TEXT
88
+ name: "partnerTier"
89
+ label: "Partner Tier"
90
+ isNullable: true
91
+ defaultValue: null
92
+ }) {
93
+ id
94
+ name
95
+ type
96
+ }
97
+ }
98
+ ```
99
+
100
+ ### Activating a custom object
101
+
102
+ After creation, activate via the UI (Settings > Objects > toggle Active) or via API:
103
+
104
+ ```graphql
105
+ mutation ActivateObject {
106
+ activateWorkspaceObject(input: { id: "<object-id>" }) {
107
+ id
108
+ isActive
109
+ }
110
+ }
111
+ ```
112
+
113
+ ---
114
+
115
+ ## WORKFLOW ENGINE
116
+
117
+ Twenty's workflow engine is in `packages/twenty-server/src/workflow/`.
118
+
119
+ ### Trigger types (frozen assumptions, verify in fork)
120
+
121
+ | Trigger | Description |
122
+ |---|---|
123
+ | `RECORD_CREATED` | Fires when a record of the target object is created |
124
+ | `RECORD_UPDATED` | Fires when a record is updated |
125
+ | `MANUAL` | Manually triggered by a user |
126
+ | `CRON` | Time-based schedule |
127
+
128
+ ### Action types (frozen assumptions, verify in fork)
129
+
130
+ | Action | Description |
131
+ |---|---|
132
+ | `SEND_EMAIL` | Send an email |
133
+ | `CREATE_RECORD` | Create a CRM record |
134
+ | `UPDATE_RECORD` | Update a CRM record |
135
+ | `DELETE_RECORD` | Delete a CRM record |
136
+ | `CODE` | Execute a custom code action (TypeScript function) |
137
+ | `FILTER` | Condition filter (branch logic) |
138
+ | `SEND_HTTP_REQUEST` | Outbound HTTP POST (webhook action) |
139
+
140
+ **Recommendation for custom automation logic:** Use the `CODE` action type for complex conditional logic that the standard action types do not support. The CODE action executes a TypeScript function in a sandboxed environment.
141
+
142
+ ---
143
+
144
+ ## LOCAL DEVELOPMENT STACK
145
+
146
+ ### Prerequisites
147
+
148
+ - Docker and Docker Compose
149
+ - Node.js 18+
150
+ - Git
151
+
152
+ ### Boot sequence
153
+
154
+ ```bash
155
+ git clone https://github.com/twentyhq/twenty ~/twenty
156
+ cd ~/twenty
157
+ cp .env.example .env
158
+ docker-compose up -d
159
+ ```
160
+
161
+ Services started:
162
+ - `twenty-server` — NestJS API at `http://localhost:3000`
163
+ - `twenty-front` — React frontend at `http://localhost:3001`
164
+ - `postgres` — PostgreSQL at `localhost:5432`
165
+ - `redis` — Redis at `localhost:6379`
166
+
167
+ ### Running migrations
168
+
169
+ ```bash
170
+ npx nx run twenty-server:database:migrate
171
+ ```
172
+
173
+ ### Seeding the database
174
+
175
+ ```bash
176
+ npx nx run twenty-server:database:seed
177
+ ```
178
+
179
+ ### Accessing the GraphQL playground
180
+
181
+ Navigate to `http://localhost:3000/graphql` in the browser. The playground requires an active Bearer token.
182
+
183
+ ---
184
+
185
+ ## KNOWN FORK CONSIDERATIONS
186
+
187
+ ### Environment variables (`.env`)
188
+
189
+ The Twenty server requires several environment variables. Key ones:
190
+
191
+ | Variable | Purpose |
192
+ |---|---|
193
+ | `PG_DATABASE_URL` | PostgreSQL connection string |
194
+ | `REDIS_URL` | Redis connection string |
195
+ | `SERVER_URL` | Public API URL (used for webhooks) |
196
+ | `FRONT_BASE_URL` | Frontend URL |
197
+ | `SIGN_IN_PREFILLED` | Pre-fill sign-in for local dev |
198
+ | `STORAGE_TYPE` | `local` (dev) or `s3` (production) |
199
+
200
+ ### First-time workspace setup
201
+
202
+ After booting Docker Compose, navigate to `http://localhost:3001` and create your first workspace. The default seeded admin credentials (if seeded) are in the Twenty README.
203
+
204
+ ### CLI
205
+
206
+ The Twenty CLI (`@twenty-crm/cli`) provides workspace management commands:
207
+
208
+ ```bash
209
+ npx twenty workspace:create --name "My Workspace"
210
+ npx twenty workspace:list
211
+ ```
212
+
213
+ Run `npx twenty --help` for the full command surface.
@@ -0,0 +1,172 @@
1
+ # CRM Playbook — Growthub (SAMPLE)
2
+
3
+ **Date:** 2026-04-15
4
+ **Kit:** `growthub-twenty-crm-v1`
5
+ **Version:** v1
6
+
7
+ > **Note:** This is a sample output. Adapt all procedures to the actual client context.
8
+
9
+ ---
10
+
11
+ ## ABOUT THIS PLAYBOOK
12
+
13
+ This playbook is the operating manual for the Growthub Twenty CRM workspace. It defines roles, daily workflows, pipeline procedures, and data hygiene rules. All four team members with CRM access must read this before their first session.
14
+
15
+ ---
16
+
17
+ ## 1. TEAM ROLES AND PERMISSIONS
18
+
19
+ | Role | Name | Access level | Responsibilities |
20
+ |---|---|---|---|
21
+ | CRM Admin | Antonio Romero | Full access | Object config, member management, integration maintenance, data hygiene |
22
+ | Sales Rep | [Rep 1] | Create/edit own records | Lead creation, pipeline updates, notes |
23
+ | Sales Rep | [Rep 2] | Create/edit own records | Lead creation, pipeline updates, notes |
24
+ | CS Manager | [CS] | Read/edit post-close | Customer success tracking, renewal notes |
25
+
26
+ **Onboarding new members:** CRM Admin creates the workspace member in Settings > Members, assigns the correct role, and shares this playbook.
27
+
28
+ ---
29
+
30
+ ## 2. DAILY WORKFLOW
31
+
32
+ ### Sales rep daily workflow (10–15 min)
33
+
34
+ 1. Log in to Twenty and open **Pipeline Board** view (pre-filtered: open opportunities, my records)
35
+ 2. Review new leads assigned to you in the LEAD stage — move any that are ICP-qualified to QUALIFIED
36
+ 3. For every call or email from today: add a Note on the Person record (what you discussed, next step, date)
37
+ 4. Check Tasks due today — complete each or reschedule with a Note explaining the delay
38
+ 5. End of day: every new contact from today's outreach must be in Twenty before logging off
39
+
40
+ **Expected daily time investment:** 10–15 minutes
41
+
42
+ ### CRM Admin daily workflow (5–10 min)
43
+
44
+ 1. Check import error log if enrichment pipeline ran overnight
45
+ 2. Spot-check 3 records for data quality (no blank required fields, company linked, stage current)
46
+ 3. Check workflow logs (Settings > Workflows) for any automation failures
47
+
48
+ ---
49
+
50
+ ## 3. PIPELINE MANAGEMENT PROCEDURES
51
+
52
+ ### Creating a new Opportunity
53
+
54
+ 1. Navigate to Opportunities → click `+ New`
55
+ 2. Fill in: **Name** (e.g. "Acme Corp — Growthub Platform"), **Stage** (start at LEAD), **Amount**, **Close Date**
56
+ 3. Link **Point of Contact** (Person) and **Company**
57
+ 4. Set **Assignee** to yourself or the responsible rep
58
+ 5. Add a first Note: where did this lead come from, what is the hook?
59
+
60
+ ### Moving a stage
61
+
62
+ 1. Open the Opportunity → click the stage badge at the top
63
+ 2. Select the new stage
64
+ 3. Add a Note immediately explaining what happened and what the next step is
65
+ 4. If moving to **CLOSED_WON**: confirm Amount and Close Date are accurate before saving
66
+ 5. If moving to **CLOSED_LOST**: add a Note with the reason (e.g. "No budget Q2", "Chose competitor", "Ghosted after demo")
67
+
68
+ **Pipeline stages and exit criteria:**
69
+
70
+ | Stage | Exit criteria |
71
+ |---|---|
72
+ | LEAD | ICP fit confirmed + email opened or replied |
73
+ | QUALIFIED | Discovery call complete, pain confirmed, budget range known |
74
+ | DEMO | Product demo complete, specific use case validated |
75
+ | PROPOSAL | Commercial terms sent or under negotiation |
76
+ | CLOSED_WON | Contract signed, payment confirmed |
77
+ | CLOSED_LOST | Explicitly lost or no response after 3 follow-ups past close date |
78
+
79
+ ### Weekly pipeline review (team — 30 min)
80
+
81
+ **View:** Pipeline Board filtered to QUALIFIED + DEMO + PROPOSAL
82
+ **Sort:** Close Date ascending
83
+
84
+ For each open opportunity in the top 10 by close date:
85
+ - Is the stage accurate?
86
+ - When was the last Note added? (if >7 days, flag as stale)
87
+ - What is the next action and who owns it?
88
+ - Is there a Task assigned for the next action?
89
+
90
+ ---
91
+
92
+ ## 4. ENRICHMENT CADENCE
93
+
94
+ **Schedule:** Weekly on Monday at 6 AM (automated cron job)
95
+
96
+ **What runs automatically:**
97
+ - Apollo enrichment job pulls the latest saved search export and runs a merge import into Twenty
98
+ - New Person records are created; existing records are updated with latest enrichment data
99
+
100
+ **What to do if the enrichment job fails:**
101
+ 1. CRM Admin checks the error log file `enrichment-errors.csv` (stored in the enrichment job output)
102
+ 2. Review skipped records — most common reason is missing email
103
+ 3. Manually add missing contacts from Apollo if volume is small (< 20 records)
104
+ 4. Contact [developer] if the job fails to run at all (check cron logs)
105
+
106
+ ---
107
+
108
+ ## 5. REPORTING AND DASHBOARD INSTRUCTIONS
109
+
110
+ ### Pipeline health view (built in Twenty)
111
+
112
+ **Filter:** Opportunities where stage IN [QUALIFIED, DEMO, PROPOSAL]
113
+ **Group by:** Stage
114
+ **Sort:** Close Date ascending
115
+
116
+ **Reading the view:**
117
+ - Count in each stage = pipeline coverage (healthy = more in LEAD/QUALIFIED than PROPOSAL)
118
+ - Total amount in DEMO + PROPOSAL = near-term revenue signal
119
+ - Opportunities with last Note > 14 days old = stale — review in weekly pipeline call
120
+
121
+ ### Weekly metrics to track (manual, 5 min)
122
+
123
+ Count from Twenty each Friday:
124
+ - New Opportunities created this week
125
+ - Opportunities moved to CLOSED_WON this week
126
+ - Opportunities moved to CLOSED_LOST this week + note the loss reasons
127
+ - Opportunities moved to DEMO this week (pipeline velocity indicator)
128
+
129
+ ---
130
+
131
+ ## 6. ESCALATION AND HANDOFF PROTOCOLS
132
+
133
+ ### Record dispute (wrong data)
134
+
135
+ 1. Do **not** delete the record
136
+ 2. Add a Note: "Data quality issue — [describe problem]" and tag `@antonio`
137
+ 3. CRM Admin reviews and resolves within 2 business days
138
+
139
+ ### Integration failure
140
+
141
+ 1. Check Settings > Workflows for automation errors
142
+ 2. Check enrichment error log file
143
+ 3. If unresolved: email [developer contact] with the error message and timestamp
144
+ 4. CRM Admin documents the gap in a Note on the affected object if data is missing
145
+
146
+ ### Offboarding a team member
147
+
148
+ 1. CRM Admin reassigns all open Opportunities from the departing member to the remaining rep
149
+ 2. Reassigns all open Tasks
150
+ 3. Deactivates the workspace member (Settings > Members > Deactivate)
151
+ 4. Revokes any API tokens the member had access to
152
+
153
+ ---
154
+
155
+ ## 7. MAINTENANCE AND DATA HYGIENE CHECKLIST
156
+
157
+ **Weekly (CRM Admin — 15 min):**
158
+ - [ ] Review import error log — resolve skipped records
159
+ - [ ] Check stale Opportunities (no update in 14 days) — flag for reps to update
160
+ - [ ] Confirm all Closed Won / Closed Lost opportunities have a loss/win reason Note
161
+
162
+ **Monthly (CRM Admin — 30 min):**
163
+ - [ ] Search for duplicate Person records (same email) — merge duplicates
164
+ - [ ] Search for Companies with no linked Persons — flag for review or archive
165
+ - [ ] Review workflow logs for repeated failures — escalate to developer if pattern
166
+ - [ ] Update this playbook if any procedures have changed
167
+
168
+ **Quarterly (CRM Admin + head of sales — 60 min):**
169
+ - [ ] Review pipeline stage definitions — do they still match how we sell?
170
+ - [ ] Evaluate enrichment provider data quality — are enriched fields accurate?
171
+ - [ ] Review custom field usage — archive any fields the team stopped using
172
+ - [ ] Check if new automation opportunities exist based on team pain points
@@ -0,0 +1,100 @@
1
+ # CRM Setup Brief — Growthub (SAMPLE)
2
+
3
+ **Date:** 2026-04-15
4
+ **Operator:** `twenty-crm-operator`
5
+ **Kit:** `growthub-twenty-crm-v1`
6
+ **Mode:** `cloud`
7
+
8
+ > **Note:** This is a sample output illustrating the quality and format expected from this kit. Adapt all values to the actual client context.
9
+
10
+ ---
11
+
12
+ ## 1. CLIENT CONTEXT AND CRM OBJECTIVE
13
+
14
+ **Client:** Growthub
15
+ **Industry:** B2B SaaS / Growth Platform
16
+ **Company size:** 12 employees
17
+ **CRM objective:** Build a structured outbound sales pipeline with automated lead enrichment from Apollo, Stripe event capture, and Intercom conversation logging.
18
+
19
+ **Why Twenty:**
20
+ - Open-source, MIT license — no vendor lock-in risk for a growing platform company
21
+ - TypeScript/React/NestJS stack matches Growthub's existing codebase — easier to self-host and extend
22
+ - REST and GraphQL APIs make it straightforward to build custom enrichment pipelines
23
+ - Custom object support handles the non-standard Growthub product-led-growth workflow
24
+
25
+ ---
26
+
27
+ ## 2. DEPLOYMENT MODE
28
+
29
+ **Selected mode:** `cloud`
30
+ **API URL:** `https://api.twenty.com`
31
+ **Environment:** production
32
+
33
+ **Prerequisites confirmed:**
34
+ - [x] Twenty workspace created at app.twenty.com
35
+ - [x] API token generated: `growthub-production` token (stored in `.env`)
36
+ - [x] `node setup/verify-env.mjs` exits 0 — connected to workspace "Growthub" (id: abc123)
37
+
38
+ ---
39
+
40
+ ## 3. TEAM SIZE AND USER ROLES
41
+
42
+ | Role | User | Permissions |
43
+ |---|---|---|
44
+ | CRM Admin | Antonio Romero | Full access |
45
+ | Sales Rep | [Sales Rep 1] | Create/edit Opportunities and Persons |
46
+ | Sales Rep | [Sales Rep 2] | Create/edit Opportunities and Persons |
47
+ | CS Manager | [CS Manager] | Read/edit Opportunities post-close |
48
+
49
+ **Total workspace members:** 4
50
+
51
+ ---
52
+
53
+ ## 4. DATA SOURCES AND VOLUME ESTIMATES
54
+
55
+ | Source | Object type | Estimated volume | Import method |
56
+ |---|---|---|---|
57
+ | Apollo CSV export | Person + Company | ~1,200 contacts, ~400 companies | CSV import |
58
+ | Stripe | Company + Note | ~50 new customers/month | Webhook (customer.created) |
59
+ | Intercom | Note | ~150 conversations/month | Webhook (conversation.created) |
60
+
61
+ ---
62
+
63
+ ## 5. INTEGRATION SCOPE
64
+
65
+ | Integration | Direction | Priority |
66
+ |---|---|---|
67
+ | Apollo | Inbound enrichment | High |
68
+ | Stripe | Inbound webhook | High |
69
+ | Intercom | Inbound webhook | Medium |
70
+ | Slack | Outbound notification (Closed Won) | Low |
71
+
72
+ ---
73
+
74
+ ## 6. GO-LIVE TIMELINE AND MILESTONES
75
+
76
+ | Milestone | Target date | Owner |
77
+ |---|---|---|
78
+ | Data model finalized | 2026-04-18 | Antonio (CRM Admin) |
79
+ | Initial Apollo import complete | 2026-04-20 | Antonio |
80
+ | Stripe webhook live | 2026-04-22 | Developer |
81
+ | Intercom webhook live | 2026-04-25 | Developer |
82
+ | Stage automations active | 2026-04-25 | Developer |
83
+ | Team onboarded | 2026-04-28 | Antonio |
84
+
85
+ ---
86
+
87
+ ## 7. SUCCESS CRITERIA
88
+
89
+ - [x] All 1,200 contacts imported and deduplicated against email
90
+ - [x] Pipeline visible with 6 stages (Lead → Closed Won/Lost)
91
+ - [x] 3 automations active (stage change → task creation, Closed Won → Slack notify, Intercom → Note)
92
+ - [x] Stripe enrichment running on customer.created event
93
+ - [x] All 4 team members onboarded and logging daily activity in the CRM
94
+
95
+ ---
96
+
97
+ ## OPEN QUESTIONS
98
+
99
+ - [ ] Does the head of sales want round-robin assignment or territory-based routing?
100
+ - [ ] Should Intercom conversations be logged as Notes on Person or as a custom Activity object?