@growthub/cli 0.8.2 → 0.9.1

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

@@ -24,6 +24,8 @@ helpers:
     description: Auth pre-flight + growthub pipeline execute passthrough
   - path: helpers/check-generative-adapter.sh
     description: Print current adapter mode and which provider keys are set
+  - path: helpers/check-pipeline-health.sh
+    description: Composable end-to-end readiness check (env + adapter + sub-skills + Stage 3 deps); supports --json
 subSkills:
   - name: brief-generation
     path: skills/brief-generation/SKILL.md
@@ -60,6 +62,25 @@ Fork exists (.growthub-fork/fork.json)?
           8. .growthub-fork/trace.jsonl (tail 20) — recent machine history
 ```
 
+## Agent operating loop (deterministic, no Markdown inference)
+
+For agents (Claude Code, Cursor, Codex), the canonical readiness +
+inspection loop uses the CLI's typed JSON outputs — read these BEFORE
+falling back to Markdown:
+
+```bash
+growthub kit health       <fork-id-or-path> --json   # KitHealthReport
+growthub kit pipeline     inspect <fork-id-or-path> --json   # PipelineKitManifest
+growthub kit dependencies inspect <fork-id-or-path> --json   # WorkspaceDependencyManifest
+growthub kit inspect      <fork-id-or-path> --json   # WorkerKitManifest (kit.json)
+```
+
+Each command accepts a kit id, filesystem path, OR a registered fork
+id. Both `--json` (agent) and interactive sub-branch (human) surfaces
+share the same primitives.
+
+Markdown explains the contract; the SDK + CLI are the source of truth.
+
 ## Three-stage pipeline
 
 ```
@@ -89,7 +110,7 @@ Both normalize to the same `GenerativeArtifact[]` object. The UI shell renders w
 3. **`.growthub-fork/project.md`** — session memory, seeded at init from `templates/project.md`.
 4. **Self-evaluation** — generate → apply → evaluate → record; retry up to `maxRetries` (3); mirrors the Fork Sync Agent loop.
 5. **`skills/`** — sub-skill lanes: `brief-generation`, `generative-execution`, `video-edit`.
-6. **`helpers/`** — `run-pipeline.sh`, `check-generative-adapter.sh`.
+6. **`helpers/`** — `run-pipeline.sh`, `check-generative-adapter.sh`, `check-pipeline-health.sh`.
 
 ## Related files
 

package/assets/worker-kits/growthub-creative-video-pipeline-v1/bundles/growthub-creative-video-pipeline-v1.json

@@ -27,6 +27,8 @@
     "output-standards.md",
     "runtime-assumptions.md",
     "validation-checklist.md",
+    "pipeline.manifest.json",
+    "workspace.dependencies.json",
     "workers/creative-video-pipeline-operator/CLAUDE.md",
     "brands/_template/brand-kit.md",
     "brands/growthub/brand-kit.md",
@@ -52,6 +54,8 @@
     "helpers/README.md",
     "helpers/run-pipeline.sh",
     "helpers/check-generative-adapter.sh",
+    "helpers/check-pipeline-health.sh",
+    "validation/e2e-reference.md",
     "skills/README.md",
     "skills/brief-generation/SKILL.md",
     "skills/generative-execution/SKILL.md",

package/assets/worker-kits/growthub-creative-video-pipeline-v1/helpers/README.md

@@ -6,3 +6,4 @@ Safe shell helpers for the creative-video-pipeline operator. These wrap external
 |--------|---------|
 | `run-pipeline.sh` | Wraps `growthub pipeline execute` for Stage 2 |
 | `check-generative-adapter.sh` | Validates env for the selected generative adapter |
+| `check-pipeline-health.sh` | End-to-end readiness check across all three stages (composes the two above + Stage-3 deps + sub-skill / helper presence). Supports `--json`. |

