@growthub/cli 0.3.38 → 0.3.39

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/skills.md

@@ -0,0 +1,257 @@
+# Open Higgsfield Studio Operator — Master Skill Doc
+
+**Source of truth for methodology. Read this file completely before beginning any task.**
+
+---
+
+## QUICK REFERENCE TABLE
+
+| Resource | Path |
+|---|---|
+| Agent operating law | `workers/open-higgsfield-studio-operator/CLAUDE.md` |
+| Brand kit template | `brands/_template/brand-kit.md` |
+| Growthub example brand kit | `brands/growthub/brand-kit.md` |
+| Output contract | `output-standards.md` |
+| Runtime assumptions | `runtime-assumptions.md` |
+| Fork integration notes | `docs/open-higgsfield-fork-integration.md` |
+| Provider adapter layer | `docs/provider-adapter-layer.md` |
+| Visual campaign brief | `templates/visual-campaign-brief.md` |
+| Studio selection brief | `templates/studio-selection-brief.md` |
+| Model selection recommendation | `templates/model-selection-recommendation.md` |
+| Shot plan | `templates/shot-plan.md` |
+| Prompt matrix | `templates/prompt-matrix.md` |
+| Generation batch plan | `templates/generation-batch-plan.md` |
+| Asset tracking | `templates/asset-tracking.md` |
+| Review QA checklist | `templates/review-qa-checklist.md` |
+| Execution handoff | `templates/platform-ready-execution-handoff.md` |
+| Frame analysis primitive | `templates/frame-analysis.md` |
+| Image prompt template | `templates/prompt-templates/image-generation.md` |
+| Video prompt template | `templates/prompt-templates/video-generation.md` |
+| Lip sync prompt template | `templates/prompt-templates/lip-sync-generation.md` |
+| Cinema prompt template | `templates/prompt-templates/cinema-generation.md` |
+| Sample brief | `examples/visual-campaign-brief-sample.md` |
+| Sample shot plan | `examples/shot-plan-sample.md` |
+| Sample prompt matrix | `examples/prompt-matrix-sample.md` |
+| Sample handoff | `examples/platform-ready-handoff-sample.md` |
+
+---
+
+## STEP 0 — BEFORE ANY TASK, ANSWER THESE QUESTIONS
+
+Before producing anything, confirm:
+
+1. Which brand or client is this for?
+2. What is the output objective?
+3. Which studio is the likely match: image, video, lip sync, or cinema?
+4. What assets already exist locally?
+5. What execution surface is active: browser, desktop, or local fork?
+6. Is the fork repo available for inspection?
+
+If any of these are unknown after the 3-question gate, stop and ask.
+
+---
+
+## STEP 1 — LOAD THE BRAND KIT
+
+Read `brands/<client-slug>/brand-kit.md` if it exists. Otherwise start from `brands/_template/brand-kit.md`.
+
+Extract:
+- audience and offer
+- visual identity
+- brand-safe language
+- emotional outcome
+- approved phrasing
+- no-go claims
+- asset library references
+
+This kit inherits the strongest brand-kit primitives from the existing Growthub creative and email kits: identity, audience, positioning, messaging guardrails, approved phrases, CTA language, and deliverables logging.
+
+---
+
+## STEP 2 — CHECK THE WORKING SUBSTRATE
+
+If the user has a local Open Higgsfield fork, inspect it before planning.
+
+### Source-of-truth file order
+
+1. `README.md`
+2. `packages/studio/src/models.js`
+3. `packages/studio/src/muapi.js`
+4. `packages/studio/src/components/ImageStudio.jsx`
+5. `packages/studio/src/components/VideoStudio.jsx`
+6. `packages/studio/src/components/LipSyncStudio.jsx`
+7. `packages/studio/src/components/CinemaStudio.jsx`
+8. `components/StandaloneShell.js`
+9. `components/ApiKeyModal.js`
+10. `electron/`
+
+### What to verify
+
+- Which studios are exposed
+- Which models are currently active
+- What parameters each model expects
+- Whether prompt is required or optional
+- Which media inputs are accepted
+- How upload history is stored and reused
+- How generation history is stored and revisited
+- Whether desktop behavior diverges from browser behavior
+
+If the fork cannot be inspected, use the frozen upstream assumptions in this kit and label the output `assumption-based`.
+
+---
+
+## STEP 3 — STUDIO SELECTION LOGIC
+
+Choose the narrowest studio that matches the real job.
+
+| Studio | Use when | Avoid when |
+|---|---|---|
+| `image` | still concepts, key art, reference frame generation, look dev | motion or audio-driven output is required |
+| `video` | text-to-video or image-to-video motion clips are the target | precise talking-head lip sync is the real need |
+| `lip-sync` | face performance must follow audio | cinematic camera grammar matters more than mouth sync |
+| `cinema` | shot design, lensing, focal length, aperture, and visual language are central | a basic output can be handled by image or video mode alone |
+
+Default to one primary studio. Secondary studios can appear only as fallbacks.
+
+---
+
+## STEP 4 — MODEL SELECTION LOGIC
+
+Open Higgsfield AI uses model and endpoint mappings as the operational core. Selection must be tied to actual capabilities.
+
+For every recommendation, document:
+- studio mode
+- model class
+- endpoint assumption
+- prompt requirement
+- reference-image count
+- aspect ratio options
+- duration or resolution options
+- likely failure modes
+- fallback model
+
+### Required model-selection discipline
+
+1. Prefer the local fork's `models.js` over memory.
+2. Match input mode first, then aesthetic.
+3. Avoid recommending models that require assets the user does not have.
+4. For lip sync, distinguish portrait-image mode from video mode.
+5. For cinema, translate camera intent into prompt modifiers and control selections.
+
+---
+
+## STEP 5 — PROMPT PLANNING LOGIC
+
+Prompt work is not free-form writing. It is production planning.
+
+Every prompt set must specify:
+- objective
+- subject
+- environment
+- action
+- camera language
+- composition
+- lighting
+- texture / material detail
+- motion behavior where relevant
+- negative prompt or exclusion language when supported
+- output constraints
+
+### Mode-specific rules
+
+- `image`: prioritize subject clarity, composition, style lock, and reference usage
+- `video`: prioritize motion verb, start state, camera move, continuity, and duration
+- `lip-sync`: prioritize performance intent, facial framing, audio sync assumptions, and artifact avoidance
+- `cinema`: prioritize lens, focal length, aperture, movement grammar, blocking, and scene beat
+
+Use the frozen prompt templates. Do not invent a new schema unless the use case truly does not fit.
+
+---
+
+## STEP 6 — SHOT PLANNING LOGIC
+
+Shot plans convert abstract goals into executable batches.
+
+Each shot row must include:
+- shot id
+- narrative purpose
+- studio mode
+- model target
+- input assets
+- camera intent
+- prompt key
+- duration / ratio / resolution
+- pass count
+- review note
+
+### When to run frame extraction
+
+If the user provides a local reference mp4, use `templates/frame-analysis.md` before finalizing the shot plan.
+
+This kit intentionally reuses the proven frame-analysis primitive from the creative strategist workflow:
+- extract frames locally with `ffmpeg`
+- identify scene boundaries
+- record composition, motion, text rhythm, and pacing
+- convert those observations into shot rows and prompt constraints
+
+---
+
+## STEP 7 — GENERATION BATCH LOGIC
+
+Every batch plan must group generations by:
+- studio mode
+- model
+- asset dependency
+- aspect ratio
+- duration
+- priority
+
+This matters because Open Higgsfield AI generation is asynchronous and provider-backed. The operator needs a clear submit order and a clear poll / review loop.
+
+---
+
+## STEP 8 — PROVIDER ADAPTER LOGIC
+
+Muapi is the reference adapter, not the only forever adapter.
+
+All provider assumptions must state:
+- provider name
+- auth header contract
+- submit endpoint pattern
+- poll endpoint pattern
+- upload flow
+- result handling
+- fallback behavior when a model is unavailable
+
+Keep adapter language abstract enough that a second provider can fit later without rewriting the kit.
+
+---
+
+## STEP 9 — OUTPUT ORDER
+
+Produce artifacts in this order:
+
+1. Visual campaign brief
+2. Studio selection brief
+3. Model selection recommendation
+4. Shot plan
+5. Prompt matrix
+6. Generation batch plan
+7. Asset tracking
+8. Review QA checklist
+9. Platform-ready execution handoff
+
+---
+
+## STEP 10 — QUALITY BAR
+
+Good output looks like this:
+
+- grounded in inspected repo files or clearly labeled assumptions
+- one primary studio choice with reasoning
+- model recommendation tied to endpoint constraints
+- prompts ready to paste into Open Higgsfield AI
+- shot plan rows mapped to actual inputs and outputs
+- generation batches sequenced for async submit/poll workflows
+- handoff notes clear enough for browser or desktop execution
+- review checklist specific enough to catch model drift, framing errors, lip-sync mismatch, and prompt leakage

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/asset-tracking.md

