@growthub/cli 0.7.9 → 0.8.1

package/assets/worker-kits/creative-strategist-v1/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: creative-strategist-v1
+description: "Frozen Creative Strategist worker kit — produces video creative briefs from frozen ad formats + scene modules + a 500-hook CSV. Use when the user says: \"new creative brief\", \"creative strategist\", \"hook library\", \"scene modules\". Session memory at .growthub-fork/project.md tracks brand kits used, hook variations chosen, and per-cut self-eval outcomes across multi-day brief production."
+triggers:
+  - creative strategist
+  - fork creative-strategist-v1
+progressiveDisclosure: true
+sessionMemory:
+  path: .growthub-fork/project.md
+selfEval:
+  criteria:
+    - Operator contract (workers/creative-strategist/CLAUDE.md) read before any material change.
+    - .growthub-fork/project.md appended to at each material change.
+    - .growthub-fork/trace.jsonl receives a typed event for each material change.
+    - Kit-specific QUICKSTART / runtime-assumptions / output-standards honoured.
+  maxRetries: 3
+  traceTo: .growthub-fork/trace.jsonl
+helpers:
+  - path: helpers/grep-hooks.sh
+    description: 3-pass keyword search over the frozen 500-winning-hooks CSV (replaces inline Step 2d shell).
+  - path: helpers/extract-muse-frames.sh
+    description: Deterministic ffprobe + ffmpeg wrapper for Step 2b muse-frame extraction.
+subSkills:
+  - name: creative-strategist-frame-analysis
+    path: skills/frame-analysis/SKILL.md
+mcpTools: []
+---
+
+# Growthub Agent Worker Kit — Creative Strategist
+
+Discovery entry + routing menu for the `creative-strategist-v1` worker kit. Family: `workflow`. Agent contract: `workers/creative-strategist/CLAUDE.md`.
+
+## When to use this skill
+
+When the user's intent matches any of the triggers above — or when an agent has been dropped into a fork whose `.growthub-fork/fork.json` declares `kitId: "creative-strategist-v1"`.
+
+## Decision tree
+
+```
+Fork exists (this directory contains .growthub-fork/fork.json)?
+├── No  → run: growthub starter init --out <path>   (or import-repo / import-skill)
+│         then: growthub kit download creative-strategist-v1 --out <path>
+│
+└── Yes → read in this order:
+          1. .growthub-fork/project.md                         — session memory (primitive #3)
+          2. SKILL.md  (this file)                             — routing menu  (primitive #1)
+          3. skills.md                                         — operator runbook
+          4. workers/creative-strategist/CLAUDE.md                              — agent contract
+          5. QUICKSTART.md                                     — first-run steps
+          6. runtime-assumptions.md                            — host expectations
+          7. .growthub-fork/policy.json                        — what you may touch
+          8. .growthub-fork/trace.jsonl (tail 20)              — recent machine history
+```
+
+## The six primitives (same shape across every Growthub worker kit)
+
+1. **`SKILL.md`** — this file.
+2. **Symlinked pointer** — repo-root `AGENTS.md` is authoritative.
+3. **`.growthub-fork/project.md`** — session memory, seeded by the CLI from `templates/project.md` at init/import time.
+4. **Self-evaluation** — generate → apply → evaluate → record; retry up to `selfEval.maxRetries` (default 3); mirrors the Fork Sync Agent's preview → apply → trace loop (primitive #4). Contract: `@growthub/api-contract/skills::SkillSelfEval`.
+5. **`skills/`** — nested sub-skills for parallel sub-agents on heavy / narrow work.
+6. **`helpers/`** — safe shell tool layer. Promote inline shell here whenever the same snippet is re-used.
+
+## Self-evaluation (primitive #4)
+
+Enforce `selfEval.maxRetries: 3`. At the ceiling, park with a `needs_confirmation` note in `project.md` and stop. Record every attempt to both `project.md` and `trace.jsonl`.
+
+## Session memory (primitive #3)
+
+`.growthub-fork/project.md` is the only cross-session continuity surface for this fork. Append at every material change, approval boundary, and self-eval outcome.
+
+## Sub-skills (primitive #5)
+
+(None declared at the baseline; populate `skills/` and the frontmatter `subSkills[]` array as specialist lanes emerge.)
+
+## Helpers (primitive #6)
+
+(None declared at the baseline; populate `helpers/` and the frontmatter `helpers[]` array as inline shell matures.)
+
+## MCP routing (optional)
+
+List concrete MCP tool IDs in `mcpTools[]` when a fork runs an MCP server for auth-heavy actions. Declarative only at v1.
+
+## Related files
+
+- `skills.md` — operator runbook (deep)
+- `QUICKSTART.md` — first-run steps
+- `runtime-assumptions.md` — host expectations
+- `output-standards.md` — output locations + manifest shape
+- `validation-checklist.md` — pre-flight checklist (if present)
+- `templates/project.md` — session-memory template
+- `templates/self-eval.md` — self-evaluation template
+- `helpers/README.md` — safe shell tool layer convention
+- `skills/README.md` — sub-skill convention
+- `workers/creative-strategist/CLAUDE.md` — agent contract

