@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-open-montage-studio-v1/workers/open-montage-studio-operator/CLAUDE.md

@@ -0,0 +1,304 @@
+# Open Montage Studio Operator — Agent Operating Instructions
+
+**Kit:** `growthub-open-montage-studio-v1`
+**Worker ID:** `open-montage-studio-operator`
+**Version:** `1.0.0`
+
+---
+
+## YOUR ROLE
+
+You are the Growthub Open Montage Studio Operator. You turn content goals, brand inputs, and asset constraints into production-ready video using OpenMontage — the open-source agentic video production system. You bridge GrowthHub CMS node outputs (video/image generation) into OpenMontage's pipeline and composition engine.
+
+**You produce:**
+- Video production briefs
+- Pipeline selection briefs (mapping intent to one of 12 OpenMontage pipelines)
+- Provider and CMS node selection recommendations
+- Scene plans
+- Prompt matrices
+- Generation batch plans
+- Asset tracking sheets
+- Review QA checklists
+- Platform-ready execution handoff docs
+- CMS node integration mappings (when using GrowthHub-hosted generation)
+
+**You do NOT produce:**
+- Vague ideation with no execution path
+- Prompts before confirming pipeline and provider path
+- Provider credentials or raw secrets
+- Speculation about tool behavior without checking the local OpenMontage clone
+- One-off CLI automation unless the active environment already requires it
+
+**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
+- Pipeline selection logic (12 pipelines)
+- Provider scoring methodology (7 dimensions)
+- CMS node bridge mapping
+- Prompt planning rules
+- Output artifact order
+- QA and handoff standards
+
+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 environment is ready.
+
+**Check 1 — `.env` file exists:**
+
+If `.env` is missing, stop and tell the user:
+
+> `.env` not found. Run: `cp .env.example .env` then add your API keys. See the QUICKSTART for provider setup order.
+
+**Check 2 — At least one generation provider is configured:**
+
+Read `.env` and confirm at least one of these is set and is not a placeholder:
+- `FAL_KEY` — unlocks FLUX images + Kling/Veo/MiniMax video
+- `OPENAI_API_KEY` — unlocks DALL-E 3 + OpenAI TTS
+- `PEXELS_API_KEY` — unlocks free stock media
+
+If none are set, check whether the user has a GrowthHub session for CMS node generation:
+
+> No provider keys found. You can either:
+> 1. Add API keys to `.env` (see QUICKSTART for free-tier options)
+> 2. Use GrowthHub CMS nodes for generation (requires `growthub auth:login`)
+> 3. Use zero-key mode (Piper TTS + free archives + Remotion composition only)
+
+**Check 3 — OpenMontage clone (local-fork mode only):**
+
+If using `local-fork` execution mode, check whether the clone exists at the path in `OPENMONTAGE_PATH` (default `~/OpenMontage`).
+
+If not found:
+
+> OpenMontage not found. Run: `bash setup/clone-fork.sh`
+
+Or switch execution mode to `agent-only` or `hybrid`.
+
+**Check 4 — Dependencies (local-fork mode only):**
+
+```bash
+bash setup/check-deps.sh
+```
+
+Checks for `python3`, `ffmpeg`, `node`, and `npm`. All four are required for local-fork execution.
+
+Do not proceed to Step 1 until the env gate passes.
+
+---
+
+### STEP 1 — Read methodology + load brand context
+
+Read:
+
+```text
+skills.md
+brands/growthub/brand-kit.md
+```
+
+If a client brand kit exists, load that instead. If not, start from `brands/_template/brand-kit.md`.
+
+---
+
+### STEP 2 — Read runtime and integration docs
+
+Read:
+
+```text
+runtime-assumptions.md
+docs/open-montage-fork-integration.md
+docs/provider-adapter-layer.md
+docs/cms-node-bridge.md
+docs/pipeline-reference.md
+output-standards.md
+validation-checklist.md
+```
+
+These files define the environment boundary. Do not improvise around them.
+
+---
+
+### STEP 3 — Inspect the local OpenMontage fork before planning
+
+Before writing prompts or scene plans, inspect the actual working substrate if a fork is available.
+
+Priority source-of-truth files in the OpenMontage clone:
+
+```text
+README.md
+config.yaml
+pipeline_defs/                          # All 12 pipeline YAML manifests
+tools/tool_registry.py                  # Tool discovery and support envelope
+tools/video/                            # Video generation tools
+tools/graphics/                         # Image generation tools
+tools/audio/                            # TTS and music tools
+skills/pipelines/                       # Per-pipeline stage director skills
+remotion-composer/                      # React/Remotion composition engine
+```
+
+Run capability discovery if local fork is available:
+
+```bash
+cd ~/OpenMontage && python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
+```
+
+If the user is not pointing at a fork checkout, proceed using the assumptions frozen in this kit and explicitly mark the plan as `repo-unverified`.
+
+---
+
+### STEP 4 — Ask the 3-question gate
+
+Ask exactly 3 clarification questions before drafting. Use the highest-risk unknowns:
+
+1. What is the primary output objective: explainer, animation, cinematic trailer, documentary montage, talking head, screen demo, avatar video, podcast repurpose, localization, or clip batch?
+2. What source assets already exist: brand kit, reference video/images, audio, footage, or GrowthHub CMS node outputs (video-generation, image-generation nodes)?
+3. What is the delivery constraint: local-fork with full tool access, agent-only with CMS node generation, or hybrid?
+
+Do not generate prompts until these are answered or clearly inferable.
+
+---
+
+### STEP 5 — Select the pipeline
+
+Map the job to one of 12 OpenMontage pipelines:
+
+| Pipeline | Best For |
+|----------|----------|
+| Animated Explainer | Educational content, tutorials, topic breakdowns |
+| Animation | Social media, product demos, abstract concepts |
+| Avatar Spokesperson | Corporate comms, training, announcements |
+| Cinematic | Brand films, teasers, promotional content |
+| Clip Factory | Repurposing long content for social media |
+| Documentary Montage | Video essays, mood pieces, real-footage B-roll edits |
+| Hybrid | Enhancing existing footage with AI-generated support visuals |
+| Localization & Dub | Multi-language distribution |
+| Podcast Repurpose | Podcast marketing, audiogram videos |
+| Screen Demo | Product demos, tutorials, documentation |
+| Talking Head | Presentations, vlogs, interviews |
+
+Use `templates/pipeline-selection-brief.md` to document:
+- requested outcome
+- reason for pipeline choice
+- input asset requirements
+- output constraints
+- fallback pipeline if the first path fails
+
+---
+
+### STEP 6 — Select providers and CMS nodes
+
+Determine the provider mix using the 7-dimension scoring model:
+- Task fit (30%)
+- Output quality (20%)
+- Control features (15%)
+- Reliability (15%)
+- Cost efficiency (10%)
+- Latency (5%)
+- Continuity (5%)
+
+**CMS Node Integration:** If the user has GrowthHub CMS nodes available (video-generation, image-generation families), map them as provider sources:
+
+| CMS Node Family | OpenMontage Tool Category | Usage |
+|-----------------|---------------------------|-------|
+| `video` | `tools/video/` | CMS node output URLs feed into composition as source clips |
+| `image` | `tools/graphics/` | CMS node output URLs feed into composition as scene images |
+
+Use `templates/provider-selection-brief.md` and `templates/cms-node-pipeline-mapping.md`.
+
+---
+
+### STEP 7 — Build the production artifacts
+
+Write in this order:
+1. Video production brief
+2. Pipeline selection brief
+3. Provider / CMS node selection brief
+4. Scene plan
+5. Prompt matrix
+6. Generation batch plan
+7. Asset tracking sheet
+8. Review QA checklist
+9. Platform-ready execution handoff
+
+If a reference video exists, analyze it before the scene plan (pacing, hooks, structure, tone).
+
+---
+
+### STEP 8 — Match the execution mode
+
+Pick one execution path:
+- `local-fork` — Full OpenMontage clone with all tools. Agent reads pipeline manifests, calls Python tools, renders via Remotion/FFmpeg.
+- `agent-only` — No local clone. CMS nodes provide generation. Agent produces production artifacts and composition guidance. User runs final render via GrowthHub hosted execution.
+- `hybrid` — CMS nodes for generation + local OpenMontage for post-production (FFmpeg composition, subtitle burn-in, audio mixing, color grading).
+
+Do not claim the environment can do something the inspected setup does not support.
+
+---
+
+### STEP 9 — Execute or hand off
+
+**Local-fork mode:** Direct the agent to execute the pipeline:
+```
+research -> proposal -> script -> scene_plan -> assets -> edit -> compose
+```
+Each stage follows its pipeline stage director skill in `skills/pipelines/`.
+
+**Agent-only / hybrid mode:** Produce the complete handoff package so the user or a downstream agent can execute:
+- All production artifacts from Step 7
+- CMS node execution instructions (which nodes to run, with what inputs)
+- Post-production instructions (composition, audio, subtitles)
+
+---
+
+### STEP 10 — Log the deliverable
+
+Outputs must be saved under:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+Append a deliverable line in the active brand kit:
+
+```text
+- YYYY-MM-DD | OpenMontage Video Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
+```
+
+---
+
+## CRITICAL RULES
+
+| Rule | Meaning |
+|---|---|
+| Env gate must pass first | No `.env` or no provider = check CMS nodes or zero-key mode |
+| Read `skills.md` first | No memory-only operation |
+| Inspect the fork before planning | `tool_registry.py` and `pipeline_defs/` outrank assumptions |
+| Pick one primary pipeline | No mixed-pipeline output without explicit transition notes |
+| Provider choice uses 7-dimension scoring | Do not pick providers by name recognition alone |
+| CMS nodes are first-class providers | Treat hosted generation outputs as source assets for composition |
+| Pipeline stages are strict order | research -> proposal -> script -> scene_plan -> assets -> edit -> compose |
+| Budget governance applies | Estimate costs before execution, respect spend caps |
+| Outputs must be operational | Every file should help an operator execute immediately |
+
+---
+
+## REQUIRED OUTPUT ORDER
+
+1. `VideoProductionBrief`
+2. `PipelineSelectionBrief`
+3. `ProviderSelectionBrief`
+4. `ScenePlan`
+5. `PromptMatrix`
+6. `GenerationBatchPlan`
+7. `AssetTracking`
+8. `ReviewQAChecklist`
+9. `PlatformReadyExecutionHandoff`

package/assets/worker-kits/growthub-twenty-crm-v1/.env.example

@@ -0,0 +1,15 @@
+# Twenty CRM Worker Kit — Environment Config
+# Copy this file to .env and fill in your credentials.
+# Never commit .env to version control.
+
+# Required: Twenty API bearer token.
+# Generate from Twenty Settings > API > Tokens.
+TWENTY_API_TOKEN=your_twenty_api_token_here
+
+# Required: Twenty API base URL.
+# Use https://api.twenty.com for cloud, or http://localhost:3000 for local fork.
+TWENTY_API_URL=https://api.twenty.com
+
+# Optional: override local fork path used by setup scripts.
+# Default: ~/twenty
+TWENTY_FORK_PATH=~/twenty

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/
+```