video-workbench/VIDEO_WORKBENCH.md

VIDEO_WORKBENCH.md

1. Workspace Identity

This project is the local execution workspace for dimensional video and slide-style output.

It turns accepted GPT V2 planning Markdown and user-provided sources into project notes, local execution plans, visual-system assets, slide/page execution folders, generated assets, and handoff material. It is optimized for practical continuation, not heavy governance.

2. Collaboration Roles

GPT / ChatGPT   = stage 0-5 planning Markdown, outlines, visual systems, page/shot skeletons
User            = decisions, accepted inputs, source/reference material
Codex           = stage 6+ execution planning, Prompt Advisor work, visual-system materialization, iteration, local assets

GPT V2 does not provide final image prompts, Codex JSON, output paths, task lists, or image generation parameters. Codex should not request those from GPT as missing inputs.

Codex should not rewrite GPT planning into duplicate project content. The accepted planning files belong in the project intake/ directory, and Codex turns them into local execution decisions in execution-plan.md.

3. Project Layout

All video or slide-style work lives under projects/:

projects/
  project-id/
    project.md
    intake/
    execution-plan.md
    visual-system/
      visual-system.md
      refs/
      iterations/
    slides/
      slides.md
      s01/
      s02/
    tasks/

Use root-level handoff/ for repository-level, cross-project, series-level, or context-window handoff notes.

Use docs/cases/ for Codex-side local case patterns extracted from old real GPT cases. These documents preserve reusable structure, granularity, asset layering, speaker-note style, and review dimensions. They do not restore old GPT final prompts, Codex JSON execution packages, output paths, or global text-rendering rules.

Do not split projects into active, completed, abandoned, series, or standalone folders. Status and series membership belong in project files because both can change during real production.

If a series needs more structure, create projects/_series/ when the first real series needs it.

4. Project Notes

projects/<project>/project.md is a lightweight Codex-maintained note. It should record:

• project status;
• medium type;
• source and reference links;
• which intake/ files are GPT V2 planning Markdown, source notes, reference notes, or background notes;
• current execution focus;
• key local execution files;
• next action.

It should not duplicate the full outline, storyboard, page design, shot design, or execution plan.

5. Execution Plan

Visual projects must have:

projects/<project>/execution-plan.md

This is a living Codex-maintained execution control file. It records:

• the current medium branch;
• the current execution focus;
• which visual-system assets need materialization;
• the current small-batch iteration strategy;
• which sNN units are in the active batch;
• the current round;
• the next decision.

It should not repeat the project ID, full intake file index, or project map from project.md.

6. Intake

projects/<project>/intake/ holds material provided or accepted by the user:

• GPT V2 stage 0-5 planning Markdown;
• outlines;
• storyboards, page skeletons, or shot skeletons;
• background notes;
• reference images, audio notes, or source pointers.

File naming can be agreed during the first real project. Do not create a rigid naming scheme before the real GPT outputs are known.

Intake Heading Repair

When copied GPT / LLM intake Markdown has broken heading hierarchy, use the installed fix-title Skill as an external repair capability, but keep the calling protocol local to Video Workbench.

Local calling rules:

• Repair work must run through a real Agent / subagent invocation when the runtime provides one.
• The main session should pass the source file paths, mode=artifact or mode=discussion, the fix-title skill path, and the output directory to the worker.
• The main session should not build semantic heading plans or apply heading edits itself when an Agent carrier is available.
• For files under projects/<project>/intake/, output must go under:

projects/<project>/intake-repair/fix-title-YYYY-MM-DD-<short-slug>/

The repair output package should contain:

<stem>.heading-map.json
<stem>.heading-plan.json
<stem>.fixed.md
<stem>.heading-report.md
fix-title-batch-report.md

If repaired files replace originals, first copy the original Markdown files to:

projects/<project>/intake-repair/fix-title-YYYY-MM-DD-<short-slug>/originals-before-replacement/

Main-session responsibilities after the worker returns:

• verify the returned files exist;
• inspect the heading map, plan, fixed copy, per-file report, and batch report;
• check that intended artifact files have one clear document title unless the report flags an intentional appended artifact;
• check that ambiguous appended artifacts are reported instead of silently merged;
• decide whether to replace originals, and write replacement notes when replacement happens.

Do not put durable intake repair output under tmp/. Keep reusable automation changes in skills-vault; Video Workbench owns only the local invocation protocol, project evidence, replacement notes, and supplier-request records.

7. Visual System

Visual projects use:

