@growthub/cli 0.8.1 → 0.8.2

package/assets/worker-kits/growthub-creative-video-pipeline-v1/templates/pipeline-brief.md

@@ -0,0 +1,129 @@
+# Pipeline Brief — [CLIENT NAME] / [CAMPAIGN NAME]
+> Stage 1 output. Write this file to `output/<client-slug>/<project-slug>/brief/pipeline-brief.md`.
+> Pull all brand values from `brands/<client-slug>/brand-kit.md`. Do not invent brand detail.
+
+---
+
+## BRAND CONSTRAINTS
+
+> ⚠️ This ad must NEVER:
+> - [Pull from brand-kit.md `messaging_guardrails`]
+> - [Pull from brand-kit.md `do_not_attract`]
+
+---
+
+## BRIEF OVERVIEW
+
+| Field | Value |
+|---|---|
+| Client | |
+| Campaign | |
+| Date | |
+| Format | (UGC / AI Avatar / Explainer / Performance) |
+| Length | (seconds) |
+| Primary Goal | (Conversion / Awareness / Education) |
+| Hook Variations | (default 5 — A through E) |
+| Scene Count | |
+| Aspect Ratios | (9:16 + 1:1 minimum) |
+| Captions | ON |
+| CTA Offer | |
+| Landing Page | |
+
+---
+
+## SCENE STRUCTURE
+
+| Scene | Name | Timecode | Beat |
+|---|---|---|---|
+| 1 | Hook | 0:00–0:05 | N hook variations A–E |
+| 2 | Problem | 0:05–0:15 | Consistent across all hooks |
+| 3 | Solution | 0:15–0:25 | Consistent across all hooks |
+| N | CTA | 0:25–0:30 | Consistent across all hooks |
+
+---
+
+## SCENE 1 — HOOK (N VARIATIONS)
+
+> All variations share the same Scene 2–N structure. Only Scene 1 differs.
+
+### Hook A — [Type]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Hook B — [Type]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Hook C — [Type]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Hook D — [Type]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Hook E — [Type]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+---
+
+## SCENES 2–N (CONSISTENT ACROSS ALL HOOK VARIATIONS)
+
+### Scene 2 — [Name]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Scene 3 — [Name]
+**Visual:** 
+**On-Screen Text:** 
+**VO:** 
+
+### Scene N — CTA
+**Visual:** 
+**On-Screen Text:** 
+**VO:** `[CTA text from brand kit]`
+
+---
+
+## EDITING GUIDELINES
+
+- **Pacing:** Cut every ~3s unless specified otherwise
+- **Music:** [direction]
+- **Captions:** ON — match VO rhythm
+- **Color grade:** [direction]
+- **Aspect ratios:** 9:16 primary, 1:1 secondary
+- **NO list:** [pull from brand-kit.md messaging_guardrails]
+
+---
+
+## APPENDIX — AI GENERATION PROMPTS (OPTIONAL)
+
+> These prompts feed Stage 2 of the pipeline. Each prompt maps to one scene / one clip.
+> Keep prompts in this appendix only. Never inline in scene blocks above.
+
+### Video prompt — Scene 1 (Hook A)
+
+```
+[Scene description for video-generation CMS node]
+Brand: [brand name], style: [style from brand kit], no text overlays,
+[aspect ratio], [duration]s
+```
+
+### Video prompt — Scene 2
+
+```
+[Scene description]
+```
+
+### Image prompt — [Scene N background / reference]
+
+```
+[Image description]
+```

package/assets/worker-kits/growthub-creative-video-pipeline-v1/templates/project.md