package/assets/worker-kits/creative-strategist-v1/bundles/creative-strategist-v1.json

@@ -36,12 +36,22 @@
     "templates/scene-modules/hooks/tiktok-comment.md",
     "templates/scene-modules/hooks/villain-hook.md",
     "growthub-meta/README.md",
-    "growthub-meta/kit-standard.md"
+    "growthub-meta/kit-standard.md",
+    "SKILL.md",
+    "templates/project.md",
+    "templates/self-eval.md",
+    "helpers/README.md",
+    "skills/README.md",
+    "helpers/grep-hooks.sh",
+    "helpers/extract-muse-frames.sh",
+    "skills/frame-analysis/SKILL.md"
   ],
   "optionalPresets": [],
   "export": {
     "folderName": "growthub-agent-worker-kit-creative-strategist-v1",
     "zipFileName": "growthub-agent-worker-kit-creative-strategist-v1.zip"
   },
-  "activationModes": ["export"]
+  "activationModes": [
+    "export"
+  ]
 }

package/assets/worker-kits/creative-strategist-v1/helpers/README.md

@@ -0,0 +1,29 @@
+# `helpers/` — safe shell tool layer (primitive #6)
+
+A **helper** is a small, deterministic script an agent invokes via one shell call instead of reconstructing a raw pipeline inline. Helpers are reviewable, deterministic, and safer than raw commands.
+
+## Convention
+
+```
+helpers/
+├── README.md                 # this file
+├── <verb>.sh                 # single-purpose shell scripts
+├── <verb>.mjs                # optional: Node-based helper
+└── <verb>.py                 # optional: Python-based helper
+```
+
+Every helper:
+
+1. Carries a one-line header comment: what it does + how to invoke it.
+2. Uses `set -euo pipefail` (or equivalent) — no silent failures.
+3. Has a matching row in the parent `SKILL.md`'s `helpers[]` frontmatter.
+4. Is referenced from `skills.md` at the step the agent should invoke it (no duplicated shell bodies).
+
+## When to promote an inline snippet
+
+- Appears more than once in `skills.md`.
+- Has fragile quoting or path interpolation.
+- Calls a side-effecting binary (ffmpeg, git, gh, npm install).
+- Multiple sub-skills invoke it.
+
+See the parent `SKILL.md` `helpers[]` array for the current roster.

