wantsong
/
video-workbench
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
video-workbench/docs/workflows/slide-task-orchestration.md

16 KiB
Raw Blame History

Slide Task Orchestration

Status

  • Status: active workflow rule.
  • Scope: local Video Workbench slide production tasks.
  • First profile: video-slide-production.

In this workflow, slide is the execution unit. A slide may be a video frame unit, a PPT page, or another visual page-like unit. Current rules implement video/MV slide production only.

Goals

  • Keep the main session small enough to survive long production work.
  • Keep style and character continuity anchored in visual-system/.
  • Keep user review focused on real decisions, not every generated image.
  • Keep task evidence light but sufficient for continuation after context compression.
  • Keep routine completeness and optional instruction review inside child sessions, so the main orchestration session can stay lightweight in production.

Worker Profiles

Current profile:

video-slide-production

This profile uses:

  • visual-system/ as the production authority;
  • visual-system/style/style-prompt-master.md for style modules and style prompt language;
  • visual-system/characters/character-reference-registry.md for active character references;
  • slides/ for slide artifacts;
  • gpt-image-2 Skill Advisor / host-native prompt workflow.

For Video Workbench, the gpt-image-2 Skill is used as the prompt/spec Advisor. Normal project-bound image generation does not need to prove Garden, API, multipart upload, or local gpt-image-2 script execution. The expected generation path is:

gpt-image-2 Advisor prompt/spec
-> load the real reference image into visible conversation context when references are required
-> call host built-in image generation with the loaded image named as Image 1 / Image 2
-> copy the host output into slides/sNN/
-> record prompt/spec evidence, loaded-reference evidence, host output path, and review/return evidence

Garden/API use is expected to be no unless the user explicitly changes the project policy.

Reserved future profile:

ppt-page-production

Future PPT tasks may use docs/cases/ as an additional case-pattern knowledge base and may need a different page brief, prompt, and review structure. Do not apply video-slide-production rules blindly to PPT work; design that profile when the first real PPT task needs it.

Every task plan must record:

Worker Profile: video-slide-production

Directory Model

Use project-local tasks/ for orchestration records:

projects/<project-id>/
  tasks/
    <task-id>/
      task-plan.md
      task-log.md
      session-01/
        child-session-plan.md
        child-session-handoff.md
        packets/
          s05-v1-slide-agent-packet.md
        returns/
          s05-v1-slide-agent-return.md
  slides/
    s05/
      s05-v1-brief.md
      s05-v1-prompt.md
      s05-v1-image.png
      s05-v1-review.md

Rules:

  • tasks/<task-id>/ records orchestration and agent communication.
  • slides/sNN/ remains the durable home for slide artifacts.
  • Task records link to slide artifacts by path and should not duplicate full prompts.
  • Task records do not own the slide version number. Before each slide run, resolve the next unused sNN-vN-* version from the existing files in slides/sNN/, then write only that new version.
  • Existing slide artifacts are historical evidence even when incomplete or superseded. Do not overwrite them to make a later task look cleaner.
  • Suggested task id pattern: YYYY-MM-DD-<short-purpose>.

Artifact Version And Write Policy

Default policy:

  • New task execution appends a new slide version. It does not reuse or overwrite an existing vN.
  • The next version is the next unused integer after all existing files matching sNN-v*-* in the slide folder, regardless of whether earlier versions have missing brief, prompt, image, or review files.
  • Incomplete earlier versions should be recorded as incomplete, broad-run, interrupted, superseded, or invalid as appropriate. Do not backfill a missing prompt or brief in a way that implies it was the original generation prompt.
  • Every child session or slide-agent packet must state Overwrite allowed: no unless the user explicitly authorizes an overwrite repair for named files.
  • Before writing brief, prompt, image, review, packet, return, or handoff files, the writing agent must check whether each target file already exists. If a target exists and overwrite is not explicitly authorized, the agent must stop and report an artifact collision instead of writing.
  • An approved overwrite repair must preserve or explicitly cite the prior file state before replacement. Routine production and workflow tests should not use overwrite repair.

This rule applies even when the previous run was malformed. Malformed output is still evidence about the workflow and should be superseded by a new version, not silently replaced.

Session Roles

Main Session

The main session is the only session that talks with the user by default.