@@ -0,0 +1,68 @@
+---
+# .growthub-fork/project.md — session memory primitive (v1)
+#
+# Seeded by `growthub kit fork register` from this template.
+# Replaceable tokens: {{KIT_ID}} {{FORK_ID}} {{STARTED_AT}} {{SOURCE}} {{SOURCE_REF}}
+
+kitId: "{{KIT_ID}}"
+forkId: "{{FORK_ID}}"
+startedAt: "{{STARTED_AT}}"
+source: "{{SOURCE}}"
+sourceRef: "{{SOURCE_REF}}"
+skillManifestVersion: 1
+approvals: []
+selfEvalHistory: []
+subSkillRuns: []
+
+# Pipeline state (update after each stage)
+pipelineState:
+  stage1Brief:
+    status: pending       # pending | in_progress | complete
+    clientSlug: ""
+    projectSlug: ""
+    briefPath: ""
+    sceneCount: 0
+    hookVariations: 0
+    completedAt: ""
+  stage2Generative:
+    status: pending       # pending | in_progress | complete
+    adapter: ""           # growthub-pipeline | byo-api-key
+    provider: ""
+    artifactCount: 0
+    manifestPath: ""
+    completedAt: ""
+  stage3Edit:
+    status: pending       # pending | in_progress | complete
+    videoUseForkPath: ""
+    finalVideoPath: ""
+    durationTarget: ""
+    qaPass: false
+    completedAt: ""
+---
+
+# Project journal — fork `{{FORK_ID}}`
+
+Baseline primitive: `{{KIT_ID}}`. Seeded at `{{STARTED_AT}}` from `{{SOURCE}}` (`{{SOURCE_REF}}`).
+
+## How to use this file
+
+1. **Session start.** Read the last 3 entries below + tail 20 events in `.growthub-fork/trace.jsonl`. Update `pipelineState` to reflect actual completion.
+2. **Stage completion.** Record a dated entry in "Session log" with: stage, client, project, key paths, self-eval outcome.
+3. **Material change.** Append a dated bullet here AND a typed event to `trace.jsonl`.
+4. **Self-eval boundary.** Append to `selfEvalHistory`: `attempt`, `criteria`, `outcome`, `notes`.
+5. **Sub-skill spawn.** Append to `subSkillRuns`: `subSkill`, `startedAt`, `result`.
+
+## Session log
+
+<!-- Append entries below, newest at the bottom.
+
+### YYYY-MM-DD HH:mm UTC · creative-video-pipeline-operator
+- **Plan.** What you intend to do this session.
+- **Stage.** Which stage (1/2/3) and what sub-task.
+- **Changes.** What you actually did (each must correspond to a trace event).
+- **Outcome.** Pass / fail / parked. Reference the selfEval criteria checked.
+- **Next.** What the next session should pick up.
+
+-->
+
+_No sessions recorded yet. This block is populated as the fork is operated._

package/assets/worker-kits/growthub-creative-video-pipeline-v1/templates/self-eval.md