projects/<project>/visual-system/
  visual-system.md
  refs/
  iterations/

visual-system.md is the single record for the project's public visual system. It should cover:

• the current accepted visual system;
• materialization targets;
• trial prompts and generated reference assets;
• review notes;
• failure attribution;
• next action.

Use optional subfolders only when the project needs them:

visual-system/characters/
visual-system/scenes/
visual-system/templates/
visual-system/diagrams/
visual-system/backgrounds/

Do not create a separate makeup-still/ directory. Character anchors and identity references belong under visual-system/.

After a character anchor stage is accepted, clean the character workspace before scene generation:

• keep only current usable character references under visual-system/characters/;
• record the active references and their intended use in visual-system/characters/character-reference-registry.md;
• move historical candidates, rejected versions, prompt/review process files, previews, masks, chroma sources, and other intermediate files to archive/characters/;
• do not use files under archive/characters/ as default prompt references unless a repair task explicitly reopens them.

For identity-critical shots, prompt specs must choose the person reference from the active character registry. Text description can clarify the role, but it does not replace the active character image reference.

8. Slides And Shots

Use slides/ as the execution unit area for both video shots and PPT-style pages.

projects/<project>/slides/slides.md is the unit execution fact table. It records each page or shot's source, batch, current prompt version, current image version, review state, acceptance state, and notes. Project-level iteration strategy belongs in execution-plan.md.

Each slides/sNN/ folder keeps one slide, page, or shot together:

slides/
  slides.md
  s01/
    s01-metadata.json
    s01-unit-spec.md
    s01-visual-brief.md
    s01-v1-prompt.md
    s01-v1-image.png
    s01-v1-review.md
    s01-v2-prompt.md
    s01-v2-image.png
    s01-v2-review.md

All files inside sNN/ must carry the sNN prefix. Iteration files use sNN-vN-type.ext, so files from the same version sort together.

New task execution must append a new slide version instead of overwriting an existing one. Resolve the next unused vN from existing sNN-v*-* files in the slide folder, and treat incomplete or superseded earlier versions as historical evidence rather than paths to reuse.

Slide Task Orchestration

For long or context-heavy production, use local slide task orchestration:

docs/workflows/slide-task-orchestration.md
docs/workflows/slide-task-templates.md

Project-local task records go under:

projects/<project>/tasks/<task-id>/

Task records are for orchestration only. Durable slide artifacts remain under slides/sNN/.

Roles:

• Main session: receives user instructions, defines worker profile / running mode / slide scope, starts child sessions, and reads handoffs.
• Child session: reads shared context, writes per-slide briefs, starts one slide agent per slide, and writes a child-session handoff.
• Slide agent: handles exactly one slide, writes the prompt, generates only when allowed, writes review only when required, and returns compact status.

Defaults:

• Worker profile for current video / MV work: video-slide-production.
• Child session capacity: at most 3 slides.
• Slide agent capacity: exactly 1 slide.
• Execution is sequential by default; do not run child sessions or slide agents in parallel unless the user explicitly changes the rule.
• Future ppt-page-production work is reserved and may use docs/cases/, but it must not inherit video-slide rules blindly.

The user controls task running mode:

• prompt only: create briefs and prompts; do not generate images.
• prompt and generate: create briefs and prompts, then generate images for the task's recorded slide scope.

Task-level generation instructions count as user approval for the named scope and mode. Core, repair, identity-heavy, or otherwise high-risk slides may still pause if the task plan says they require sampling or explicit review.

Visual-system rules:

• visual-system/ is the production authority.
• Style continuity must use visual-system/style/style-prompt-master.md.
• Character continuity must use visual-system/characters/character-reference-registry.md and active character reference images.
• Visible character identity cannot be generated from text-only prompts when identity matters.
• Slide prompts must use the gpt-image-2 Skill Advisor / host-native workflow.

Review rules:

• Review defaults to local-only.
• Do not call Minimax MCP or other external vision/review services unless the user explicitly authorizes that task.
• Non-core generated slides can be tracked in tasks/<task-id>/task-log.md and slides/slides.md instead of a full per-slide review.

9. Investigations

Use investigations/ for research reports, experiments, comparisons, draft workflow proposals, and other reviewable evidence.

tmp/ is deprecated and should not receive new durable work. Short-lived scratch material should either be deleted or promoted into investigations/ when it becomes useful evidence.

garden-gpt-image-2/ remains reserved for tool-level image prompt or workflow traces when that path is used.

10. Word Budget

