291 lines
11 KiB
Markdown
291 lines
11 KiB
Markdown
# 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.
|
|
|
|
## Worker Profiles
|
|
|
|
Current profile:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
Worker Profile: video-slide-production
|
|
```
|
|
|
|
## Directory Model
|
|
|
|
Use project-local `tasks/` for orchestration records:
|
|
|
|
```text
|
|
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 `child-session-handoff.md`;
|
|
- 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.
|
|
|
|
### 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.
|
|
|
|
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;
|
|
- write `child-session-handoff.md`.
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
docs/workflows/slide-task-templates.md
|
|
```
|
|
|
|
Required per-slide artifacts:
|
|
|
|
```text
|
|
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.
|
|
|
|
## 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.
|
|
- 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:
|
|
|
|
```text
|
|
tasks/<task-id>/task-log.md
|
|
slides/slides.md
|
|
```
|