@@ -0,0 +1,5 @@
+# Asset Tracking Template
+
+| Asset ID | Type | Source | Local Path / URL | Reuse Status | Upload Needed | Owner | Notes |
+|---|---|---|---|---|---|---|---|
+| A01 | | | | | | | |

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/frame-analysis.md

@@ -0,0 +1,24 @@
+# Frame Analysis Primitive
+
+Use this when the operator has a local reference video and the shot plan should mirror proven pacing or framing.
+
+## Extraction
+
+```bash
+mkdir -p /tmp/open_higgsfield_frames
+ffmpeg -i "/path/to/reference.mp4" -vf fps=1/2 /tmp/open_higgsfield_frames/frame_%04d.jpg
+```
+
+## Record per frame cluster
+
+| Cluster | Approx time | What changes | Composition | Motion | Text rhythm | Notes |
+|---|---|---|---|---|---|---|
+| C01 | | | | | | |
+
+## Convert analysis into planning
+
+1. identify shot boundaries
+2. name the narrative function of each segment
+3. map each segment to a studio and model
+4. convert visual observations into prompt controls
+5. add continuity rules to the shot plan

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/generation-batch-plan.md

@@ -0,0 +1,7 @@
+# Generation Batch Plan Template
+
+| Batch ID | Priority | Studio | Model | Inputs | Output Target | Submit Order | Polling Note | Retry Rule |
+|---|---|---|---|---|---|---|---|---|
+| B01 | | | | | | | | |
+
+## Batch Strategy

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/model-selection-recommendation.md

