@growthub/cli 0.7.8 → 0.8.0

package/assets/worker-kits/growthub-custom-workspace-starter-v1/docs/governed-workspace-primitives.md

@@ -0,0 +1,182 @@
+# Governed-Workspace Primitives — How Your Workspace Coordinates Agents at Enterprise Scale
+
+Every workspace you create with Growthub Local — greenfield via `growthub starter init`, or imported via `growthub starter import-repo` / `import-skill`, or materialised from any worker kit via `growthub kit download` — inherits six architectural primitives that make the workspace **self-describing to agents**, **continuous across sessions**, and **auditable for enterprise operators**.
+
+This doc explains **why** each primitive exists and **what it buys your team**. The protocol reference lives at [`docs/SKILLS_MCP_DISCOVERY.md`](../../../../docs/SKILLS_MCP_DISCOVERY.md) at the repo level; this file is written for the human and the agent who are about to operate inside the workspace you just exported.
+
+> TL;DR — The primitives turn a folder of files into a **coordinated execution substrate** that Claude, Cursor, Codex, and custom harnesses all read the same way, that remembers what has happened across sessions, and that refuses to run away on a retry loop.
+
+---
+
+## The problem these primitives solve
+
+Most agent stacks give you one of:
+
+- a raw repo an agent can edit, with no governance;
+- a prompt pack that works once and then decays;
+- a hosted product that locks your customisation behind a vendor.
+
+None of those scale to enterprise work where many agents, many sessions, and many operators act on the same substrate over time. You need a **workspace** that is:
+
+- **discoverable** — agents know what's here without reading everything
+- **continuous** — day 3 of a brief remembers day 1
+- **bounded** — a broken generation doesn't loop forever
+- **auditable** — every material change produces a receipt a human can review
+- **composable** — heavy work spawns into its own lane without poisoning the parent context
+- **safe** — side-effecting shell calls are reviewable files, not one-off prompts
+
+The six primitives below each answer one of those needs, and the Growthub SDK (`@growthub/api-contract/skills`) is the capability-agnostic contract that lets every worker kit, every fork, and every agent harness read them the same way.
+
+---
+
+## 1. `SKILL.md` — The Discovery Entry
+
+**What it is.** A single file at the root of every kit with YAML frontmatter (`name`, `description`, `triggers`, `sessionMemory`, `selfEval`, `helpers`, `subSkills`, `mcpTools`) and a short markdown routing body.
+
+**Why it exists.** Claude / Cursor / Codex agents scan the frontmatter at session start to catalog what's available — they do **not** load the full runbook (`skills.md`) until the user actually engages the skill. That cuts token cost on discovery and lets an agent know, within milliseconds, that your workspace has a Creative Strategist, a Hyperframes studio, and a Postiz social scheduler available — without reading a single line of the detailed operator runbook.
+
+**What it buys you.**
+- Agents route faster and more predictably across many kits.
+- A new team member (or a fresh agent session) gets oriented without re-explaining the repo.
+- Cross-agent compatibility is automatic — the same `SKILL.md` is read identically by Claude, Cursor, Codex, and custom harnesses.
+
+**Enterprise use case.** A creative ops team with 30 worker kits across 6 brands can expose all 30 to every agent surface in the org without a custom integration per tool. The manifest *is* the integration.
+
+---
+
+## 2. Symlinked Pointer — AGENTS.md as Single Source of Truth
+
+**What it is.** The repo root has exactly one authoritative agent contract (`AGENTS.md`). `CLAUDE.md` and `.cursorrules` are plain-text pointers that say "see AGENTS.md". No duplicated rules, no drift.
+
+**Why it exists.** Multi-agent environments drift the second a rule lives in two places. Someone updates the Cursor file and forgets the Claude file. The pointer pattern makes that impossible: there is only one file to edit.
+
+**What it buys you.**
+- Agent rules updated in one place, picked up by every surface on next session load.
+- Audit is simpler — reviewers look at one file, not three.
+- Cross-OS safety — pointer files work on Windows clones where symlinks don't.
+
+**Enterprise use case.** Compliance or InfoSec can sign off on one agent-behaviour file; no more "but the Cursor rules differ from the Claude rules" gaps.
+
+---
+
+## 3. `.growthub-fork/project.md` — Session Memory
+
+**What it is.** A human-readable, append-only journal seeded inside the fork's governed state directory (alongside `fork.json`, `policy.json`, `trace.jsonl`, optional `authority.json`). Written by the CLI at init/import time from the kit's `templates/project.md`.
+
+**Why it exists.** The machine-readable `trace.jsonl` is perfect for systems to replay history, but it is lossy to humans. `project.md` is the narrative layer — "what we tried, what we approved, what we rejected, where we stopped" — so the next session (yours or another agent's) can resume without re-explaining.
+
+**What it buys you.**
+- Day 3 of a multi-day brief opens with yesterday's context already in scope.
+- Approvals, rejections, and self-eval outcomes are preserved across handoffs.
+- Operators who return to a workspace after a month see exactly where work paused.
+
+**Enterprise use case.** Hand-offs between a contract creative team and an in-house team stop losing context. An agent in the in-house session reads the last 3 entries in `project.md` and picks up where the contractor left off.
+
+---
+
+## 4. Self-Evaluation — Bounded Retry Loop
+
+**What it is.** Every `SKILL.md` declares `selfEval.criteria[]` (what good looks like) and `selfEval.maxRetries` (default `3`). The agent runs `generate → apply → evaluate → record`, records each attempt to both `project.md` and `trace.jsonl`, and **must stop** when it hits the retry ceiling. The CLI primitive `recordSelfEval()` (`cli/src/skills/self-eval.ts`) is the single place that writes both surfaces.
+
+**Why it exists.** Unbounded agent loops are the #1 source of cost overruns and silent failures. A governed self-eval contract guarantees every attempt is observable *and* gives the agent a principled stopping point.
+
+**What it buys you.**
+- Runaway jobs are impossible — the ceiling is enforced in the bookkeeping primitive.
+- Every retry produces a receipt a human can read.
+- The Fork Sync Agent's existing `preview → apply → trace` loop is reused, not reinvented — so operators who already trust Fork Sync get the same governance here.
+
+**Enterprise use case.** A marketing ops team approves "at most 3 retries per creative unit" as policy. The SDK enforces it. Failed attempts surface in `project.md` immediately; nobody has to write a watchdog.
+
+---
+
+## 5. Sub-Skills — Parallel Agent Lanes
+
+**What it is.** A kit can declare nested skills under `<kit>/skills/<slug>/SKILL.md`. The parent skill spawns a sub-agent for a sub-skill when the work is (a) heavy enough to pollute the parent's context, or (b) narrow enough to benefit from a specialist lane. Both parent and sub-skill share the same `project.md` journal — so the parent reads the sub-agent's outcome on return without losing continuity.
+
+**Why it exists.** Heavy work (frame extraction, Manim render, PIL compositing, audit passes) shouldn't share the parent's context budget. And specialist work is easier to govern as its own unit.
+
+**What it buys you.**
+- Lower token cost on the parent — the parent stays focused on the user-facing artifact.
+- Clean audit trail — each sub-skill run appends to `project.md::subSkillRuns` with its own start/result.
+- Reusable lanes — a sub-skill like `frame-analysis` can be shared across multiple parent kits.
+
+**Enterprise use case.** Video / creative pipelines get the EDL-per-cut pattern as a sub-skill spawned by the parent brief skill, while non-video kits (CRM, email, SEO) stay on a simple flat loop — one SDK, both patterns, same governance.
+
+---
+
+## 6. `helpers/` — Safe Shell Tool Layer
+
+**What it is.** Small, deterministic scripts (`helpers/<verb>.{sh,mjs,py}`) that agents invoke via one shell call instead of reconstructing a raw pipeline inline.
+
+**Why it exists.** Raw shell in a prompt is fragile, unreviewable, and drifts every session. Moving the same snippets into reviewable files in the kit makes them (a) inspectable, (b) testable, (c) safer — and agents read *one line* ("run helpers/grep-hooks.sh") instead of reconstructing a 4-line pipeline.
+
+**What it buys you.**
+- Reliability — the same inputs always produce the same outputs.
+- Reviewable by security — helpers live in the repo and diff cleanly.
+- Lower cognitive load for agents — one invocation is easier than four.
+
+**Enterprise use case.** A security review of your agent workflow doesn't require reading agent transcripts — it reads the `helpers/` folder once. That's the full list of side-effecting operations.
+
+---
+
+## How the primitives compose: the export guarantee
+
+Every kit export (`scripts/export-worker-kit.mjs --qa`) asserts all six primitives are present before shipping. The assertions are:
+
+1. `SKILL.md` exists with well-formed frontmatter (`name`, `description`).
+2. `templates/project.md` exists (session memory seed).
+3. `templates/self-eval.md` exists (self-eval pattern).
+4. `helpers/README.md` exists (safe-shell convention).
+5. `skills/README.md` exists (sub-skill convention).
+6. `kit.json.frozenAssetPaths` declares all five paths.
+
+A kit that forgets any of these **cannot ship** — the export script refuses to produce a bundle. That guarantee is what makes the primitive layer trustworthy at scale: every workspace your team exports will have them, every time.
+
+---
+
+## How to operate inside this workspace
+
+1. **At session start.** Read `.growthub-fork/project.md` (what happened last time) → `SKILL.md` (what's here) → `skills.md` (how to do the work).
+2. **During work.** After every material change, write a dated bullet to `project.md`'s "Session log" AND call `appendKitForkTraceEvent` for the machine log. The CLI primitive `recordSelfEval` does both in one call — use it.
+3. **On retry.** Every attempt goes to both surfaces. At `attempt === maxRetries`, park with a `needs_confirmation` note and stop.
+4. **On heavy work.** Spawn a sub-skill from `skills/<slug>/` when context isolation helps. The sub-skill shares this fork's `project.md` — no separate journal.
+5. **On side effects.** Use a helper from `helpers/`. If you're about to write raw shell for the third time, promote it to a helper first.
+
+---
+
+## Command surface from inside the workspace
+
+```bash
+# Catalog every SKILL.md reachable from here (root + nested sub-skills)
+growthub skills list [--json]
+
+# Strict shape check — frontmatter + helper/sub-skill path existence
+growthub skills validate
+
+# Read the session memory for this fork
+growthub skills session show [--body]
+
+# (Re-)seed the session memory if it is missing
+growthub skills session init [--kit <id>]
+```
+
+## What this substrate is NOT
+
+- **Not a sandbox.** It's a set of conventions. The filesystem is still yours to edit.
+- **Not a lock-in.** Every primitive file is plain markdown or JSON — readable without Growthub tooling.
+- **Not a replacement for policy.** `policy.json` and the Fork Sync Agent remain the safety envelope. The primitives ride on top.
+- **Not capability-specific.** The SDK contract (`@growthub/api-contract/skills::SkillSelfEval`) is intentionally agnostic. Creative, code, content, CRM, social, audit — all specialise inside their own `skills.md` without changing the contract.
+
+---
+
+## Further reading
+
+- [`../SKILL.md`](../SKILL.md) — the discovery entry for this kit
+- [`../skills.md`](../skills.md) — the operator runbook (the deep how-to)
+- [`../workers/custom-workspace-operator/CLAUDE.md`](../workers/custom-workspace-operator/CLAUDE.md) — the worker agent contract
+- [`../templates/project.md`](../templates/project.md) — session-memory template
+- [`../templates/self-eval.md`](../templates/self-eval.md) — self-evaluation template
+- [`../helpers/README.md`](../helpers/README.md) — safe-shell convention
+- [`../skills/README.md`](../skills/README.md) — sub-skill convention
+- Repo-level protocol reference: `docs/SKILLS_MCP_DISCOVERY.md`
+- SDK source of truth: `@growthub/api-contract/skills`

package/assets/worker-kits/growthub-custom-workspace-starter-v1/helpers/README.md

@@ -0,0 +1,44 @@
+# `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.** They live in the repo; diffs are inspectable.
+- **Deterministic.** Pinned inputs and outputs; no hidden state.
+- **Safer.** Agents call `bash helpers/<verb>.sh <args>` instead of re-assembling a 4-line `ffmpeg` / `grep` / `python` pipeline every session.
+
+Helpers are **not** capability nodes, and they do not cross policy boundaries. Anything that requires auth, hosted execution, or network reach lives in the CLI (`growthub <verb>`) or in MCP routing — not here.
+
+## Convention
+
+```
+helpers/
+├── README.md                 # this file
+├── <verb>.sh                 # short, single-purpose shell scripts
+├── <verb>.mjs                # optional: Node-based helper when shell is too weak
+└── <verb>.py                 # optional: Python-based helper for CSV / data work
+```
+
+Every helper ships with:
+
+1. A one-line comment at the top: what it does + the one command that invokes it.
+2. `set -euo pipefail` (or the language equivalent) — no silent failures.
+3. A matching row in the parent `SKILL.md`'s `helpers[]` frontmatter array:
+   ```yaml
+   helpers:
+     - path: helpers/grep-hooks.sh
+       description: 3-pass hook-library search against the frozen 500-hook CSV
+   ```
+4. A matching entry in `skills.md` pointing to the helper at the place the agent should invoke it (no duplicated shell bodies).
+
+## When to promote an inline snippet into a helper
+
+Promote when any of these are true:
+
+- The same snippet appears in `skills.md` more than once.
+- The snippet has fragile quoting or path interpolation.
+- The snippet calls a side-effecting binary (`ffmpeg`, `git`, `gh`, `osascript`, `npm install`).
+- Multiple sub-skills invoke the same snippet.
+
+## Baseline ships zero helpers on purpose
+
+The starter kit carries the convention only. Individual worker kits (creative-strategist, hyperframes, video-use, etc.) populate `helpers/` with concrete scripts — those are the reference implementations. This keeps the baseline surface minimal and predictable.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/kit.json

@@ -25,6 +25,7 @@
   "frozenAssetPaths": [
     "QUICKSTART.md",
     ".env.example",
+    "SKILL.md",
     "skills.md",
     "output-standards.md",
     "runtime-assumptions.md",
@@ -39,6 +40,10 @@
     "templates/workspace-brief.md",
     "templates/agent-contract.md",
     "templates/deployment-plan.md",
+    "templates/project.md",
+    "templates/self-eval.md",
+    "helpers/README.md",
+    "skills/README.md",
     "examples/workspace-sample.md",
     "docs/starter-kit-overview.md",
     "docs/fork-sync-integration.md",
@@ -51,7 +56,8 @@
     "studio/src/App.jsx",
     "studio/src/app.css",
     "growthub-meta/README.md",
-    "growthub-meta/kit-standard.md"
+    "growthub-meta/kit-standard.md",
+    "docs/governed-workspace-primitives.md"
   ],
   "setupPaths": {
     "quickstart": "QUICKSTART.md",
@@ -66,6 +72,7 @@
       "kit.json",
       ".env.example",
       "bundles/growthub-custom-workspace-starter-v1.json",
+      "SKILL.md",
       "skills.md",
       "workers/custom-workspace-operator/CLAUDE.md",
       "brands/_template/brand-kit.md",
@@ -76,8 +83,15 @@
       "output/README.md",
       "studio",
       "templates",
+      "templates/project.md",
+      "templates/self-eval.md",
+      "helpers",
+      "helpers/README.md",
+      "skills",
+      "skills/README.md",
       "docs",
-      "growthub-meta"
+      "growthub-meta",
+      "docs/governed-workspace-primitives.md"
     ]
   },
   "bundles": [

package/assets/worker-kits/growthub-custom-workspace-starter-v1/skills/README.md

@@ -0,0 +1,55 @@
+# `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. Use sub-skills when work is:
+
+- **Heavy** — isolating the context keeps the parent lean (e.g. frame extraction, Manim render, PIL compositing).
+- **Narrow** — a specialist lane is clearer than a generalist lane (e.g. hook-library lookup, scene-module assembly).
+
+Sub-skills are **not** CLI commands and **not** capability nodes. They are local-to-the-kit Claude/Cursor/Codex skills, discovered by walking the tree.
+
+## 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 `SKILL.md` follows the same shape as the parent (see `@growthub/api-contract/skills::SkillManifest`):
+
+```yaml
+---
+name: <slug>
+description: <trigger + capability, <=1024 chars>
+triggers: [ ... ]
+sessionMemory:
+  path: .growthub-fork/project.md      # same fork journal — sub-skills do not branch the journal
+selfEval:
+  criteria: [ ... ]
+  maxRetries: 3
+  traceTo: .growthub-fork/trace.jsonl
+helpers: []
+mcpTools: []
+---
+```
+
+## Parallelism
+
+A parent skill spawns 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 the fork's `project.md::subSkillRuns` frontmatter so the parent can read the outcome on return.
+
+Example wiring:
+
+```
+creative-strategist-v1/
+└── skills/
+    └── frame-analysis/
+        └── SKILL.md   — parent delegates Step 2b (ffprobe + ffmpeg + frame read)
+```
+
+## Baseline ships zero sub-skills on purpose
+
+The starter kit carries the convention only. Individual worker kits populate `skills/` as they discover specialist lanes during operation.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/templates/project.md

@@ -0,0 +1,55 @@
+---
+# .growthub-fork/project.md — session memory primitive (v1)
+#
+# This file is written by `growthub starter init` / `import-repo` / `import-skill`
+# (and by `growthub skills session init` inside an existing fork). It is the
+# human-readable continuity surface across agent sessions — it sits alongside
+# the machine-readable `trace.jsonl` without duplicating it.
+#
+# Rules:
+#   - Append-only. Never delete a dated entry; cross it out instead.
+#   - Every material change to the fork gets a paragraph here AND a typed event
+#     in `.growthub-fork/trace.jsonl`. The two are kept in sync.
+#   - Approvals, rejections, and self-eval outcomes all land 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. Return here at the start of every session; append to it at the end of every session and at every self-eval boundary.
+
+## How to use this file
+
+1. **Session start.** Read the last 3 entries in the "Session log" below + tail 20 events in `.growthub-fork/trace.jsonl`. State what you plan to do.
+2. **Material change.** Record the change as a dated bullet in "Session log" (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 above (include the operator's decision verbatim).
+4. **Self-eval boundary.** Append to `selfEvalHistory` in the frontmatter: `attempt`, `criteria`, `outcome`, `notes`. Enforce `maxRetries: 3` from the active skill's frontmatter.
+5. **Sub-skill spawn.** Append to `subSkillRuns` in the frontmatter: `subSkill`, `startedAt`, `result`.
+
+## Session log
+
+<!-- Append entries below, newest at the bottom. Format:
+
+### {{YYYY-MM-DD HH:mm UTC}} · {{skill-slug}}
+- **Plan.** What you intend to do this session.
+- **Changes.** What you actually did (material changes only; each must correspond to a trace event).
+- **Outcome.** Pass / fail / parked. Reference the self-eval criteria you 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-custom-workspace-starter-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/growthub-custom-workspace-starter-v1/workers/custom-workspace-operator/CLAUDE.md

@@ -4,28 +4,50 @@ You are the Custom Workspace Operator — the agent wired to this Growthub custo
 
 ## Inputs you always have
 
+- `SKILL.md` — the routing menu. **Read first on every session.**
+- `skills.md` — the operator runbook. Progressively disclosed from `SKILL.md`.
 - `kit.json` — the manifest, schema v2, family `studio`
 - `bundles/growthub-custom-workspace-starter-v1.json` — the bundle contract
 - `brands/_template/brand-kit.md` — empty brand scaffold
 - `brands/growthub/brand-kit.md` — reference brand
 - `studio/` — the Vite UI shell (React + Vite 5)
+- `templates/project.md` — session-memory template (seed for `.growthub-fork/project.md`)
+- `templates/self-eval.md` — self-evaluation pattern
+- `helpers/` — safe shell tool layer (starts empty; promote inline shell here over time)
+- `skills/` — nested sub-skill convention (parallel sub-agents for heavy or narrow work)
 - `workers/custom-workspace-operator/CLAUDE.md` — this file
-- `.growthub-fork/fork.json`, `.growthub-fork/policy.json`, `.growthub-fork/trace.jsonl` — the fork state the CLI registered for this workspace
+- `.growthub-fork/fork.json`, `.growthub-fork/policy.json`, `.growthub-fork/trace.jsonl`, `.growthub-fork/project.md` — the fork state the CLI registered for this workspace
+
+## The six primitives (architectural, carried into every exported fork)
+
+1. **`SKILL.md`** — single source of truth + discovery entry (primitive #1).
+2. **Symlinked pointer** — repo-root `AGENTS.md` is the authoritative agent contract; `CLAUDE.md` and `.cursorrules` point to it (primitive #2).
+3. **`.growthub-fork/project.md`** — session memory, append-only, human-readable; written from `templates/project.md` at init time (primitive #3).
+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/<slug>/SKILL.md`** — sub-skill + parallel-agent convention (primitive #5).
+6. **`helpers/<verb>.{sh,mjs,py}`** — safe shell tool layer; agents call one script instead of reconstructing raw commands (primitive #6).
 
 ## Non-negotiables
 
+- Read `SKILL.md` first, then `.growthub-fork/project.md`, then `skills.md`.
 - Never modify files under `skills/`, `custom/`, `.env`, `.env.local`, or any path listed in `policy.untouchablePaths`.
 - Never perform a destructive remote operation (`push --force`, `reset --hard`) without explicit user confirmation.
-- Every significant action appends an event to `trace.jsonl` via the Fork Sync Agent — do not bypass.
+- Every significant action appends an event to `trace.jsonl` via the Fork Sync Agent AND a dated entry to `project.md` — do not bypass; do not write one without the other.
 - Respect `policy.autoApprove` + `policy.autoApproveDepUpdates`. If a change is outside scope, mark it `needsConfirmation` and park.
+- Self-eval hard ceiling: `maxRetries: 3` per skill run. At the ceiling, stop and park with a `needs_confirmation` note in `project.md`.
 
 ## Execution verbs
 
 - `growthub starter init --name <workspace> --out <path>` — scaffold a new workspace from this starter
+- `growthub starter import-repo <owner/repo> --out <path>` — scaffold from a GitHub repo
+- `growthub starter import-skill <owner/repo/skill> --out <path>` — scaffold from a skills.sh skill
 - `growthub kit fork status <fork-id>` — check drift
 - `growthub kit fork heal <fork-id> [--dry-run | --background]` — propose + apply heal
 - `growthub kit fork policy --fork-id <fork-id> --set <key=value>` — configure safety envelope
 - `growthub kit fork trace --fork-id <fork-id> --tail N` — replay the event log
+- `growthub skills list [--json]` — enumerate every SKILL.md in this fork (root + nested `skills/`)
+- `growthub skills validate` — check SKILL.md frontmatter + helper/sub-skill paths
+- `growthub skills session show` — print the current `.growthub-fork/project.md`
 
 ## Output contract
 

package/assets/worker-kits/growthub-email-marketing-v1/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: growthub-email-marketing-v1
+description: "Self-contained workspace for Growthub-focused email marketing — brand-aware email campaigns, nurture flows, drip sequences. Use when the user says: \"email campaign\", \"drip sequence\", \"email marketing strategist\". Session memory tracks brand inputs, list segments, and subject-line self-eval pass/fail history."
+triggers:
+  - email marketing
+  - email marketing strategist
+  - fork growthub-email-marketing-v1
+progressiveDisclosure: true
+sessionMemory:
+  path: .growthub-fork/project.md
+selfEval:
+  criteria:
+    - Operator contract (workers/email-marketing-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: []
+subSkills: []
+mcpTools: []
+---
+
+# Growthub Agent Worker Kit — Email Marketing Strategist
+
+Discovery entry + routing menu for the `growthub-email-marketing-v1` worker kit. Family: `operator`. Agent contract: `workers/email-marketing-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: "growthub-email-marketing-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 growthub-email-marketing-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/email-marketing-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/email-marketing-strategist/CLAUDE.md` — agent contract

package/assets/worker-kits/growthub-email-marketing-v1/bundles/growthub-email-marketing-v1.json

@@ -55,12 +55,19 @@
     "templates/broadcast-formats/lead-magnet-traffic.md",
     "templates/broadcast-formats/showcase-proof.md",
     "templates/broadcast-formats/engagement-nudge.md",
-    "templates/broadcast-formats/activation-booking.md"
+    "templates/broadcast-formats/activation-booking.md",
+    "SKILL.md",
+    "templates/project.md",
+    "templates/self-eval.md",
+    "helpers/README.md",
+    "skills/README.md"
   ],
   "optionalPresets": [],
   "export": {
     "folderName": "growthub-agent-worker-kit-email-marketing-v1",
     "zipFileName": "growthub-agent-worker-kit-email-marketing-v1.zip"
   },
-  "activationModes": ["export"]
+  "activationModes": [
+    "export"
+  ]
 }

package/assets/worker-kits/growthub-email-marketing-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.