@@ -0,0 +1,67 @@
+# Self-evaluation template — v1 primitive (Growthub, capability-agnostic)
+
+A skill's `selfEval` contract declares **what good looks like** (`criteria[]`) and **the retry ceiling** (`maxRetries`). The agent drives the loop; this file is the pattern the agent follows at every unit of work.
+
+The contract is defined in `@growthub/api-contract/skills::SkillSelfEval` and is **capability-agnostic** — the same primitive applies to code edits, copy drafts, CRM rules, API payloads, asset renders, audit passes, and every other domain. The "unit of work" is the smallest reversible change the skill operates on; concrete boundaries are defined in the kit's own `skills.md` operator runbook, not here.
+
+## Loop
+
+```
+for attempt in 1..maxRetries:          # default maxRetries = 3
+  generate       — produce a proposal (whatever the skill produces)
+  apply          — materialise the proposal against the fork
+  self-evaluate  — for each criterion in skill.selfEval.criteria:
+                     check → pass / fail / needs-confirmation
+  record         — append to project.md (human) + trace.jsonl (machine)
+
+  if all criteria pass: break
+  if attempt == maxRetries: park with needs_confirmation note. Stop.
+```
+
+## What each attempt writes
+
+### Human row — append to `.growthub-fork/project.md` "Session log"
+
+```md
+### 2026-04-24 · creative-video-pipeline-operator
+- **Plan.** What you intend to do this unit of work.
+- **Changes.** Material change applied (must correspond to a trace event).
+- **Self-eval.** attempt 2/3 — criterion "<one of skill.selfEval.criteria>" ✗ (<note>). Retrying.
+- **Outcome.** retry-pending / pass / parked.
+- **Next.** What the next attempt (or next session) should pick up.
+```
+
+### Machine row — append to `.growthub-fork/trace.jsonl`
+
+```json
+{
+  "ts": "2026-04-24T00:00:00.000Z",
+  "forkId": "<fork-id>",
+  "kitId": "growthub-creative-video-pipeline-v1",
+  "type": "self_eval_recorded",
+  "summary": "attempt 2/3 failed on <criterion>",
+  "detail": {
+    "skill": "<skill-slug>",
+    "attempt": 2,
+    "maxRetries": 3,
+    "criterion": "<one of skill.selfEval.criteria>",
+    "outcome": "fail",
+    "notes": "<short explanation>"
+  }
+}
+```
+
+## Hard rules
+
+1. **Never exceed `maxRetries`.** At the ceiling, park with a `needs_confirmation` note and stop.
+2. **Record every attempt.** Even the first pass.
+3. **Keep `project.md` and `trace.jsonl` in sync.**
+4. **Preserve prior entries.** Append-only. Never rewrite history.
+
+## Kit-specific self-eval units
+
+| Stage | Unit of work |
+|---|---|
+| Stage 1 — Brief | Completed `pipeline-brief.md` for one creative concept |
+| Stage 2 — Generate | `manifest.json` with one artifact URL per scene |
+| Stage 3 — Edit | `final.mp4` exists, duration ±10% of target, QA pass |

package/assets/worker-kits/growthub-creative-video-pipeline-v1/validation-checklist.md

@@ -0,0 +1,52 @@
+# Validation Checklist — Creative Video Pipeline
+
+Run before calling the kit v1-ready or before a Vercel deployment.
+
+## Environment
+
+- [ ] `bash setup/check-deps.sh` passes (FFmpeg, Python 3, pip, git, node)
+- [ ] `node setup/verify-env.mjs` passes
+- [ ] `bash helpers/check-generative-adapter.sh` shows expected adapter and keys
+- [ ] `VIDEO_USE_HOME` resolves to an existing `video-use` clone
+
+## Growthub CLI (growthub-pipeline adapter)
+
+- [ ] `growthub auth whoami --json` returns authenticated user
+- [ ] `growthub kit list --family studio` includes `growthub-creative-video-pipeline-v1`
+- [ ] `growthub kit fork status <fork-id>` shows no unexpected drift
+
+## Stage 1 — Brief
+
+- [ ] Brand kit exists at `brands/<client-slug>/brand-kit.md`
+- [ ] `pipeline-brief.md` written to `output/<client>/<project>/brief/`
+- [ ] Brief contains: brand constraints box, scene table, hook variations A–E, editing guidelines
+- [ ] AI generation prompts in Appendix only (not inline in scene blocks)
+
+## Stage 2 — Generate
+
+- [ ] `output/<client>/<project>/generative/manifest.json` exists and is valid JSON
+- [ ] Each manifest entry has `id`, `type`, `provider`, `url`, `prompt`
+- [ ] No API keys appear in any artifact file
+- [ ] Artifact count matches scene count in brief
+
+## Stage 3 — Edit
+
+- [ ] `output/<client>/<project>/final/final.mp4` exists
+- [ ] Duration within ±10% of target from edit plan
+- [ ] Audio fades at segment boundaries (30 ms)
+- [ ] Subtitles applied last
+- [ ] No secrets in any output artifact
+
+## Local shell
+
+- [ ] `cd studio && npm install && npm run build` succeeds
+- [ ] `cd apps/creative-video-pipeline && npm install && npm run build` succeeds
+- [ ] Studio Vite shell renders pipeline stage status without errors
+- [ ] Next.js `/settings/keys` page renders adapter config
+
+## Governed primitives
+
+- [ ] `.growthub-fork/project.md` has entries for all completed stages
+- [ ] `.growthub-fork/trace.jsonl` has typed events for all material changes
+- [ ] `growthub skills validate` passes
+- [ ] `growthub skills list` shows this kit's SKILL.md tree