Responsibilities:

  • receive the user instruction;
  • define the worker profile, running mode, slide scope, and review expectations;
  • create or update task-plan.md;
  • split work into sequential child sessions;
  • start child sessions one at a time;
  • read the child session's short completion handoff;
  • ask the user only for blockers, core decisions, or requested sampling;
  • update task-log.md with compact status.

The main session should not write per-slide briefs, final prompts, images, or routine reviews by default. In production mode it should also not redo routine child-session completeness checks unless the child session reports a problem.

Production orchestration default:

  • Launch or continue exactly one child session for the approved scope.
  • Choose the wait schedule by package size:
    • 1 slide: sleep 10 minutes before the first status check; if incomplete, poll every 1 minute up to 15 minutes total.
    • 2 slides: sleep 20 minutes before the first status check; if incomplete, poll every 1 minute up to 30 minutes total.
    • 3 slides: sleep 30 minutes before the first status check; if incomplete, poll every 1 minute up to 45 minutes total.
  • If a package would exceed 3 slides, split it into smaller packages unless the task plan explicitly defines a custom wait schedule.
  • After the package-specific cap, inspect thread status or report a timeout / blocker.
  • During routine waiting, parent-facing heartbeat/status updates default to every 5 minutes or on material state changes. This is separate from the child-session status-check schedule and should not trigger extra thread inspection.
  • Consume only the handoff's status, completion gate, review mode/result, agent lifecycle, and parent summary by default.
  • Continue to the next approved slide/scope when status is complete and the completion gate is pass.
  • Open detailed prompt, return, ledger, or image evidence only when the handoff reports blocked, failed, warning, missing completion-gate evidence, artifact collision, duplicate worker, user-requested audit, or explicit sampling/review.

Child Session

The child session is the small-batch context holder.

Default capacity:

  • maximum 3 slides per child session;
  • fewer slides for identity-heavy, repair-heavy, or context-expensive work;
  • sequential only, not parallel.

This maximum is a default child-session chunk size, not a project-wide production cap. After the workflow is proven stable, the main session may dispatch additional child sessions or a broader user-approved scope while preserving the per-child-session capacity rule unless the task plan explicitly changes it.

Responsibilities:

  • read project rules and the task plan;
  • read shared project context for assigned slides;
  • read active visual-system/ files needed for assigned slides;
  • resolve the next unused slide version and write one new sNN-vN-brief.md per assigned slide;
  • create one slide-agent packet per slide;
  • start exactly one slide agent per slide, sequentially;
  • verify expected files were written;
  • run the required completion gate before returning;
  • run instruction review only when the task plan or packet requires review;
  • write child-session-handoff.md with a compact parent-facing summary.

If the runtime does not let the child session start a slide agent directly, the child session must record this as a runtime fallback requirement in child-session-handoff.md. The main session may then start the slide agent as a fallback, but that run must be reported as a fallback orchestration test, not as a full child-session-owned slide-agent test.

Slide Agent

The slide agent is the single-slide worker.

Default capacity:

  • one slide per invocation;
  • no ranges;
  • no batches.

Responsibilities:

  • read the packet and brief;
  • follow the gpt-image-2 Skill Advisor / host-native prompt workflow;
  • preserve visual-system reference choices in sNN-vN-prompt.md;
  • write the new-version sNN-vN-prompt.md;
  • generate an image only when the packet allows generation;
  • write sNN-vN-review.md only when required;
  • write a compact return file.

Lifecycle rule:

  • A slide agent is one-shot.
  • It receives exactly one immutable packet.
  • It owns exactly one slide/version.
  • It writes exactly one compact return.
  • After the return is recorded, the agent is terminal / closed.
  • Closed agents must not be continued, reused, or assigned follow-up work.
  • Any repair, retry, or next slide must launch a new agent with a new packet and, when writing slide artifacts, a new append-only version.

The slide agent must not:

  • overwrite existing slide artifacts unless the packet explicitly authorizes overwrite repair for named files;
  • write the brief in the default workflow;
  • process a second slide;
  • replace style-master guidance with ad hoc style text;
  • replace active character image references with text-only identity description when character continuity matters;
  • use archived style or character references unless the packet explicitly reopens them;
  • call Minimax MCP or external review tools by default.

Running Modes

Prompt And Generate

Use when the user authorizes generation for the task scope.

Flow:

