341 lines
16 KiB
Markdown
341 lines
16 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.
|
|
- Keep routine completeness and optional instruction review inside child sessions, so the main orchestration session can stay lightweight in production.
|
|
|
|
## 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 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:
|
|
|
|
```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.
|
|
|
|
## 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:
|
|
|
|
```text
|
|
tasks/<task-id>/task-log.md
|
|
slides/slides.md
|
|
```
|