@growthub/cli 0.3.53 → 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-postiz-social-v1/.env.example

@@ -0,0 +1,18 @@
+# Growthub Postiz Social Studio — Environment Config
+# Copy this file to .env and fill in your values.
+# Never commit .env to version control.
+
+# Optional override for your local Postiz fork path.
+# Default used by scripts is ~/postiz-app.
+# POSTIZ_FORK_PATH=/path/to/your/postiz-app
+
+# Base URL for the local Postiz API.
+POSTIZ_API_URL=http://localhost:3000
+
+# Required for scheduling manifest submission.
+# Find this in Postiz Settings > Workspace.
+POSTIZ_WORKSPACE_ID=your_postiz_workspace_id_here
+
+# Optional for AI-enhanced caption generation in agent/hybrid mode.
+# Get one at https://console.anthropic.com
+ANTHROPIC_API_KEY=your_anthropic_key_here

package/assets/worker-kits/growthub-postiz-social-v1/QUICKSTART.md

@@ -0,0 +1,136 @@
+# Growthub Postiz Social Media Studio — Quickstart
+
+**Kit:** `growthub-postiz-social-v1`
+**Worker:** `postiz-social-operator`
+**Platform:** [Postiz](https://github.com/gitroomhq/postiz-app)
+
+---
+
+## What This Kit Does
+
+The Growthub Postiz Social Media Studio is a self-contained AI agent environment for planning, drafting, scheduling, and analyzing social media campaigns using the Postiz open-source platform. It wraps the self-hosted Postiz workspace to produce:
+
+- Social campaign briefs (objective, platforms, audience, KPIs)
+- 30/60/90-day content calendars with theme pillars
+- Platform publishing plans for 28+ social networks
+- Caption copy decks with A/B/C variants per post
+- BullMQ-compatible scheduling manifests for Postiz API
+- Analytics briefings (engagement, reach, growth signals)
+- Client-ready proposals with platform mix and ROI projections
+
+Supported platforms include: Instagram, LinkedIn, TikTok, X/Twitter, YouTube, Pinterest, Reddit, Bluesky, Facebook, Mastodon, Slack, Telegram, and 16+ more. See `docs/platform-coverage.md` for the full list.
+
+---
+
+## Setup — 6 Steps
+
+### Step 1 — Point Your Working Directory
+
+Export this kit to a local folder and point Claude Code's Working Directory at the kit root. All paths in the kit are relative to the kit root.
+
+### Step 2 — Copy the Environment File
+
+```bash
+cp .env.example .env
+```
+
+Fill in your Postiz workspace credentials and API endpoint. No platform OAuth tokens are stored in this kit — those live inside the Postiz admin UI.
+
+### Step 3 — Verify the Environment
+
+```bash
+node setup/verify-env.mjs
+```
+
+This checks:
+- Whether the Postiz fork is cloned at `POSTIZ_FORK_PATH` (default: `~/postiz-app`)
+- Whether the Postiz API is reachable on port 3000
+- Whether `ANTHROPIC_API_KEY` is valid format (if set for AI caption enhancement)
+- No OAuth tokens are validated here — those are managed inside Postiz
+
+### Step 4 — Check Dependencies
+
+```bash
+bash setup/check-deps.sh
+```
+
+Verifies that `node`, `docker`, `docker compose`, and `git` are available. Checks Node.js version (18+ required). Checks Docker engine is running.
+
+### Step 5 — Clone and Start the Postiz Workspace (Local-Fork Mode Only)
+
+```bash
+bash setup/clone-fork.sh
+```
+
+This clones `postiz-app` to `~/postiz-app` (or `POSTIZ_FORK_PATH` if set), runs `docker compose up -d` to start Redis, PostgreSQL, and the Postiz API, and waits for the API healthcheck to pass.
+
+Skip this step if you are using **agent-only mode** — the operator can plan campaigns, draft captions, and produce content calendars without a running Postiz instance.
+
+### Step 6 — Start a Session
+
+Open Claude Code, set the Working Directory to this kit root, and start your session. The operator will guide you through the 10-step workflow.
+
+---
+
+## Execution Modes
+
+| Mode | Requirements | Use When |
+|---|---|---|
+| `local-fork` | Node 18+, Docker, Postiz running | You want to schedule posts via the Postiz API and use multi-workspace features |
+| `agent-only` | Nothing — Claude handles everything | You need campaign planning, content calendars, and caption drafts without a running instance |
+| `hybrid` | ANTHROPIC_API_KEY + Postiz running | Best of both — agent reasoning with live Postiz API scheduling |
+
+---
+
+## First Run
+
+1. Tell the operator: **"Plan a 30-day Instagram + LinkedIn campaign for [your brand]"**
+2. The operator will ask 4 clarifying questions (client, platforms, objective, cadence)
+3. The operator runs the 10-step workflow and produces all campaign artifacts
+4. Output is saved to `output/<client-slug>/<project-slug>/`
+
+---
+
+## New Client Setup
+
+See `brands/NEW-CLIENT.md` for instructions on adding a new client brand kit.
+
+Quick version:
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+# Then fill in the fields in the new file
+```
+
+---
+
+## Available Commands
+
+Tell the operator which you need:
+
+| Command | What It Does |
+|---|---|
+| `/postiz campaign` | Full campaign brief + content calendar + publishing plan |
+| `/postiz calendar` | Content calendar only — existing brief provided |
+| `/postiz captions` | Caption copy deck for a specific platform or batch |
+| `/postiz schedule` | Generate BullMQ-compatible scheduling manifest |
+| `/postiz analytics` | Analytics briefing from Postiz API data or provided metrics |
+| `/postiz proposal` | Client-ready proposal with platform mix and ROI projection |
+| `/postiz platforms` | Platform coverage report for a specific client context |
+| `/postiz quick` | 30-second campaign snapshot for a domain or brand |
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `workers/postiz-social-operator/CLAUDE.md` | Agent operating instructions (start here) |
+| `skills.md` | Full methodology — read at every session |
+| `brands/_template/brand-kit.md` | Blank brand kit template |
+| `brands/growthub/brand-kit.md` | Growthub reference example |
+| `output/README.md` | Output directory structure and naming |
+| `docs/postiz-fork-integration.md` | How this kit integrates with Postiz |
+| `docs/platform-coverage.md` | All 28+ supported platforms with format specs |
+| `docs/ai-caption-layer.md` | AI caption generation methodology |
+| `docs/bullmq-queue-layer.md` | Scheduling manifest format for Postiz API |
+| `validation-checklist.md` | Pre-session checklist |

package/assets/worker-kits/growthub-postiz-social-v1/brands/NEW-CLIENT.md

@@ -0,0 +1,67 @@
+# Adding a New Client
+
+This guide explains how to create a brand kit for a new client in the Postiz Social Media Studio.
+
+---
+
+## Steps
+
+### 1. Copy the Template
+
+```bash
+cp brands/_template/brand-kit.md brands/<client-slug>/brand-kit.md
+```
+
+Replace `<client-slug>` with a lowercase, hyphenated version of the client name. Examples:
+- "Urban Cycle" → `urban-cycle`
+- "Acme SaaS Corp" → `acme-saas`
+- "The Bloom Studio" → `bloom-studio`
+
+### 2. Fill in the Brand Kit
+
+Open the new file and fill in every section:
+- **Client Identity** — name, slug, industry, website
+- **Social Media Presence** — existing accounts, follower counts, current activity level
+- **Target Audience** — primary and secondary audience profiles
+- **Campaign Objectives** — metrics, targets, and timelines
+- **Brand Voice** — tone, personality, approved/blocked words, emoji usage
+- **Content Theme Pillars** — 3–5 recurring themes with platform assignments
+- **Competitor Reference Accounts** — 2–3 accounts to reference for format benchmarking
+- **Agency Context** — engagement stage, retainer, reporting cadence
+
+### 3. Verify the Brand Kit
+
+Before using the brand kit in a session, confirm:
+- [ ] `client-slug` in the filename matches the `Client Slug` field in the kit
+- [ ] At least one platform is listed in `Social Media Presence`
+- [ ] At least one campaign objective has a measurable target
+- [ ] Brand voice section is complete — no empty `[fill in]` placeholders
+- [ ] At least 3 content theme pillars are defined
+
+### 4. Tell the Operator
+
+Start your Claude Code session and say:
+> "Load the brand kit for [client-name] and begin a [campaign objective] campaign."
+
+The operator will read the brand kit and ask the 4-question gate before producing any output.
+
+---
+
+## Brand Kit Naming Rules
+
+| Rule | Correct | Incorrect |
+|---|---|---|
+| Directory name is lowercase kebab-case | `brands/urban-cycle/` | `brands/UrbanCycle/` |
+| Filename is always `brand-kit.md` | `brands/urban-cycle/brand-kit.md` | `brands/urban-cycle/UrbanCycle.md` |
+| Slug contains no spaces | `acme-saas` | `acme saas` |
+| Slug contains no special chars | `bloom-studio` | `bloom/studio` |
+
+---
+
+## Note on Public Brand Kits
+
+Brand kits are **not included in kit exports by default**. The only brand kits included in exports are:
+- `brands/_template/brand-kit.md` — the blank template
+- `brands/growthub/brand-kit.md` — the public reference example
+
+Client brand kits you create live in your local kit installation only. They are not bundled into the export zip or submitted to any external service.

package/assets/worker-kits/growthub-postiz-social-v1/brands/_template/brand-kit.md

@@ -0,0 +1,120 @@
+# Brand Kit — [Client Name]
+
+<!-- Replace [Client Name] with the actual client name and rename this file to brands/<client-slug>/brand-kit.md -->
+
+---
+
+## Client Identity
+
+| Field | Value |
+|---|---|
+| Client Name | [Client Name] |
+| Client Slug | [client-slug] |
+| Industry | [e.g., SaaS / E-commerce / Hospitality / Fintech] |
+| Website | [https://...] |
+| Primary Contact | [Name, email] |
+
+---
+
+## Social Media Presence
+
+| Platform | Handle | Followers | Current Status |
+|---|---|---|---|
+| Instagram | [@handle] | [N] | [Active / Inactive / New] |
+| LinkedIn | [company page URL] | [N followers] | [Active / Inactive] |
+| TikTok | [@handle] | [N] | [Active / Inactive] |
+| X/Twitter | [@handle] | [N] | [Active / Inactive] |
+| [Other] | [handle] | [N] | [Active / Inactive] |
+
+---
+
+## Target Audience
+
+### Primary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | [e.g., 25–40] |
+| Gender | [e.g., 55% female, 45% male] |
+| Location | [e.g., North America, English-speaking markets] |
+| Interests | [e.g., entrepreneurship, productivity, design] |
+| Pain Points | [e.g., too many disconnected tools, manual social media posting] |
+| Content Preferences | [e.g., educational how-tos, success stories, data-driven insights] |
+
+### Secondary Audience
+
+| Attribute | Description |
+|---|---|
+| Age Range | [e.g., 18–25] |
+| Interests | [e.g., tech, side projects] |
+| Platform | [e.g., TikTok, Reddit] |
+
+---
+
+## Campaign Objectives
+
+| Objective | Metric | Target | Timeline |
+|---|---|---|---|
+| [Brand awareness] | [Impressions] | [50,000/month] | [Q2 2026] |
+| [Lead generation] | [Link clicks] | [200/month] | [Q2 2026] |
+| [Community growth] | [Follower growth] | [+500] | [Q2 2026] |
+
+---
+
+## Brand Voice
+
+| Attribute | Spec |
+|---|---|
+| Tone | [e.g., Professional but approachable. Data-driven without being dry. Never salesy.] |
+| Personality | [e.g., Smart, helpful, occasionally witty] |
+| Words to Use | [e.g., "build", "grow", "automate", "team", "results"] |
+| Words to Avoid | [e.g., "hack", "guru", "crush it", "cheap", "amazing"] |
+| Emoji Usage | [e.g., Minimal on LinkedIn; moderate on Instagram; more on TikTok] |
+| CTA Style | [e.g., Direct action verbs: "Start today", "Learn more", "Join the team"] |
+
+---
+
+## Content Theme Pillars
+
+| Pillar | Description | Platforms | % of Calendar |
+|---|---|---|---|
+| [Industry Insights] | [What we know that others don't — data, trends, analysis] | [All] | [40%] |
+| [Product Value] | [Feature spotlights, use cases, ROI stories] | [LinkedIn, Instagram] | [30%] |
+| [Social Proof] | [Customer testimonials, case studies, results] | [All] | [20%] |
+| [Community] | [Q&A, behind the scenes, team moments] | [Instagram, TikTok] | [10%] |
+
+---
+
+## Competitor Reference Accounts
+
+| Platform | Account | Why Reference |
+|---|---|---|
+| [Instagram] | [@competitor] | [Strong visual brand, good engagement format] |
+| [LinkedIn] | [competitor company page] | [Industry leader, consistent posting cadence] |
+
+---
+
+## Agency Context
+
+| Field | Value |
+|---|---|
+| Engagement Stage | [Prospect / Onboarding / Retained] |
+| Monthly Retainer | [e.g., $X,XXX/month or "not established"] |
+| Campaign Budget | [e.g., $X,XXX / campaign or "TBD"] |
+| Reporting Cadence | [e.g., Monthly analytics brief] |
+
+---
+
+## CRM Notes
+
+<!-- Internal notes for agency context. Not included in client-facing outputs. -->
+
+[Add internal notes here: key contacts, relationship history, upsell opportunities, account health signals]
+
+---
+
+## DELIVERABLES LOG
+
+<!-- Append a line for each completed deliverable. -->
+
+<!-- - YYYY-MM-DD | Social Media Campaign Package v1 — [Project Name] | output/<client-slug>/<project-slug>/ -->