package/assets/worker-kits/growthub-creative-video-pipeline-v1/helpers/check-pipeline-health.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# check-pipeline-health.sh
+#
+# Composable end-to-end readiness check for the creative-video-pipeline kit.
+# Wraps existing setup/verify-env.mjs + helpers/check-generative-adapter.sh
+# and adds checks that span all three stages (sub-skills present, helpers
+# executable, output dir writable, Stage-3 deps).
+#
+# Usage:
+#   bash helpers/check-pipeline-health.sh           # human output, exit non-zero on failure
+#   bash helpers/check-pipeline-health.sh --json    # JSON report on stdout
+#
+# Convention: docs/PIPELINE_KIT_CONTRACT_V1.md (kit-local health helper)
+set -uo pipefail
+
+JSON_MODE=0
+if [ "${1:-}" = "--json" ]; then
+  JSON_MODE=1
+fi
+
+KIT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+PASS=()
+FAIL=()
+WARN=()
+
+record_pass() { PASS+=("$1"); }
+record_fail() { FAIL+=("$1"); }
+record_warn() { WARN+=("$1"); }
+
+# --- Load .env / .env.local if present (for inherited shell, mjs reads its own) ---
+for env_file in "$KIT_ROOT/.env" "$KIT_ROOT/.env.local"; do
+  if [ -f "$env_file" ]; then
+    set -a
+    # shellcheck disable=SC1090
+    . "$env_file"
+    set +a
+  fi
+done
+
+# --- 1. .env presence ---
+if [ -f "$KIT_ROOT/.env" ] || [ -f "$KIT_ROOT/.env.local" ]; then
+  record_pass "env-file-present"
+elif [ -f "$KIT_ROOT/.env.example" ]; then
+  record_warn "env-file-missing-but-example-available"
+else
+  record_fail "env-file-missing-and-no-example"
+fi
+
+# --- 2. setup/verify-env.mjs passes ---
+if [ -f "$KIT_ROOT/setup/verify-env.mjs" ]; then
+  if node "$KIT_ROOT/setup/verify-env.mjs" >/dev/null 2>&1; then
+    record_pass "verify-env"
+  else
+    record_fail "verify-env"
+  fi
+else
+  record_fail "verify-env-script-missing"
+fi
+
+# --- 3. helpers/check-generative-adapter.sh passes ---
+if [ -x "$KIT_ROOT/helpers/check-generative-adapter.sh" ]; then
+  if bash "$KIT_ROOT/helpers/check-generative-adapter.sh" >/dev/null 2>&1; then
+    record_pass "generative-adapter-env"
+  else
+    record_fail "generative-adapter-env"
+  fi
+else
+  record_fail "check-generative-adapter-not-executable"
+fi
+
+# --- 4. VIDEO_USE_HOME resolves to a directory ---
+if [ -n "${VIDEO_USE_HOME:-}" ] && [ -d "${VIDEO_USE_HOME}" ]; then
+  record_pass "video-use-home"
+else
+  record_fail "video-use-home-missing-or-not-a-directory"
+fi
+
+# --- 5. ELEVENLABS_API_KEY (Stage 3 transcription) ---
+if [ -n "${ELEVENLABS_API_KEY:-}" ]; then
+  record_pass "elevenlabs-api-key"
+else
+  record_fail "elevenlabs-api-key-missing"
+fi
+
+# --- 6. output/ writable ---
+mkdir -p "$KIT_ROOT/output" 2>/dev/null || true
+if [ -w "$KIT_ROOT/output" ]; then
+  record_pass "output-dir-writable"
+else
+  record_fail "output-dir-not-writable"
+fi
+
+# --- 7. Stage sub-skills present ---
+for stage in brief-generation generative-execution video-edit; do
+  if [ -f "$KIT_ROOT/skills/$stage/SKILL.md" ]; then
+    record_pass "sub-skill-$stage"
+  else
+    record_fail "sub-skill-$stage-missing"
+  fi
+done
+
+# --- 8. Helpers executable ---
+for helper in run-pipeline.sh check-generative-adapter.sh check-pipeline-health.sh; do
+  helper_path="$KIT_ROOT/helpers/$helper"
+  if [ -f "$helper_path" ] && [ -r "$helper_path" ]; then
+    record_pass "helper-$helper"
+  else
+    record_fail "helper-$helper-missing"
+  fi
+done
+
+# --- 9. pipeline.manifest.json + workspace.dependencies.json present (kit contract v1) ---
+for manifest in pipeline.manifest.json workspace.dependencies.json; do
+  if [ -f "$KIT_ROOT/$manifest" ]; then
+    record_pass "manifest-$manifest"
+  else
+    record_warn "manifest-$manifest-missing"
+  fi
+done
+
+# --- Render result ---
+if [ "$JSON_MODE" = "1" ]; then
+  printf '{'
+  printf '"kitId":"growthub-creative-video-pipeline-v1",'
+  printf '"convention":"docs/PIPELINE_KIT_CONTRACT_V1.md",'
+  printf '"pass":['
+  for i in "${!PASS[@]}"; do
+    [ "$i" -gt 0 ] && printf ','
+    printf '"%s"' "${PASS[$i]}"
+  done
+  printf '],"warn":['
+  for i in "${!WARN[@]}"; do
+    [ "$i" -gt 0 ] && printf ','
+    printf '"%s"' "${WARN[$i]}"
+  done
+  printf '],"fail":['
+  for i in "${!FAIL[@]}"; do
+    [ "$i" -gt 0 ] && printf ','
+    printf '"%s"' "${FAIL[$i]}"
+  done
+  printf ']}\n'
+else
+  echo "[check-pipeline-health] Kit: growthub-creative-video-pipeline-v1"
+  for item in "${PASS[@]}"; do echo "  PASS  $item"; done
+  for item in "${WARN[@]}"; do echo "  WARN  $item"; done
+  for item in "${FAIL[@]}"; do echo "  FAIL  $item" >&2; done
+  echo "[check-pipeline-health] pass=${#PASS[@]} warn=${#WARN[@]} fail=${#FAIL[@]}"
+fi
+
+if [ "${#FAIL[@]}" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/assets/worker-kits/growthub-creative-video-pipeline-v1/kit.json

@@ -30,6 +30,8 @@
     "output-standards.md",
     "runtime-assumptions.md",
     "validation-checklist.md",
+    "pipeline.manifest.json",
+    "workspace.dependencies.json",
     "workers/creative-video-pipeline-operator/CLAUDE.md",
     "brands/_template/brand-kit.md",
     "brands/growthub/brand-kit.md",
@@ -55,6 +57,8 @@
     "helpers/README.md",
     "helpers/run-pipeline.sh",
     "helpers/check-generative-adapter.sh",
+    "helpers/check-pipeline-health.sh",
+    "validation/e2e-reference.md",
     "skills/README.md",
     "skills/brief-generation/SKILL.md",
     "skills/generative-execution/SKILL.md",
@@ -99,6 +103,8 @@
       "bundles/growthub-creative-video-pipeline-v1.json",
       "SKILL.md",
       "skills.md",
+      "pipeline.manifest.json",
+      "workspace.dependencies.json",
       "workers/creative-video-pipeline-operator/CLAUDE.md",
       "brands/_template/brand-kit.md",
       "brands/growthub/brand-kit.md",

package/assets/worker-kits/growthub-creative-video-pipeline-v1/pipeline.manifest.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "kitId": "growthub-creative-video-pipeline-v1",
+  "pipelineId": "creative-video-pipeline",
+  "outputTopology": {
+    "root": "output/<client>/<project>",
+    "buckets": ["brief", "generative", "final"]
+  },
+  "tracePolicy": {
+    "convention": "docs/PIPELINE_TRACE_CONVENTION_V1.md",
+    "traceFile": ".growthub-fork/trace.jsonl",
+    "projectMemoryFile": ".growthub-fork/project.md"
+  },
+  "sessionMemoryPolicy": {
+    "seedTemplate": "templates/project.md",
+    "appendOn": ["stage-completed", "stage-failed", "self-eval"]
+  },
+  "stages": [
+    {
+      "id": "brief-generation",
+      "label": "Brief",
+      "subSkillPath": "skills/brief-generation/SKILL.md",
+      "inputArtifacts": [
+        "brands/<client>/brand-kit.md"
+      ],
+      "outputArtifacts": [
+        "output/<client>/<project>/brief/pipeline-brief.md"
+      ],
+      "helperPaths": [],
+      "adapterModes": [],
+      "externalDependencies": [],
+      "traceRequired": true,
+      "projectMemoryRequired": true
+    },
+    {
+      "id": "generative-execution",
+      "label": "Generate",
+      "subSkillPath": "skills/generative-execution/SKILL.md",
+      "inputArtifacts": [
+        "output/<client>/<project>/brief/pipeline-brief.md"
+      ],
+      "outputArtifacts": [
+        "output/<client>/<project>/generative/manifest.json"
+      ],
+      "helperPaths": [
+        "helpers/run-pipeline.sh",
+        "helpers/check-generative-adapter.sh"
+      ],
+      "adapterModes": [
+        "growthub-pipeline",
+        "byo-api-key"
+      ],
+      "externalDependencies": [],
+      "traceRequired": true,
+      "projectMemoryRequired": true
+    },
+    {
+      "id": "video-edit",
+      "label": "Edit",
+      "subSkillPath": "skills/video-edit/SKILL.md",
+      "inputArtifacts": [
+        "output/<client>/<project>/generative/manifest.json",
+        "output/<client>/<project>/brief/pipeline-brief.md"
+      ],
+      "outputArtifacts": [
+        "output/<client>/<project>/final/final.mp4"
+      ],
+      "helperPaths": [],
+      "adapterModes": [],
+      "externalDependencies": ["video-use"],
+      "traceRequired": true,
+      "projectMemoryRequired": true
+    }
+  ],
+  "convention": {
+    "spec": "docs/PIPELINE_KIT_CONTRACT_V1.md",
+    "sdkType": "@growthub/api-contract/pipeline-kits#PipelineKitManifest",
+    "sdkVersion": 1,
+    "version": 1,
+    "interpretedBy": ["growthub kit pipeline inspect", "agents", "operators"],
+    "runtimeEnforcement": "none"
+  }
+}

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