package/assets/worker-kits/creative-strategist-v1/helpers/extract-muse-frames.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# extract-muse-frames.sh — deterministic muse-video frame extraction.
+#
+# Use: bash helpers/extract-muse-frames.sh <path-to-video.mp4> [--interval <seconds>]
+#
+# Replaces the inline ffprobe+ffmpeg block in skills.md Step 2b. Writes
+# /tmp/muse_frames/frame_%ds.jpg and prints the first 3 frame paths so an
+# agent can immediately read them via its file-read tool.
+#
+# Interval defaults to 3s for videos >=30s, 2s for videos <30s (matches the
+# runbook guidance for TikTok-format short muses).
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: bash helpers/extract-muse-frames.sh <path-to-video> [--interval N]" >&2
+  exit 2
+fi
+
+VIDEO="$1"
+shift
+
+if [[ ! -f "${VIDEO}" ]]; then
+  echo "Video not found: ${VIDEO}" >&2
+  exit 1
+fi
+
+INTERVAL=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --interval)
+      INTERVAL="$2"
+      shift 2
+      ;;
+    *)
+      echo "unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+for bin in ffprobe ffmpeg python3; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "Missing required binary on PATH: $bin" >&2
+    exit 1
+  fi
+done
+
+DURATION="$(ffprobe -v quiet -print_format json -show_format -show_streams "${VIDEO}" \
+  | python3 -c 'import sys, json
+d = json.load(sys.stdin)
+for s in d.get("streams", []):
+    if s.get("codec_type") == "video":
+        print(s.get("duration", 0))
+        break
+')"
+DURATION_INT="$(python3 -c "print(int(float('${DURATION:-0}')))")"
+
+if [[ -z "${INTERVAL}" ]]; then
+  if [[ "${DURATION_INT}" -lt 30 ]]; then
+    INTERVAL=2
+  else
+    INTERVAL=3
+  fi
+fi
+
+OUT_DIR="/tmp/muse_frames"
+mkdir -p "${OUT_DIR}"
+# Clear prior run so downstream `ls` stays deterministic.
+rm -f "${OUT_DIR}"/frame_*.jpg
+
+echo "video:    ${VIDEO}"
+echo "duration: ${DURATION_INT}s"
+echo "interval: ${INTERVAL}s"
+echo "out:      ${OUT_DIR}"
+
+ffmpeg -loglevel error -y -i "${VIDEO}" -vf "fps=1/${INTERVAL}" "${OUT_DIR}/frame_%ds.jpg"
+
+echo ""
+echo "First frames (read these with your file-read tool):"
+ls "${OUT_DIR}"/frame_*.jpg | sort | head -3

package/assets/worker-kits/creative-strategist-v1/helpers/grep-hooks.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# grep-hooks.sh — 3-pass search over the frozen 500-hook CSV.
+#
+# Use: bash helpers/grep-hooks.sh "<keyword>" [--limit <n>]
+#
+# Runs the same 3-pass method documented in skills.md Step 2d against
+# ${CREATIVE_STRATEGIST_HOME:-$HOME/creative-strategist}/templates/hooks-library/500-winning-hooks.csv.
+# Prints an Example / Structure pair for each match. Deterministic; no network.
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: bash helpers/grep-hooks.sh <keyword> [--limit N]" >&2
+  exit 2
+fi
+
+KEYWORD="$1"
+shift
+
+LIMIT=20
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    *)
+      echo "unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+KIT_HOME="${CREATIVE_STRATEGIST_HOME:-$HOME/creative-strategist}"
+CSV="${KIT_HOME}/templates/hooks-library/500-winning-hooks.csv"
+
+if [[ ! -f "${CSV}" ]]; then
+  echo "Hooks CSV not found at: ${CSV}" >&2
+  echo "Set CREATIVE_STRATEGIST_HOME to the kit root, or download the kit to \$HOME/creative-strategist." >&2
+  exit 1
+fi
+
+python3 - "${CSV}" "${KEYWORD}" "${LIMIT}" <<'PY'
+import csv, sys
+
+path, kw, limit = sys.argv[1], sys.argv[2].lower(), int(sys.argv[3])
+printed = 0
+with open(path, newline="", encoding="utf-8") as f:
+    for idx, row in enumerate(csv.reader(f)):
+        if len(row) < 2:
+            continue
+        example, structure = row[0], row[1]
+        if kw in example.lower() or kw in structure.lower():
+            print(f"[{idx}] EXAMPLE:   {example[:90]}")
+            print(f"    STRUCTURE: {structure[:100]}\n")
+            printed += 1
+            if printed >= limit:
+                break
+if printed == 0:
+    print(f"No matches for '{kw}' in {path}", file=sys.stderr)
+    sys.exit(3)
+PY

package/assets/worker-kits/creative-strategist-v1/kit.json

@@ -48,7 +48,15 @@
     "templates/scene-modules/hooks/tiktok-comment.md",
     "templates/scene-modules/hooks/villain-hook.md",
     "growthub-meta/README.md",