Use the default standard:

1 minute = about 220 Chinese characters of voiceover
10 minutes = about 2200 Chinese characters

Adjust only when the user specifies a different narration speed.

11. Asset Policy

Image and audio generation can be automated when available skills or APIs are appropriate.

Video generation from images remains manual or semi-manual for now because output reliability varies.

Editing and publishing are human-controlled unless explicitly automated later.

Codex is the default prompt owner for final image prompts in this workspace, but final prompts must be produced through the gpt-image-2 Skill workflow rather than direct freehand drafting. GPT V2 planning Markdown remains a source specification, not a final prompt.

For project-bound image prompts, Codex must:

• run the gpt-image-2 mode check before prompt work;
• read the relevant Skill template or reference file;
• save the rendered prompt/spec as a reviewable project file;
• list the source files actually used;
• wait for user approval before image generation.

A task-level user instruction that records prompt and generate plus the slide scope counts as generation approval for that task scope. A task recorded as prompt only never authorizes image generation.

Direct prompts may exist only as clearly labeled scratch or non-generation-ready drafts. They must be rebuilt through the gpt-image-2 Skill workflow before use.

Reference-Capable Image Generation

The current and future default success path for project-bound reference generation is:

gpt-image-2 Skill Advisor prompt/spec
→ load the real reference image into the conversation context
→ call host image_gen with the loaded image assigned an explicit role
→ copy the selected output into the project or investigation
→ record prompt, input reference path, output path, and review

This route was validated in:

investigations/2026-06-24-s14-reference-capable-generation/

Use this path instead of API/Garden image generation for normal Video Workbench work. Do not reopen the "can references work" question for ordinary project-bound image generation unless the host image tool is unavailable, the reference file cannot be loaded, or the user explicitly changes the policy.

For every reference-capable generation:

• the prompt must still be produced through the gpt-image-2 Skill workflow;
• the actual image reference must be loaded into the conversation context before generation;
• the prompt must name the loaded image role, such as Image 1: identity reference, Image 1: style reference, or Image 1: edit target;
• merely writing a local path in the prompt is not enough;
• the output must be copied from the host-generated default location into the project, investigation, or other durable workspace path;
• the review must record whether the generation used the verified host reference-by-visible-context path.

Reference selection defaults:

Shot or asset need	Default reference choice
Near shot, face, half-profile, expression, identity-heavy frame	Use the matching crop reference first.
Distant shot, landscape-led frame, aerial / wide scene, low identity burden	Use the accepted character anchor board or project-approved distant reference first.
Medium action, back view, walking pose, prop continuity	Use the matching crop, transparent slice, or anchor board according to the visible direction.
High identity fidelity project with many close shots	Consider creating higher-resolution crops through image-to-image from the accepted anchor board before production.

For 在路上-style landscape-led MV projects, a crop set derived from the accepted character anchor board and made transparent is sufficient by default when the goal is consistency rather than high-fidelity portrait likeness.

12. Capability-Request Mode

When a required capability is missing, create a supplier ticket and pause the dependent work.

Tickets go to:

requirements/ccpe/
requirements/skills-vault/

Use requirements/ccpe/ for local work agents, CCPE-Lite artifacts, agent specs, runtime rules, model cards, invocation contracts, and governed cognitive assets.

Use requirements/skills-vault/ for deterministic automation tools, scripts, exporters, batch processors, and installable automation skills.

13. Text Encoding

All local project documents are UTF-8 unless a file explicitly declares another encoding.

When using PowerShell to read Markdown, JSON, YAML, text, handoff, prompt, or discussion files, use explicit UTF-8:

Get-Content -LiteralPath <path> -Encoding UTF8
Select-String -Path <path> -Pattern <pattern> -Encoding UTF8

Do not wait for mojibake or a failed first read before applying UTF-8.

14. CCPE Consumption

Video Workbench consumes CCPE through the single external interface:

C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md

When preparing CCPE integration or invocation work, read Interface.md first and follow it to:

C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md

Do not duplicate canonical CCPE definitions here. Do not hardcode Agent, Lite, Skill, Runtime, or protocol paths as default entrypoints. Use ccpe-consumption/ for interface notes and future project-local invocation setup records.

Reusable or canonical expert agents belong in CCPE. Project-local slide task orchestration, child-session records, and slide-agent packets belong in Video Workbench and are not formal CCPE participant output. If this workflow is later packaged as deployable software, production/business agent implementation belongs in the target software project, not in Video Workbench.