@growthub/cli 0.7.9 → 0.8.1

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

@@ -0,0 +1,122 @@
+---
+name: growthub-custom-workspace-starter
+description: Baseline primitive for every Growthub governed workspace. Routing menu for the Custom Workspace Operator — delegates to the operator runbook (`skills.md`), the session-memory template (`templates/project.md`), the self-evaluation contract (`templates/self-eval.md`), the safe-shell helpers layer (`helpers/`), and the parallel sub-skill convention (`skills/`). Invoked when the user starts a greenfield workspace via `growthub starter init`, imports a GitHub repo or skills.sh skill via `growthub starter import-repo`/`import-skill`, or downloads this kit directly via `growthub kit download`.
+triggers:
+  - greenfield workspace
+  - starter init
+  - custom workspace
+  - import repo
+  - import skill
+  - baseline primitive
+progressiveDisclosure: true
+sessionMemory:
+  path: .growthub-fork/project.md
+selfEval:
+  criteria:
+    - Scaffolded tree matches kit.json frozenAssetPaths.
+    - .growthub-fork/ carries fork.json + policy.json + trace.jsonl.
+    - .growthub-fork/project.md seeded from templates/project.md.
+    - Operator contract read before any material change.
+  maxRetries: 3
+  traceTo: .growthub-fork/trace.jsonl
+helpers: []
+subSkills: []
+mcpTools: []
+---
+
+# Custom Workspace Starter — Baseline Primitive
+
+Every Growthub governed workspace is materialised from this kit. The kit ships the `.growthub-fork/` contract (identity, policy, trace, optional authority) plus the six primitive layers Claude/Cursor/Codex agents operate against:
+
+1. **`SKILL.md`** — this file. Discovery entry + routing menu. Always loaded first; the full operator runbook (`skills.md`) is disclosed progressively when work begins.
+2. **`skills.md`** — the deep operator runbook. Everything the operator agent needs to actually customise the workspace. Unchanged from v1.
+3. **`templates/project.md`** — session-memory template. On `growthub starter init` and `growthub starter import-*`, the CLI copies this to `.growthub-fork/project.md` so every fork starts with an append-only editing history alongside the machine-readable `trace.jsonl`.
+4. **`templates/self-eval.md`** — self-evaluation pattern. Describes the generate → render → evaluate → retry (≤3) loop that mirrors the Fork Sync Agent's preview → apply → trace lifecycle.
+5. **`helpers/`** — safe shell tool layer. Scripts an agent calls via one shell invocation instead of reconstructing raw commands. Populated per fork; the baseline ships conventions only.
+6. **`skills/`** — nested sub-skill convention. Each sub-directory is a full `SKILL.md`-addressable sub-skill that a parent agent can spawn in parallel for heavy or narrow tasks.
+
+## When to use this skill
+
+- User says: "start a new custom workspace", "scaffold a fork", "import this repo into a workspace", "bring this skill into a fork".
+- An agent has just been dropped into a directory that contains `.growthub-fork/fork.json` — this is the SKILL.md that routes the agent into the right operator flow for that fork.
+
+## Decision tree
+
+```
+Did the user ask to CREATE a new workspace?
+├── Yes → route to `growthub starter init --out <path>` (greenfield)
+│         or `growthub starter import-repo <owner/repo> --out <path>`
+│         or `growthub starter import-skill <owner/repo/skill> --out <path>`
+│         Afterwards: open the fork + read `.growthub-fork/project.md` (just seeded).
+│
+└── No  → the fork already exists. Read in this order:
+          1. `.growthub-fork/project.md`      — session memory (your own prior state)
+          2. `SKILL.md` (this file)           — routing menu
+          3. `skills.md`                      — operator runbook
+          4. `workers/custom-workspace-operator/CLAUDE.md` — agent contract
+          5. `.growthub-fork/policy.json`     — what you may touch
+          6. `.growthub-fork/trace.jsonl`     — machine history (tail 20)
+```
+
+## Self-evaluation (primitive #4)
+
+After each material change to the fork:
+
+1. Append an entry to `.growthub-fork/project.md` (human-readable: what you tried, why, outcome).
+2. Append a typed event to `.growthub-fork/trace.jsonl` via `appendKitForkTraceEvent` — never bypass.
+3. Check against `selfEval.criteria` above. If failed, retry up to `maxRetries: 3` — then stop and park with a `needs_confirmation` note in `project.md`. Do not loop indefinitely.
+
+See `templates/self-eval.md` for the concrete template.
+
+## Session memory (primitive #3)
+
+`.growthub-fork/project.md` is the single cross-session continuity surface. Write to it:
+
+- before you begin each session (what you plan),
+- after each material change (what you did),
+- at approval boundaries (what the user approved / rejected),
+- at self-eval boundaries (retry count, outcome).
+
+`project.md` is human-readable; `trace.jsonl` is machine-readable. The two are kept in sync by the CLI's fork primitives — you never pick one over the other.
+
+## Sub-skills (primitive #5)
+
+If this fork declares sub-skills under `skills/<slug>/SKILL.md`, list them below. Spawn a sub-agent per sub-skill only when the work is (a) heavy enough that isolating context helps, or (b) narrow enough that a specialist lane is clearer than a generalist lane.
+
+(None declared at the baseline; forks populate this as the workspace evolves.)
+
+## Helpers (primitive #6)
+
+Helpers live under `helpers/`. When an existing shell snippet in `skills.md` is re-used in multiple sessions, extract it into `helpers/<verb>.sh`, add a row to `helpers/README.md`, and add an entry to this frontmatter's `helpers[]` array. Agents then call one shell file rather than reconstructing the snippet — safer, reviewable, consistent.
+
+(None declared at the baseline; see `helpers/README.md` for the pattern.)
+
+## MCP routing (optional)
+
+If a concrete MCP server is available for this fork, list its tool IDs in `mcpTools[]`. Growthub's baseline ships declarative-only routing vocabulary — the CLI does not run an MCP server at v1. This field lets future MCP integration light up additively without a breaking change.
+
+## Execution verbs (from `workers/custom-workspace-operator/CLAUDE.md`)
+
+- `growthub starter init --name <workspace> --out <path>` — scaffold a new workspace from this kit
+- `growthub starter import-repo <ref> --out <path>` — scaffold from a GitHub repo
+- `growthub starter import-skill <ref> --out <path>` — scaffold from a skills.sh skill
+- `growthub kit fork status <fork-id>` — drift check
+- `growthub kit fork heal <fork-id> [--dry-run | --background]` — preview + 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 (this fork + nested)
+- `growthub skills validate` — check SKILL.md frontmatter + helper/sub-skill paths
+- `growthub skills session show` — print the current `.growthub-fork/project.md`
+
+## Related files
+
+- `skills.md` — operator runbook (deep)
+- `QUICKSTART.md` — first-run steps
+- `runtime-assumptions.md` — what the kit expects from the host
+- `output-standards.md` — where outputs go
+- `validation-checklist.md` — pre-flight checklist
+- `templates/project.md` — session-memory template (seed for `.growthub-fork/project.md`)
+- `templates/self-eval.md` — self-evaluation template
+- `helpers/README.md` — helpers convention
+- `skills/README.md` — sub-skills convention
+- `workers/custom-workspace-operator/CLAUDE.md` — agent contract

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

@@ -9,13 +9,20 @@
   "briefType": "custom-workspace-starter",
   "capabilityType": "worker",
   "executionMode": "export",
-  "activationModes": ["export"],
+  "activationModes": [
+    "export"
+  ],
+  "export": {
+    "folderName": "growthub-custom-workspace-starter-v1",
+    "zipFileName": "growthub-custom-workspace-starter-v1.zip"
+  },
   "publicExampleBrandPaths": [
     "brands/growthub/brand-kit.md"
   ],
   "requiredFrozenAssets": [
     "QUICKSTART.md",
     ".env.example",
+    "SKILL.md",
     "skills.md",
     "output-standards.md",
     "runtime-assumptions.md",
@@ -30,6 +37,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",
@@ -42,6 +53,7 @@
     "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"
   ]
 }

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.