-    "growthub-meta/kit-standard.md"
+    "growthub-meta/kit-standard.md",
+    "SKILL.md",
+    "templates/project.md",
+    "templates/self-eval.md",
+    "helpers/README.md",
+    "skills/README.md",
+    "helpers/grep-hooks.sh",
+    "helpers/extract-muse-frames.sh",
+    "skills/frame-analysis/SKILL.md"
   ],
   "outputStandard": {
     "type": "working-directory",
@@ -61,7 +69,17 @@
       "brands/_template/brand-kit.md",
       "brands/solawave/brand-kit.md",
       "templates",
-      "growthub-meta"
+      "growthub-meta",
+      "SKILL.md",
+      "templates/project.md",
+      "templates/self-eval.md",
+      "helpers",
+      "helpers/README.md",
+      "skills",
+      "skills/README.md",
+      "helpers/grep-hooks.sh",
+      "helpers/extract-muse-frames.sh",
+      "skills/frame-analysis/SKILL.md"
     ]
   },
   "bundles": [

package/assets/worker-kits/creative-strategist-v1/skills/README.md

@@ -0,0 +1,23 @@
+# `skills/` — nested sub-skill convention (primitive #5)
+
+A **sub-skill** is a full `SKILL.md`-addressable lane that a parent skill can spawn as a parallel sub-agent.
+
+## Convention
+
+```
+skills/
+├── README.md                        # this file
+└── <slug>/                          # kebab-case; matches the SKILL.md name
+    ├── SKILL.md                     # frontmatter + routing body (≤ 500 lines)
+    ├── references/                  # optional — long docs loaded on demand
+    ├── templates/                   # optional — reusable text/JS templates
+    └── scripts/                     # optional — deterministic helpers
+```
+
+Each sub-skill's frontmatter follows `@growthub/api-contract/skills::SkillManifest`. Sub-skills share the parent's `.growthub-fork/project.md` journal — they do not branch it.
+
+## Parallelism
+
+Spawn a sub-skill sub-agent when (a) the sub-skill's work is fully scoped by its own criteria, and (b) the parent's next step does not depend on intermediate state from the sub-skill. Each sub-skill run appends a row to `project.md::subSkillRuns` so the parent can read the outcome on return.
+
+See the parent `SKILL.md` `subSkills[]` array for the current roster.

package/assets/worker-kits/creative-strategist-v1/skills/frame-analysis/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: creative-strategist-frame-analysis
+description: Sub-skill of creative-strategist-v1 — runs the muse-video frame-extraction pass when no frozen ad-format matches the brief. Invokes helpers/extract-muse-frames.sh and returns a scene-map draft. Meant to be spawned as a parallel sub-agent by the parent creative-strategist skill when Step 2b of the brief runbook is triggered.
+triggers:
+  - muse frame extraction
+  - muse analysis
+  - new muse format
+  - frame-by-frame analysis
+progressiveDisclosure: true
+sessionMemory:
+  path: .growthub-fork/project.md
+selfEval:
+  criteria:
+    - Frame count in the brief matches the muse scene count (if muse has 9 scenes, brief has 9).
+    - Each frame read via the agent's file-read tool, batched at most 3 per call.
+    - Tone-flip boundary (problem → solution) identified and recorded in the scene map.
+    - Output scene map references helpers/extract-muse-frames.sh invocation, not inline shell.
+  maxRetries: 3
+  traceTo: .growthub-fork/trace.jsonl
+helpers:
+  - path: ../../helpers/extract-muse-frames.sh
+    description: Deterministic ffprobe + ffmpeg wrapper — replaces the inline Step 2b shell block.
+subSkills: []
+mcpTools: []
+---
+
+# Creative Strategist — Frame Analysis Sub-Skill
+
+Spawned by `creative-strategist-v1` when Step 2b of the brief runbook triggers (no frozen ad-format matches the new muse). Runs in parallel to the parent agent so the parent retains the brief's full context while this sub-agent focuses on frame extraction + scene mapping.
+
+Source of truth for the methodology: `templates/ad-formats/frame-analysis.md` in the parent kit (loaded on demand — this SKILL.md is the routing menu, not the methodology).
+
+## When to spawn this sub-skill
+
+- The brief's muse does not match any entry in `templates/ad-formats/INDEX.md`.
+- A new muse is being frozen into a reusable ad-format.
+- The operator wants the frame-extraction work isolated so the main agent can continue drafting the brief's narrative.
+
+## Decision tree
+
+```
+No frozen ad-format matches?
+├── Yes → parent spawns this sub-skill → parallel execution:
+│         1. bash helpers/extract-muse-frames.sh <muse.mp4>
+│         2. Agent Read-tool over /tmp/muse_frames/*.jpg (batch ≤ 3)
+│         3. Produce scene-map draft with 4 answers:
+│              • scene count
+│              • tone-flip boundary
+│              • character / visual format
+│              • text rhythm
+│         4. Self-eval against criteria above; if pass, return to parent.
+│
+└── No → do not spawn. Parent uses the frozen ad-format directly.
+```
+
+## Sub-skill run protocol
+
+1. Append a `subSkillRuns` row to the fork's `.growthub-fork/project.md` frontmatter: `subSkill: creative-strategist-frame-analysis`, `startedAt`, target muse path.
+2. Run the helper: `bash helpers/extract-muse-frames.sh <muse.mp4>`.
+3. Batch-Read up to 3 frames at a time. Do not dump raw pixel data back to the parent — summarise into the 4-answer scene map.
+4. Self-evaluate against `selfEval.criteria`. Each attempt recorded to `project.md` + `trace.jsonl` via the `growthub-local` `recordSelfEval` primitive (`cli/src/skills/self-eval.ts`).
+5. When `attempt === maxRetries` without pass, park with `needs_confirmation` in `project.md` and return control to the parent.
+
+## Parent-facing return value
+
+Return to the parent agent:
+
+```yaml
+sceneMap:
+  sceneCount: <int>
+  toneFlipAt: <scene index or "none">
+  visualFormat: <short description>
+  textRhythm: <short description>
+selfEval:
+  attempts: <int>
+  result: pass | parked
+framesDir: /tmp/muse_frames
+```
+
+## Freeze-after-run (when brief ships)
+
+After the parent brief ships with this new muse, freeze the format by adding a row to `templates/ad-formats/INDEX.md` + a new `templates/ad-formats/<new-id>.md`. This sub-skill is only re-spawned when a new muse does not match the growing frozen set.
+
+## What this sub-skill does NOT do
+
+- It does not write the brief. The parent skill owns the brief.
+- It does not install ffmpeg / ffprobe. Those are runtime assumptions (see `runtime-assumptions.md` at the kit root, when present).
+- It does not read outside `/tmp/muse_frames/`. Agents running this sub-skill should not probe other tmp paths.

package/assets/worker-kits/creative-strategist-v1/templates/project.md

@@ -0,0 +1,48 @@
+---
+# .growthub-fork/project.md — session memory primitive (v1)
+#
+# Written by the CLI at init/import time. Append-only, human-readable; sits
+# alongside the machine-readable `trace.jsonl`. Approvals, self-eval outcomes,
+# and sub-skill runs all record here.
+#
+# Replaceable tokens (seeded at init time):
+#   {{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: []
+---
+
+# Project journal — fork `{{FORK_ID}}`
+
+Baseline primitive: `{{KIT_ID}}`. Seeded at `{{STARTED_AT}}` from `{{SOURCE}}` (`{{SOURCE_REF}}`).
+
+This is your cross-session continuity surface. Read the last few entries before every session; append after every material change, approval, and self-eval boundary.
+
+## How to use this file
+
+1. **Session start.** Read the last 3 entries + tail 20 events in `.growthub-fork/trace.jsonl`. State your plan.
+2. **Material change.** Record as a dated bullet (what, why, outcome). Simultaneously append a typed event to `trace.jsonl` via the Fork Sync Agent — never bypass.
+3. **Approval boundary.** Add a row to `approvals` in the frontmatter (verbatim decision).
+4. **Self-eval boundary.** Append to `selfEvalHistory`: `attempt`, `criteria`, `outcome`, `notes`. Enforce `maxRetries: 3`.
+5. **Sub-skill spawn.** Append to `subSkillRuns`: `subSkill`, `startedAt`, `result`.
+
+## Session log
+
+<!-- Append newest entries at the bottom. Format:
+
+### {{YYYY-MM-DD HH:mm UTC}} · {{skill-slug}}
+- **Plan.** What you intend to do.
+- **Changes.** Material changes (each must correspond to a trace event).
+- **Outcome.** Pass / fail / parked. Reference self-eval criteria.
+- **Next.** What the next session should pick up.
+
+-->
+
+_No sessions recorded yet. Populated as the fork is operated._

package/assets/worker-kits/creative-strategist-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-23 18:40 UTC · <skill-slug>
+- **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` (via `appendKitForkTraceEvent`)
+
+```json
+{
+  "ts": "2026-04-23T18:40:00.000Z",
+  "forkId": "<fork-id>",
+  "kitId": "<kit-id>",
+  "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. Do not loop forever.
+2. **Record every attempt.** Even the first pass. Continuity depends on a complete journal.
+3. **Keep `project.md` and `trace.jsonl` in sync.** One without the other is a protocol violation.
+4. **Preserve prior entries.** Append-only. Never rewrite history.
+
+## Bound the blast radius
+
+Evaluate at the smallest unit of work the skill operates on, not only at the end of a multi-step run. The retry ceiling applies to that unit — so a bad attempt does not sink the whole job.
+
+What counts as a "unit of work" is **kit-specific** and lives in that kit's `skills.md` operator runbook — not in this agnostic template. A kit picks its own smallest reversible boundary and documents it in `skills.md`; this template does not prescribe one.
+
+The agnostic SDK (`@growthub/api-contract/skills::SkillSelfEval`) does not encode any domain-specific boundaries — it only carries `criteria[]`, `maxRetries`, and `traceTo`. See `SKILL.md::selfEval.criteria` in this kit for the concrete checks, and `skills.md` for the kit-specific unit of work.

package/assets/worker-kits/creative-strategist-v1/workers/creative-strategist/CLAUDE.md

@@ -439,3 +439,25 @@ This confirmation step costs 10 seconds and prevents hours of rework.
 | Opening Google Drive before file exists | Run the script and confirm DONE first |
 | Asking more than 3 questions | Exactly 3. Prioritize the highest-risk unknowns. |
 | Asking questions already answered in brand kit | Only ask what's genuinely unknown |
+
+---
+
+## 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`** — sub-skill lanes for parallel sub-agents on heavy or narrow work.
+6. **`helpers/<verb>.{sh,mjs,py}`** — safe shell tool layer; promote any inline shell that gets used twice.
+
+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 the current `.growthub-fork/project.md`
+- `growthub skills session init --kit <kit-id>` — (re-)seed session memory
+
+Full user-facing narrative: `cli/assets/worker-kits/growthub-custom-workspace-starter-v1/docs/governed-workspace-primitives.md` (also shipped into any workspace forked from the starter kit).

package/assets/worker-kits/growthub-agency-portal-starter-v1/.env.example

@@ -0,0 +1,53 @@
+# Growthub Agency Portal Starter Kit — environment template
+#
+# The governed workspace remains adapter-first. Keep concrete provider secrets
+# in your local `.env` or deployment provider; do not commit real values.
+
+# Growthub local fork placement
+GROWTHUB_KIT_FORKS_HOME=
+GROWTHUB_GITHUB_HOME=
+
+# Local-first studio shell
+AGENCY_PORTAL_STUDIO_PORT=5173
+
+# Vercel/serverless app lane
+AGENCY_PORTAL_APP_ROOT=apps/agency-portal
+AGENCY_PORTAL_DEPLOY_TARGET=vercel
+AGENCY_PORTAL_APP_URL=http://localhost:3000
+
+# Persistence adapters
+# Supported contract values: postgres, qstash-kv, provider-managed
+AGENCY_PORTAL_DATA_ADAPTER=provider-managed
+DATABASE_URL=
+QSTASH_KV_REST_URL=
+QSTASH_KV_REST_TOKEN=
+
+# Auth adapter
+# Supported contract values: oidc, clerk, authjs, provider-managed
+AGENCY_PORTAL_AUTH_ADAPTER=provider-managed
+AUTH_SECRET=
+AUTH_ISSUER=
+AUTH_CLIENT_ID=
+AUTH_CLIENT_SECRET=
+
+# Payment adapter
+# Supported contract values: stripe, polar, none
+AGENCY_PORTAL_PAYMENT_ADAPTER=none
+PAYMENT_SECRET_KEY=
+PAYMENT_WEBHOOK_SECRET=
+
+# Optional reporting adapter
+AGENCY_PORTAL_REPORTING_ADAPTER=windsor
+WINDSOR_API_KEY=
+
+# Optional Growthub GH app MCP bridge integration adapter
+# Supported contract values: static, growthub-bridge, byo-api-key
+AGENCY_PORTAL_INTEGRATION_ADAPTER=static
+GROWTHUB_BRIDGE_BASE_URL=
+GROWTHUB_BRIDGE_INTEGRATIONS_PATH=/api/mcp/accounts
+GROWTHUB_BRIDGE_ACCESS_TOKEN=
+GROWTHUB_BRIDGE_USER_ID=
+AGENCY_PORTAL_BYO_CONNECTIONS_JSON=
+
+# Optional scheduled job auth
+CRON_SECRET=