VideoFactory — overseer kit setup

Use the same overseer discipline as other repos, with VideoFactory-specific names for the living docs so multi-repo workspaces stay unambiguous.

Doc mapping (same system, different labels)

The status board is your video queue and grid — phases, videos in play, build status. The kit treats it as the roadmap (SD-17 sync target). governance-sync and handover regeneration keep it honest vs git reality, the same way a software roadmap stays honest.

Renaming is supported. Each repo's .overseer/config.yaml sets docs.handover, docs.roadmap, docs.handover_title, and docs.roadmap_title. MuseHub can use MUSEHUB-ROADMAP.md / MUSEHUB-OVERSEER-HANDOVER.md in the same workspace — no conflict.

Prepared config

Copy or reference:

tests/fixtures/pilot/config-videofactory.yaml

Every field is commented in that file.

Install

KIT=/path/to/overseer-kit
VF=/path/to/videofactory

# Dry-run first (migrate preserves existing living docs)
$KIT/cli/overseer -C $VF init --migrate \
  --from-config $KIT/tests/fixtures/pilot/config-videofactory.yaml \
  --non-interactive --dry-run

# Apply
$KIT/cli/overseer -C $VF init --migrate \
  --from-config $KIT/tests/fixtures/pilot/config-videofactory.yaml \
  --non-interactive

$KIT/cli/overseer -C $VF status --check-footprint

If you already have a Video Production Status Board and handover file with different names, either rename them to match the config or edit docs.handover / docs.roadmap in .overseer/config.yaml to match your filenames before init --migrate.

Mandatory review gates (kit-wide, not optional)

Shipped in every consumer install via templates + .cursor/rules/build-verification-required.mdc:

Agents must not mark a phase DONE on the status board until build verification pass.

Day-to-day (VideoFactory)

1. Open VIDEO_OVERSEER_HANDOVER.md → paste NEXT prompt.
2. Work on feat/<slug> branch.
3. Thinking phase: freeze spec → /freeze-review-loop until pass.
4. Auto phase: build → tests → /build-verification-review until pass.
5. Update status board + handover together → governance-sync --dry-run → commit.
6. PR → merge with Tier-3 authorization.

Hard stops

• No --force --include-preserved on live migrate (pilot rule)
• No merge to main without Tier 3
• No marking videos/phases DONE without build verification pass

Multiple roadmaps? Video queue + software work in one tree

Today (K7): .overseer/config.yaml wires one living-doc pair into governance-sync:

• docs.handover → one relay doc (Video Overseer Handover)
• docs.roadmap → one queue doc (Video Production Status Board)

There is no second auto-synced roadmap/handover pair in the same repo yet. Optional docs.coordination (e.g. CROSS-REPO-COORDINATION.md) is preserved on migrate but is not patched by governance-sync.

Recommended VideoFactory layout (works now)

You do not need a full second roadmap + handover pair for every video. You need:

1. One repo-level status board — master grid of videos and engineering lanes.
2. One repo-level handover — current session relay (whichever lane you are in).
3. One branch per video (your existing habit) — isolates assets, edits, and agent context.
4. One row per video on the status board — honest status vs merged reality.

When you switch from “shipping Threads ep. 42” to “building a new export pipeline,” you change the NEXT prompt in the handover and the active row on the status board. You do not spin up a second synced doc pair unless we add multi-lane config (future K8+).

Future extension (not required for VF install)

A natural kit evolution is docs.lanes[] — named pairs, e.g. production + engineering, each with its own handover/roadmap paths and optional governance-sync --lane. Until then, one synced pair + sections (or a manual second file) is the supported pattern.

Per-video specs: templates, not a thinking model every time

Repetitive video types (Threads in Time + Reels, Trend + verticals, thumbnails, CTA, music, avatar rules, cadence/expression) should be frozen once, not re-specified per video.

Three layers (all live in the VideoFactory repo, not in overseer-kit core)

Gate 1 (freeze): Run /freeze-review-loop when you author or change a template — not on every episode.

Gate 2 (build verification): Run /build-verification-review per video before marking the row DONE — checks implementation against the frozen template ID + instance checklist (export settings, CTA present, music bed, avatar rules, etc.). This is the honesty gate you want for publish-ready work without paying for a thinking model on identical structure every time.

Is a frozen spec necessary for every video?

When is a video “reviewed”?

1. During build — tests / export checks per policy/test-tiers.yaml (you define VF tiers in consumer policy/).
2. Before DONE — mandatory /build-verification-review (always-on Cursor rule).
3. Before publish — human spot-check or your publish pipeline (outside kit).

There is no separate “freeze spec per video” unless that video is a one-off departure from all templates.

Modularity: molding the kit for VideoFactory (and any project)

The kit is repo-agnostic governance, not a VideoFactory runtime. Customization stays in the consumer repo:

You do not fork overseer-kit. You install it into VideoFactory; domain templates and video policy live in VideoFactory. Other repos (MuseHub, Knowtation) use the same kit with different doc names and policy files.

Stub / add-on pattern: Core CLI and adapters expose fixed contracts (init, sync, status, review, governance-sync). Domain-specific behavior is added via consumer policy, preserved docs, and Cursor skills/rules — not by editing kit source unless you are contributing upstream.

Quick decision guide