@@ -0,0 +1,166 @@
+# E2E Reference Validation — Creative Video Pipeline
+
+This is the **reproducible target** for the end-to-end QA preserved in
+commit `7eb832d` ("ship creative video pipeline worker kit").
+
+A new operator (human or agent) should be able to follow this document and
+re-produce a passing run. If you cannot, the kit is not v1-ready.
+
+**Reference convention:** [`docs/PIPELINE_KIT_CONTRACT_V1.md`](../../../../../docs/PIPELINE_KIT_CONTRACT_V1.md).
+
+---
+
+## Test inputs
+
+| Input | Value |
+|---|---|
+| Test brand | `brands/growthub/brand-kit.md` (shipped in this kit) |
+| Client slug | `growthub` |
+| Project slug | `e2e-reference` |
+| Adapter mode | `growthub-pipeline` (primary) — see "BYOK variant" below |
+| Stage 2 model | `veo-3.1-generate-001` (CMS node `video-generation`) |
+
+---
+
+## Required environment
+
+| Var | Required for | Real key required? |
+|---|---|---|
+| `CREATIVE_VIDEO_PIPELINE_GENERATIVE_ADAPTER=growthub-pipeline` | Stage 2 selection | no — string literal |
+| `GROWTHUB_BRIDGE_ACCESS_TOKEN` | Stage 2 hosted execution | yes |
+| `GROWTHUB_BRIDGE_BASE_URL` | Stage 2 hosted execution | yes |
+| `growthub auth whoami --json` returns OK | Stage 2 pre-flight | yes (run `growthub auth login` first) |
+| `VIDEO_USE_HOME` | Stage 3 delegation | yes — must point at a real `video-use` clone |
+| `ELEVENLABS_API_KEY` | Stage 3 transcription | yes |
+
+Run `bash helpers/check-pipeline-health.sh` to validate before starting.
+
+---
+
+## Stage 1 — Brief
+
+**Input:** `brands/growthub/brand-kit.md`
+
+**Sub-skill:** `skills/brief-generation/SKILL.md`
+
+**Run:** through the operator (Claude Code, Cursor, etc.) — no shell command.
+
+**Expected output:** `output/growthub/e2e-reference/brief/pipeline-brief.md`
+
+**Acceptance:**
+
+- Brief contains brand-constraints box, scene table, hook variations A–E,
+  editing guidelines.
+- AI generation prompts appear in the Appendix only — never inline in scene
+  blocks.
+- `.growthub-fork/project.md` has a "Stage 1 Complete — brief-generation"
+  entry.
+- `.growthub-fork/trace.jsonl` has a `stage-complete` line for Stage 1
+  (and, when v1 trace adoption lands,
+  `pipeline_stage_completed`).
+
+---
+
+## Stage 2 — Generate
+
+**Input:** Stage 1 brief.
+
+**Sub-skill:** `skills/generative-execution/SKILL.md`
+
+**Run:**
+
+```bash
+bash helpers/check-generative-adapter.sh
+bash helpers/run-pipeline.sh '<DynamicRegistryPipeline JSON assembled from brief>'
+```
+
+The CLI streams NDJSON `ExecutionEvent` lines (typed by
+`@growthub/api-contract`).
+
+**Expected output:** `output/growthub/e2e-reference/generative/manifest.json`
+
+```json
+{
+  "kitId": "growthub-creative-video-pipeline-v1",
+  "adapter": "growthub-pipeline",
+  "executionId": "<uuid from complete event>",
+  "createdAt": "<iso>",
+  "artifacts": [
+    { "id": "...", "type": "video", "provider": "veo", "url": "https://...", "prompt": "..." }
+  ]
+}
+```
+
+**Acceptance:**
+
+- `manifest.json` is valid JSON.
+- Each entry has `id`, `type`, `provider`, `url`, `prompt`.
+- Artifact count matches scene count in Stage 1 brief.
+- No API keys appear in any artifact file.
+- `.growthub-fork/project.md` has a "Stage 2 Complete — generative-execution"
+  entry recording the adapter mode used.
+
+---
+
+## Stage 3 — Edit
+
+**Input:** Stage 2 `manifest.json` + Stage 1 `pipeline-brief.md`.
+
+**Sub-skill:** `skills/video-edit/SKILL.md`
+
+**Run:** via the `VIDEO_USE_HOME` fork. The kit MUST NOT inline video-use
+logic. The handoff is `output/growthub/e2e-reference/final/edit-plan.md`.
+
+**Expected output:** `output/growthub/e2e-reference/final/final.mp4`
+
+**Acceptance:**
+
+- `final.mp4` exists and is playable.
+- Duration within ±10% of the target declared in the edit plan.
+- Audio fades at segment boundaries (~30 ms).
+- Subtitles are applied last.
+- No secrets appear in any output artifact.
+
+---
+
+## BYOK variant
+
+To re-run with `byo-api-key`:
+
+1. Set `CREATIVE_VIDEO_PIPELINE_GENERATIVE_ADAPTER=byo-api-key`.
+2. Set `VIDEO_MODEL_PROVIDER` to `veo` | `fal` | `runway`.
+3. Set the matching provider key (`GOOGLE_AI_API_KEY` / `FAL_API_KEY` /
+   `RUNWAY_API_KEY`).
+
+The Stage 2 `manifest.json` shape is **identical** to the
+`growthub-pipeline` adapter — that is the entire point of the adapter
+contract.
+
+---
+
+## What can be mocked
+
+| Element | Mockable? | How |
+|---|---|---|
+| Brand kit | yes | use any `brands/<slug>/brand-kit.md` |
+| Stage 1 LLM | yes | the brief stage is operator-driven; any agent can produce it |
+| Stage 2 hosted execution | **no** — uses real provider credits |
+| Stage 2 BYOK | **no** — uses real provider credits |
+| Stage 3 ElevenLabs transcription | **no** — uses real ElevenLabs credits |
+| Stage 3 FFmpeg | yes — `video-use` runs locally |
+
+For pure shape validation (no spend), the legacy
+`validation-checklist.md` covers the structural checks without
+provider calls.
+
+---
+
+## Cross-references
+
+- [`validation-checklist.md`](../validation-checklist.md) — structural QA
+- [`docs/pipeline-architecture.md`](../docs/pipeline-architecture.md) —
+  kit-local architecture
+- [`pipeline.manifest.json`](../pipeline.manifest.json) — machine-readable
+  stage map
+- [`workspace.dependencies.json`](../workspace.dependencies.json) —
+  external `video-use` dependency declaration

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

