# Nexus Viral Run

> Human-triggered runner for the nexus-viral 1→8 short-form pipeline. Composes brief → Gate A → copy → generate_video → poll → Gate B → derive_cuts as one gated agent session over the real studio/MCP tools. Draft-first spend; every gate aborts BEFORE any paid generation. NO publish primitive — releasing cuts is a separate human-gated route (WS4). Use when a human wants to take one viral idea from brief to inert, review-ready platform cuts in a single action.

- Skill: `cleanexpo/nexus-viral-run` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/nexus-viral-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/nexus-viral-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/nexus-viral-run

---


# nexus-viral-run

The runner that turns one idea into 1 hero video + N inert platform cuts, with a
deterministic gate between every stage and no way to spend or publish without an
explicit human action. It is an **agent session**, not a daemon — a human triggers
it; there is no cron, no queue, no autonomous loop.

Driver: `scripts/nexus-viral-run.ts` (`runNexusViral(options, deps)`).

## When to use

- A human wants a full 1→8 run in one action: brief → gated hero generation →
  gated derivation into platform-native cuts, landing as `queued_human_gated`
  (inert, unpublished) drafts ready for the WS4 release surface.
- Trend/competitor research and hook authoring already happened (or are folded
  into the brief) — this skill is the **execution spine**, not the ideation.

Do NOT use to publish, schedule, or push anything to a platform. This skill has
no publish capability by construction (phase-1 boundary).

## Stage sequence (each gate precedes the next spend)

| #   | Stage       | Backing function / tool                                              |
| --- | ----------- | -------------------------------------------------------------------- |
| 1   | brief       | `loadBrief(orgId, topic)` — org-grounded angle + facts               |
| A   | **Gate A**  | `runBriefGrill` (LLM producer) → `assertGatePassed(ref,'brief')`     |
| 2   | copy        | senior-copywriter-style producer (see resolution below)              |
| 3   | generate    | `executeStudioTool('generate_video', …)` — draft, 9:16, 6s, 1 var    |
| 4   | poll        | `executeStudioTool('get_job', { id })` until rendered/failed/timeout |
| B   | **Gate B**  | `runBroadcastGrill` → `assertGatePassed(heroId,'broadcast')`         |
| 5   | derive_cuts | `executeStudioTool('derive_cuts', …)` → `queued_human_gated` cuts    |
|     | report      | structured `NexusViralRunReport` (stages, gate verdicts, refs)       |

`generate_video`, `get_job`, `derive_cuts` are the real creative\_\* studio tools
(`lib/services/ai/studio-tools/index.ts`). Gate A/B are WS3
(`lib/video/gates/`): `runBriefGrill` / `runBroadcastGrill` are LLM producers
that write a `MarketingAgencyQaReport` row; `assertGatePassed` is the
deterministic, fail-closed enforcer that only resolves on a persisted `passed`
row. An agent's "8/8 verdict" is inert until that enforcer reads it.

## Grounding (REAL IMAGES ONLY)

`generate_video` inherits the grounded-by-default mandate — it seeds from owned
references (`public/reference-library/manifest.json` + the private bucket
`reference-library-private`). If the prompt's auto-detected industry has no owned
references, the generate stage aborts with `GroundingBlockedError` ("No owned references
for this subject — add real photos to the reference library first.") — treat this as a
third gate, not a retryable pipeline failure. The fix is ingesting real photos
(`POST /api/admin/private-refs`) or extracting frames from owned video via the media
worker, never bypassing it. `useReferences: false` is the sole audited escape hatch and
stamps results UNGROUNDED. For carpet-cleaning topics the carpet-style-v1 LoRA (trigger
`ccwcarpet`, `lib/services/ai/image/trained-loras.json`) auto-applies. See
`.claude/rules/real-images-only.md` + `grounded-visuals`. Direct provider calls fail CI.

## Gate discipline (the point of this skill)

- Gate A runs on the **brief, before any generation**. A FAIL — or a fail-closed
  `assertGatePassed` throw — aborts the run and prints `blockedReasons`. No
  `generate_video` call is made, so **no spend occurs on a failed brief**.
- Gate B runs on the **rendered hero, before derivation**. A FAIL aborts before
  `derive_cuts`; nothing is derived and nothing reaches the release surface.
- FAIL is terminal here — no auto-retry / re-judge loop. Re-running is a
  deliberate human action.

## Spend safety — the live generate STOP

`generate_video` is real provider spend (~$1.69 draft + renders, spec §13). The
driver is safe by default:

- **Default (no `--live`)** → full **dry-run**: gates + copy run, but
  `generate_video` is never called. The report terminates cleanly at `generate`.
- **`--live` without confirmation** → prints a documented **STOP** and no-ops the
  generate step. Never spends.
- **`--live --confirm-spend`** (or `NEXUS_VIRAL_CONFIRM_SPEND=1`) → the single
  real path. This is the founder's deliberate, watched morning proof — one live
  1→8 draft run. An overnight/automated agent MUST NOT set this.

```bash
# dry-run (safe, default) — exercises the whole composition, spends nothing
npx tsx scripts/nexus-viral-run.ts --org <orgId> --user <userId> --topic "…"

# live proof — human-watched, deliberate spend
npx tsx scripts/nexus-viral-run.ts --org <orgId> --user <userId> --topic "…" \
  --campaign <campaignId> --live --confirm-spend
```

## nexus-copywriter resolution ([UNCONFIRMED] → resolved)

The spec named a `nexus-copywriter` **agent** for the copy stage. **It does not
exist** — only the `senior-copywriter` skill does (verified). The copy stage
therefore delegates to a senior-copywriter-style producer over `getAIProvider()`
(the headless-callable equivalent), injected as `deps.generateCopy`. No phantom
agent is referenced. For a rich, brand-grounded human session, invoke the
`senior-copywriter` skill to author the hook/captions and feed them in.

## Boundaries (never crossed)

- No publish/schedule primitive is imported or called. Cuts land
  `queued_human_gated` and stay inert until the WS4 human release route acts.
- No autonomous loop / daemon / cron.
- Every effect is injected via `NexusViralRunDeps`, so the driver is fully
  unit-mockable with no network, DB, or paid call.

## Verification

`__tests__/nexus-viral/run.test.ts` proves: happy path threads all stages; Gate A
FAIL aborts before `generate_video`; Gate A fail-closed enforcement aborts before
spend; Gate B FAIL aborts before `derive_cuts`; default is a no-spend dry-run.