@@ -0,0 +1,23 @@
+# Model Selection Recommendation Template
+
+## Primary Recommendation
+
+| Field | Value |
+|---|---|
+| Studio mode | |
+| Model | |
+| Endpoint | |
+| Prompt required | |
+| Inputs required | |
+| Controls | |
+| Reason | |
+
+## Fallback Recommendation
+
+| Field | Value |
+|---|---|
+| Model | |
+| Endpoint | |
+| Reason for fallback | |
+
+## Constraint Notes

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/platform-ready-execution-handoff.md

@@ -0,0 +1,17 @@
+# Platform-Ready Execution Handoff Template
+
+## Runtime Mode
+
+## Repo Inspection Summary
+
+## Provider Adapter Assumptions
+
+## Execution Steps
+
+1.
+2.
+3.
+
+## Expected Outputs
+
+## Open Questions

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/prompt-matrix.md

@@ -0,0 +1,7 @@
+# Prompt Matrix Template
+
+| Prompt ID | Shot / Output | Studio | Model | Base Prompt | Variation Prompt | Negative / Exclusions | Controls | Assets |
+|---|---|---|---|---|---|---|---|---|
+| P01 | | | | | | | | |
+
+## Prompt Notes

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/prompt-templates/cinema-generation.md

@@ -0,0 +1,16 @@
+# Cinema Generation Prompt Template
+
+## Objective
+
+## Prompt
+
+`[subject], [blocking], [camera type], [lens], [focal length], [aperture], [camera move], [lighting], [mood], [set detail]`
+
+## Control Notes
+
+- camera:
+- lens:
+- focal length:
+- aperture:
+
+## Exclusions

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/prompt-templates/image-generation.md

@@ -0,0 +1,11 @@
+# Image Generation Prompt Template
+
+## Objective
+
+## Prompt
+
+`[subject], [action or pose], [environment], [composition], [lighting], [texture], [style], [brand cues]`
+
+## Exclusions
+
+## Recommended Controls

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/prompt-templates/lip-sync-generation.md

@@ -0,0 +1,14 @@
+# Lip Sync Generation Prompt Template
+
+## Objective
+
+## Prompt
+
+`[speaker framing], [performance intent], [head motion], [emotion], [background], [stability constraints]`
+
+## Required Inputs
+
+- portrait or source video
+- audio file
+
+## Exclusions

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/prompt-templates/video-generation.md

@@ -0,0 +1,11 @@
+# Video Generation Prompt Template
+
+## Objective
+
+## Prompt
+
+`[subject], [starting state], [motion verb], [camera move], [environment], [lighting], [tempo], [ending beat]`
+
+## Exclusions
+
+## Recommended Controls

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/review-qa-checklist.md