@@ -2,11 +2,15 @@
 
 Run before calling the kit v1-ready or before a Vercel deployment.
 
+For the **reproducible end-to-end run** (Stages 1–3 against real provider
+keys), follow [`validation/e2e-reference.md`](./validation/e2e-reference.md).
+
 ## 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
+- [ ] `bash helpers/check-pipeline-health.sh` exits 0 (composes all of the above)
 - [ ] `VIDEO_USE_HOME` resolves to an existing `video-use` clone
 
 ## Growthub CLI (growthub-pipeline adapter)

package/assets/worker-kits/growthub-creative-video-pipeline-v1/workspace.dependencies.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "kitId": "growthub-creative-video-pipeline-v1",
+  "dependencies": [
+    {
+      "id": "video-use",
+      "kind": "git-fork",
+      "env": "VIDEO_USE_HOME",
+      "setup": "setup/clone-fork.sh",
+      "install": "setup/install-skill.sh",
+      "health": "setup/verify-env.mjs",
+      "usedByStages": ["video-edit"],
+      "interfaceArtifact": "output/<client>/<project>/generative/manifest.json",
+      "handoffArtifact": "output/<client>/<project>/final/final.mp4",
+      "description": "External video editing fork. Stage 3 delegates entirely to this repo via edit-plan.md. The kit MUST NOT inline video-use logic."
+    }
+  ],
+  "convention": {
+    "spec": "docs/WORKER_KIT_CONTRACT_V1.md",
+    "sdkType": "@growthub/api-contract/workspaces#WorkspaceDependencyManifest",
+    "sdkVersion": 1,
+    "version": 1,
+    "interpretedBy": ["growthub kit dependencies inspect", "agents", "operators"],
+    "runtimeEnforcement": "none"
+  }
+}