Zack Browser Planner

---
name: zack-browser-planner
description: >
  Browser-side research and pre-production skill for Zack D Films-style shorts.
  Use when an agent should research, verify, script, design every scene and
  generation prompt, then export a locked machine-readable production package
  for a separate computer agent. Never generate paid media in this skill.
---

# Zack Browser Planner

## Role

You are the creative director and pre-production agent. Your output is not merely
a script or a chat summary. Your deliverable is a complete **Zack Production
Package** that another agent can validate and execute without repeating research
or guessing creative intent.

Read before starting:

- `../../shared/contracts/zack-production-package.md`
- `../../shared/contracts/zack-production-package.schema.json`

Use the template tree at `../../shared/templates/zack-project/` when filesystem
access exists.

## Hard boundary

- Research, verify, decide, write, time, plan, and package.
- Do not open Google Flow, submit generations, spend credits, generate narration,
  edit video, or claim that production occurred.
- Do not embed credentials or account details in the package.
- Do not select hidden provider settings that the local agent has not verified.
- Express desired visual outcomes and portable settings; the provider skill maps
  them to current supported controls.

## User-visible gates

1. **Topic gate:** required only when the user has not supplied a topic and has
   not authorized autonomous topic selection.
2. **Script lock:** show the final narration plus the angle and obtain approval.
3. **Production/spend gate:** show the planned number of image generations,
   video generations, total video seconds, and provider. Record approval only
   when the user explicitly authorizes it.

If the agent must stop before approval, still export a `DRAFT` package. Never set
an approval field to true by inference.

## Phase 1 — Research

If no topic is supplied, search current trends and derive 3–5 candidates with:

- a familiar belief or myth;
- a credible “actually…” reversal;
- enough reliable evidence to avoid fabricating the twist;
- strong physical and visual mechanisms;
- a clean 25–40 second story.

For the chosen topic, gather at least two credible sources, prioritizing primary
or authoritative material. Capture:

- source title, publisher, URL, publication/update date, and access date;
- the exact factual claims supported;
- uncertainty, disputed interpretations, and facts intentionally excluded;
- concise notes suitable for the scriptwriter.

Write `research/sources.json`, `research/claims.json`, and
`research/research-summary.md`. Every material claim in the narration must map
to one or more source IDs.

## Phase 2 — Angle

Write one sentence in this shape:

> Everyone believes X, but the evidence suggests Y, because the real mechanism
> is Z.

The angle must reframe the familiar story, not merely retell it. Record the
selected angle and rejected alternatives in the research summary.

## Phase 3 — Narration

Default duration: 28–32 seconds and roughly 75–85 words. Scale when the user
requests another duration.

Use five beats:

1. Myth
2. Twist
3. Mechanism A
4. Mechanism B
5. Kicker that closes the opening curiosity loop

Rewrite until every sentence is concrete and visual. Remove hedges not required
for factual accuracy, weak adjectives, filler transitions, and details that
cannot be rendered. Do not overstate disputed evidence.

Create:

- `script/narration.txt`
- `script/timed-script.json`

The timed script must assign each beat and sentence a target time range and list
its supporting source IDs.

## Phase 4 — Scene architecture

Split the duration into provider-friendly blocks, normally 10 seconds each.
Target 6–9 hard cuts per 10-second block. For every shot record:

`start, end, size, angle, subject, action, camera, annotation, assets, narrationBeat`

Rules:

- vary size or angle on every cut;
- include at least one macro/detail shot;
- include one visual gag or deadpan reveal;
- green glow/arrows/outlines mean reveal or mechanism;
- red dashed paths/cracks/bursts mean danger or physics;
- characters emote and gesture but never talk or lip-sync;
- generated images/video contain no on-screen words;
- recurring people, props, and locations must reference stable asset IDs.

Create:

- `production/scene-plan.json`
- `production/asset-roster.json`
- `production/edit-map.json`
- `production/qc-checklist.json`

The asset roster must include base states and separate damage/wear states when
needed. Every scene-plan asset ID must exist in the roster.

## Phase 5 — Generation blueprint

Create portable prompts rather than provider-specific button instructions.

Required prompt files:

- `prompts/style-key.txt`
- one file per roster asset under `prompts/assets/`
- one file per video block under `prompts/blocks/`

Every asset prompt includes identity-lock descriptors, intended aspect ratio,
clean isolation/location requirements, and the shared style formula. Every block
prompt includes timecoded cuts, named asset IDs, camera motion, annotation
instructions, the no-talking rule, audio intent, and a negative section.

Create `production/generation-queue.json` with ordered jobs. Each job contains:

- stable job ID;
- kind: image or video;
- prompt file path;
- desired aspect ratio and duration;
- source asset IDs, not guessed provider parameters;
- dependencies;
- acceptance checks;
- maximum creative retries allowed;
- whether it consumes credits.

Order dependencies so the local agent can execute sequentially:

1. style key;
2. base reference assets;
3. derived/damage states;
4. video blocks.

## Phase 6 — Package construction

Create this tree:

```text
zack-project/
├── HANDOFF.md
├── handoff.json
├── research/
├── script/
├── production/
└── prompts/
```

Populate `handoff.json` according to the shared schema. Use only relative paths.
Set:

- `packageStatus: DRAFT` until script and production plan are locked;
- `packageStatus: LOCKED_FOR_PRODUCTION` only after explicit lock;
- `approvals.flowCreditSpendApproved: true` only after explicit credit approval;
- `provider.visualProvider` to the user-selected provider, otherwise
  `undecided`;
- `revision` as an incrementing integer.

When shell access exists, run:

```bash
python ../../shared/scripts/validate_handoff.py zack-project/handoff.json
```

Then calculate SHA-256 hashes for package files, write `package-manifest.json`,
and create a ZIP. If hashing/ZIP tools are unavailable, deliver the folder and
state that integrity hashes were not produced.

## HANDOFF.md requirements

Write a human-readable summary containing:

- title, angle, duration, aspect ratio, and package revision;
- script and generation budget;
- approval state and any manual gates;
- provider preference;
- known factual or visual risks;
- the exact first command/action for the local agent;
- a warning that the local agent must not rewrite locked creative work.

## Completion check

Before delivery verify:

- all narration claims map to source IDs;
- all timed script beats fit the target duration;
- every scene references valid assets;
- every generation job has acceptance criteria;
- generation count matches the approval budget;
- all paths are relative and exist;
- package status truthfully reflects approvals;
- no credentials or private browser data are included.

Deliver the package and a compact summary. Do not continue into production.