package/assets/worker-kits/growthub-creative-video-pipeline-v1/workers/creative-video-pipeline-operator/CLAUDE.md

@@ -0,0 +1,109 @@
+# Creative Video Pipeline Operator
+
+**Kit:** `growthub-creative-video-pipeline-v1`
+**Worker ID:** `creative-video-pipeline-operator`
+**Version:** `1.0.0`
+
+## Role
+
+You produce end-to-end video content: a brand-grounded creative brief (Stage 1), generative image/video assets via the growthub pipeline or BYOK provider (Stage 2), and a fully edited final video via the video-use fork (Stage 3). You maintain the governed workspace across all three stages — every material change lands in `project.md` and `trace.jsonl`.
+
+## Required startup
+
+1. Read `skills.md`.
+2. Read `runtime-assumptions.md`.
+3. Resolve workspace: `WORKSPACE="${CREATIVE_VIDEO_PIPELINE_HOME:-$HOME/creative-video-pipeline}"`.
+4. Verify environment: `bash setup/check-deps.sh && node setup/verify-env.mjs`.
+5. Check generative adapter: `bash helpers/check-generative-adapter.sh`.
+6. If `ADAPTER=growthub-pipeline`: confirm auth with `growthub auth whoami --json`.
+
+If setup checks fail, stop and return remediation only. Do not invent keys or hardcode paths.
+
+## Source of truth (read in this order)
+
+1. `.growthub-fork/project.md` — session memory
+2. `SKILL.md` — routing menu and selfEval criteria
+3. `skills.md` — full 3-stage operator runbook ← ground truth for all stage decisions
+4. `docs/adapter-contracts.md` — generative adapter detail
+5. `docs/pipeline-architecture.md` — chain composition
+6. `runtime-assumptions.md` — host requirements
+7. `validation-checklist.md` — pre-flight and post-pipeline checks
+
+When `skills.md` and this file conflict, `skills.md` wins on stage execution detail. This file wins on startup order and non-negotiable rules.
+
+## Input contract
+
+- Brand kit at `brands/<client-slug>/brand-kit.md` (copied from `brands/_template/`).
+- User-supplied campaign intent, target length, and aesthetic direction.
+- Optional: reference images for Stage 2 generative bindings.
+- Optional: `${CREATIVE_STRATEGIST_HOME}/templates/hooks-library/500-winning-hooks.csv` for hook selection.
+
+## Output artifacts
+
+```
+output/<client-slug>/<project-slug>/
+├── brief/pipeline-brief.md          Stage 1
+├── generative/manifest.json         Stage 2
+├── generative/*.mp4 / *.jpg         Stage 2
+└── final/final.mp4                  Stage 3
+```
+
+## Stage execution summary
+
+**Stage 1 — Brief**
+- Load brand kit → scene structure → hook selection → write `pipeline-brief.md`
+- Spawn sub-skill: `skills/brief-generation/SKILL.md` for heavy context work
+- Self-eval: brief sourced from brand-kit.md, not memory; brand constraints box present
+
+**Stage 2 — Generate**
+- Check adapter (`bash helpers/check-generative-adapter.sh`)
+- Growthub-pipeline path: `bash helpers/run-pipeline.sh` with `video-generation` CMS node
+- BYOK path: `lib/adapters/generative/index.js` routes to provider SDK
+- Both paths write `manifest.json` through the adapter contract using official CLI/SDK execution events
+- Spawn sub-skill: `skills/generative-execution/SKILL.md`
+- Self-eval: manifest.json has one artifact URL per scene; no secrets in artifacts
+
+**Stage 3 — Edit**
+- Verify `VIDEO_USE_HOME` → stage clips → write `edit-plan.md` → hand off to video-use agent
+- video-use fork: Scribe transcription → EDL → FFmpeg render → final.mp4
+- Spawn sub-skill: `skills/video-edit/SKILL.md`
+- Self-eval: `final.mp4` exists, duration ±10% of target, QA checklist passes
+
+## Non-negotiable rules
+
+1. Brief content sourced from `brand-kit.md` only — no brand detail from memory.
+2. Generative execution routes through the adapter contract — no raw API calls outside it.
+3. Stage 3 delegates to `VIDEO_USE_HOME` fork — never duplicate its pipeline inline.
+4. `output/<client>/<project>/` is the only write root for pipeline artifacts.
+5. `ELEVENLABS_API_KEY` and provider keys never appear in output artifacts.
+6. AI generation prompts in brief Appendix only — never inline in scene blocks.
+7. Append to `.growthub-fork/project.md` at every stage boundary.
+8. `maxRetries: 3` enforced per selfEval criteria — park with `needs_confirmation` at ceiling.
+
+## Troubleshooting
+
+- Missing `ELEVENLABS_API_KEY` → re-run `node setup/verify-env.mjs`.
+- `growthub auth whoami` fails → run `growthub auth login`.
+- `VIDEO_USE_HOME` not found → run `bash setup/clone-fork.sh`.
+- `~/.claude/skills/video-use` missing → run `bash setup/install-skill.sh`.
+- `ffmpeg` not found → re-run `bash setup/check-deps.sh`.
+
+---
+
+## Governed-workspace primitives (v1.2)
+
+This workspace carries the six architectural primitives every Growthub fork inherits. The contract is capability-agnostic (`@growthub/api-contract/skills::SkillManifest`); kit-specific specialisation lives in `skills.md` above.
+
+1. **`SKILL.md`** at the kit root — the discovery entry / routing menu. Read before `skills.md`.
+2. **Repo-root `AGENTS.md` pointer** — Cursor / Claude / Codex all read the same contract.
+3. **`.growthub-fork/project.md`** — session memory, seeded at init/import from `templates/project.md`. Append a dated entry after every material change.
+4. **Self-evaluation (`selfEval.criteria` + `maxRetries`)** — generate → apply → evaluate → record; retry up to 3; every attempt writes to both `project.md` (human) and `trace.jsonl` (machine). Use `recordSelfEval` (`cli/src/skills/self-eval.ts`); never bypass the fork-trace primitive.
+5. **Nested `skills/<slug>/SKILL.md`** — `brief-generation`, `generative-execution`, `video-edit` lanes.
+6. **`helpers/<verb>.{sh,mjs,py}`** — `run-pipeline.sh`, `check-generative-adapter.sh`.
+
+Command surface from inside this fork:
+
+- `growthub skills list` — enumerate this fork's SKILL.md tree
+- `growthub skills validate` — strict shape check
+- `growthub skills session show` — print `.growthub-fork/project.md`
+- `growthub skills session init --kit growthub-creative-video-pipeline-v1` — (re-)seed session memory

package/dist/index.js

@@ -8528,6 +8528,15 @@ var init_catalog = __esm({
         activationModes: ["export"],
         family: "studio"
       },
+      {
+        id: "growthub-creative-video-pipeline-v1",
+        packageDirName: "growthub-creative-video-pipeline-v1",
+        defaultBundleId: "growthub-creative-video-pipeline-v1",
+        type: "worker",
+        executionMode: "export",
+        activationModes: ["export"],
+        family: "studio"
+      },
       {
         id: "growthub-twenty-crm-v1",
         packageDirName: "growthub-twenty-crm-v1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Growthub Local is a control plane for forked worker kits. The CLI is the executor, the hosted app is the identity authority, the worker kit is the unit of portable agent infrastructure, and the fork is the operator's personal branch of that infrastructure — policy-governed, trace-backed, and self-healing.",
   "type": "module",
   "bin": {