@@ -0,0 +1,26 @@
+# Review QA Checklist Template
+
+## Creative Review
+
+- [ ] Visual direction matches brief
+- [ ] Prompt intent is preserved across variants
+- [ ] No off-brand styling
+
+## Technical Review
+
+- [ ] Correct studio and model used
+- [ ] Aspect ratio / duration / resolution match plan
+- [ ] Inputs and references were attached correctly
+
+## Studio-Specific Review
+
+- [ ] Image: composition and subject integrity hold
+- [ ] Video: motion and continuity hold
+- [ ] Lip Sync: mouth sync and facial stability hold
+- [ ] Cinema: lensing and camera grammar hold
+
+## Sign-off
+
+- Reviewer:
+- Date:
+- Status:

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/shot-plan.md

@@ -0,0 +1,11 @@
+# Shot Plan Template
+
+| Shot ID | Beat | Studio | Model | Assets | Camera Intent | Prompt Key | Ratio / Duration | Passes | Review Note |
+|---|---|---|---|---|---|---|---|---|---|
+| S01 | | | | | | | | | |
+
+## Arc Notes
+
+## Asset Dependencies
+
+## Review Gates

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/studio-selection-brief.md

@@ -0,0 +1,18 @@
+# Studio Selection Brief Template
+
+## Requested Outcome
+
+## Recommended Studio
+
+| Option | Fit | Notes |
+|---|---|---|
+| Image | | |
+| Video | | |
+| Lip Sync | | |
+| Cinema | | |
+
+## Why the Winning Studio Fits
+
+## Required Inputs
+
+## Fallback Path

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/templates/visual-campaign-brief.md

@@ -0,0 +1,24 @@
+# Visual Campaign Brief Template
+
+## Project Overview
+
+| Field | Value |
+|---|---|
+| Client | |
+| Project | |
+| Objective | |
+| Primary platform | |
+| Runtime mode | |
+| Due date | |
+
+## Audience and Offer
+
+## Brand and Visual Rules
+
+## Existing Assets
+
+## Studio Hypothesis
+
+## Success Criteria
+
+## Output Package

package/assets/worker-kits/growthub-open-higgsfield-studio-v1/validation-checklist.md

@@ -0,0 +1,49 @@
+# Validation Checklist — Open Higgsfield Studio v1
+
+Use this checklist before considering a package complete.
+
+---
+
+## PRE-SESSION CHECKLIST (operator runs before starting the agent)
+
+- [ ] Growthub local Working Directory is pointed at this folder (or Claude Code as alternative)
+- [ ] `.env` exists (copy from `.env.example` if not)
+- [ ] `MUAPI_API_KEY` is set in `.env` (not placeholder value)
+- [ ] `node setup/verify-env.mjs` exits 0 (key is valid and API is reachable)
+- [ ] `bash setup/check-deps.sh` passes (local-fork mode only)
+- [ ] Local fork is running at `http://localhost:3001` OR execution mode is `browser-hosted` or `desktop-app`
+- [ ] `output/` directory exists (auto-created by agent on first write)
+- [ ] Active brand kit exists: `brands/<client-slug>/brand-kit.md` OR using `brands/growthub/brand-kit.md`
+
+---
+
+## KIT VALIDATION
+
+- [ ] `kit.json` exists and every `frozenAssetPaths` entry exists
+- [ ] bundle manifest matches kit id and worker id
+- [ ] entrypoint path exists
+- [ ] example brand is public-safe
+- [ ] docs, templates, and examples are all self-contained in this folder
+
+## METHODOLOGY VALIDATION
+
+- [ ] `skills.md` defines strict workflow order
+- [ ] entrypoint points back to `skills.md`
+- [ ] runtime assumptions, provider adapter notes, and output standards exist
+- [ ] visual-production-specific templates exist for all four studios
+- [ ] frame-analysis primitive is documented
+
+## OPERATIONAL VALIDATION
+
+- [ ] local fork inspection instructions exist
+- [ ] browser-hosted flow is documented
+- [ ] desktop-app flow is documented
+- [ ] Muapi auth, submit, poll, and result assumptions are documented
+- [ ] fallback provider extension path is documented
+
+## OUTPUT VALIDATION
+
+- [ ] required output categories all have templates
+- [ ] example files demonstrate the expected contract
+- [ ] naming convention is explicit
+- [ ] review and QA gates are explicit