child session writes brief
-> slide agent writes prompt
-> if visible character identity matters, load required character reference image(s)
-> slide agent calls host image generation through the visible-context reference path
-> slide agent writes review if required
-> slide agent return

For this workflow, "load required character reference image(s)" means the actual local image is made visible to the generation context before host image generation. A local filesystem path written in a prompt is traceability only and does not count as loading the image.

The slide agent must not treat "Garden/API not used" as a failure. The expected evidence is that the Advisor prompt/spec was prepared and the host image-generation path was used with the required visible-context reference.

Prompt Only

Use when the user wants prompt sampling, external cross-checking, or delayed generation.

Flow:

child session writes brief
-> slide agent writes prompt
-> slide agent return

Generation can happen later through a separate task.

Authorization Rule

The user gives the main session concrete instructions for:

  • running mode;
  • slide scope;
  • generation permission;
  • review or sampling expectations.

If the task says prompt only, no image generation is allowed.

If the task says prompt and generate, the task plan must record the authorized slide scope and exceptions. That task-level instruction is the generation approval for the named scope. Core, repair, identity-heavy, or otherwise high-risk slides may still require prompt-only handling or an explicit pause when the task plan says so.

Visual-System Requirements

visual-system/ is the production authority.

For every slide:

  • use active visual-system files, not memory reconstruction;
  • choose style from visual-system/style/style-prompt-master.md;
  • record style module and active style references in the brief and prompt;
  • choose character references from visual-system/characters/character-reference-registry.md when a visible character matters.

For visible character slides:

  • text-only identity prompting is not sufficient;
  • the brief must name the character reference image(s);
  • the prompt must assign visible-context roles such as Image 1: identity reference;
  • if the active generation path cannot load the required character image reference, the agent must block instead of generating a text-only identity-critical image.

Document Structures

Stable templates live in:

docs/workflows/slide-task-templates.md

Required per-slide artifacts:

sNN-vN-brief.md
sNN-vN-prompt.md
sNN-vN-image.png      # only when generation is allowed and succeeds
sNN-vN-review.md     # only when required

brief is the universal execution card. It is written by the child session.

prompt is an attachment to the brief. It should be runnable or easy to copy into another platform for cross-validation.

review is optional by default. Create it only for core trials, identity-heavy slides, repair targets, explicit user requests, uncertain failures, or durable accepted references.

When review is required or suppressed, the task plan or slide-agent packet should say so explicitly. Character-consistency tests and other identity-sensitive generated trials default to local review unless the task plan disables it.

Completion Gate

The completion gate is mandatory for every production or workflow-test child session. It is not the same as instruction review.

The child session must confirm before returning:

  • assigned slide versions were resolved by scanning existing slides/sNN/sNN-v*-* files;
  • no target file was overwritten unless an explicit overwrite repair authorized that exact path;
  • each assigned slide has the expected brief, packet, prompt, image when generation is allowed, and return files;
  • review files are present when review was required and absent when review was disabled;
  • each slide has exactly one owning slide agent for that slide/version;
  • each slide agent return is recorded and the agent lifecycle is terminal / closed;
  • required visible-context image references were loaded or the run blocked before generation;
  • generated project images have recorded source paths and hashes when available;
  • the child session handoff contains a compact parent summary.

If any completion-gate item fails, the child session must return blocked, failed, or warning and state what the main session should inspect. The main session then leaves lightweight production mode for that item and performs targeted inspection only.

Review Rule

Default review is local-only.

  • Do not call Minimax MCP by default.
  • Do not transmit private project images to external services unless the user explicitly authorizes it for that task.
  • Completeness checking is mandatory and belongs in the completion gate.
  • Instruction / visual review is optional and depends on the task plan.
  • If review mode is none, do not write sNN-vN-review.md; the return and handoff must still state that review was intentionally suppressed.
  • For character-visible slides, check whether the required character image reference was actually loaded.
  • For style-sensitive slides, check whether the prompt used the active style module from the style master.
  • For host-native generation, check whether the review or return records:
    • gpt-image-2 Advisor prompt/spec evidence;
    • loaded visible-context image role such as Image 1;
    • host generated-image source path;
    • copied project image path;
    • whether Garden/API was expected (no by default).

Routine non-core generated slides can be tracked in:

tasks/<task-id>/task-log.md
slides/slides.md