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

699 lines
19 KiB
Markdown
Raw Permalink Blame History

# Slide Task Orchestration Plan
## Status
- Draft date: 2026-06-24.
- Scope: local Video Workbench slide-production orchestration.
- Status: approved implementation basis.
- Project driver: `projects/2026-06-23-在路上`.
This plan is not a CCPE workflow. It is a local Video Workbench execution protocol for reducing main-session context pressure while keeping slide production traceable and lightweight.
Active workflow docs created from this plan:
```text
docs/workflows/slide-task-orchestration.md
docs/workflows/slide-task-templates.md
```
## Core Principles
1. Keep the workflow practical.
- This is not a software development project and should not become a heavy governance system.
- Record only the minimum task evidence needed for continuation, debugging, and user review.
2. Protect user attention.
- The user and any expert reviewer should not inspect every non-core slide.
- User review is reserved for run authorization, core slides, high-risk slides, failed slides, and explicit sampling.
3. Keep context bounded.
- The main session should not carry every slide's full prompt, generation, and review context.
- Child sessions reuse common project context for a small number of slides.
- One slide agent handles exactly one slide.
4. Avoid session contamination.
- No parallel child sessions by default.
- No multi-slide agents.
- Batch grouping happens at the session level, not inside a slide agent.
5. Keep files as the continuation source.
- Chat history is not authoritative after compression.
- Briefs, prompts, images, returns, logs, and handoffs must be written to disk.
6. Treat `visual-system/` as the production authority.
- slide work must use the active visual-system files rather than reconstructing style or character rules from memory.
- Style continuity comes from `visual-system/style/style-prompt-master.md` and its active style reference rules.
- Character continuity comes from `visual-system/characters/character-reference-registry.md` and active character reference images.
- When a slide contains a visible character and identity matters, text-only prompting is not sufficient.
7. Use the `gpt-image-2` Skill Advisor workflow for prompt work.
- slide prompts must be produced through the `gpt-image-2` Skill workflow.
- In the current default path, use Advisor / host-native mode: render the prompt/spec with the Skill, then use the host image tool only when the task allows generation.
- Do not freehand final project-bound image prompts from the brief alone.
## Orchestration Model
```text
main orchestration session
-> task plan
-> child session 01
-> write brief for s05
-> start slide agent for s05
-> write brief for s21
-> start slide agent for s21
-> write brief for s14
-> start slide agent for s14
-> write child-session handoff
-> child session 02
-> write brief for s25
-> start slide agent for s25
-> write brief for s33
-> start slide agent for s33
-> write child-session handoff
```
Default child-session capacity:
- 3 slides maximum per child session.
- Fewer slides are allowed when the slides are identity-heavy, repair-heavy, or otherwise context-expensive.
- Child sessions run sequentially, not in parallel.
Default slide-agent capacity:
- 1 slide per agent invocation.
- The slide agent must not accept a range or batch of slides.
## Worker Profiles
This plan implements only the current worker profile:
```text
video-slide-production
```
Current profile behavior:
- uses project `visual-system/` as the production authority;
- uses `slides/` as the slide artifact area;
- uses `gpt-image-2` Skill Advisor / host-native prompt workflow;
- uses style prompt master and active character reference registry;
- has no extra project knowledge base by default.
Reserved future profile:
```text
ppt-page-production
```
Future profile notes:
- may use `docs/cases/` as an additional case-pattern knowledge base;
- may need page-level brief, prompt, and review structures rather than slide-level structures;
- must not inherit video-slide rules blindly;
- should be designed when the first real PPT task needs it.
Task plans must record the worker profile:
```text
Worker Profile: video-slide-production
```
## Directory Model
Use `tasks/`, not `runs/`, for local 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
session-02/
child-session-plan.md
child-session-handoff.md
packets/
returns/
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 files should not duplicate full prompts unless needed for status or debugging.
- Task records should link to slide artifacts by path.
Suggested task id pattern:
```text
YYYY-MM-DD-<short-purpose>
```
Example:
```text
projects/2026-06-23-在路上/tasks/2026-06-24-character-consistency/
```
## Main Session Responsibilities
The main session is the only session that talks with the user by default.
The main session should:
- receive the user instruction;
- define the task scope and allowed running mode;
- decide the child-session split;
- create or update `task-plan.md`;
- start child sessions sequentially;
- read each `child-session-handoff.md`;
- ask the user only for real decisions, blockers, or requested sampling;
- update `task-log.md` with compact status.
The main session should not:
- write per-slide briefs by default;
- write final prompts by default;
- generate images by default;
- review every non-core image by default;
- carry all slide context in chat.
## Child Session Responsibilities
The child session is the small-batch context holder.
The child session should:
- read the project rules and the task plan;
- read the shared project context needed for the assigned slides;
- read the active `visual-system` materials needed for the assigned slides, especially:
- `visual-system/visual-system.md`;
- `visual-system/style/style-prompt-master.md`;
- `visual-system/characters/character-reference-registry.md` when a slide contains a visible character;
- write one `sNN-vN-brief.md` per assigned slide;
- create one slide-agent packet per slide;
- start exactly one slide agent per slide, sequentially;
- verify that expected files were written;
- write `child-session-handoff.md` before ending.
The child session should not:
- talk to the user unless explicitly instructed by the main session;
- process more than 3 slides by default;
- run slide agents in parallel;
- generate final prompts itself unless the slide-agent path is unavailable;
- turn task records into a full audit package.
## Slide Agent Responsibilities
The slide agent is the single-slide worker.
The slide agent should:
- read the provided packet;
- read the slide brief;
- follow the `gpt-image-2` Skill Advisor / host-native prompt workflow recorded in the packet;
- use the brief's `Reference Plan` and preserve the active visual-system reference choices in `sNN-vN-prompt.md`;
- write or update `sNN-vN-prompt.md`;
- generate the image only when the packet allows generation;
- write `sNN-vN-review.md` only when required;
- write a short return file.
The slide agent should not:
- write the brief in the default workflow;
- process a second slide;
- infer task scope beyond the packet;
- replace style-master guidance with an ad hoc style paragraph;
- replace active character image references with text-only identity description when the slide needs character continuity;
- use archived character or style references unless the packet explicitly reopens them;
- call Minimax MCP or external review tools by default.
## Slide Agent Running Modes
The main session chooses the running mode for each task.
### Mode 1: 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 the required character reference image(s)
-> slide agent generates image
-> slide agent writes review if required
-> slide agent return
```
Use for:
- non-core production after task-level authorization;
- low-risk environment slides;
- continuation work where the prompt pattern is already stable.
### Mode 2: 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.
Use for:
- high-risk identity slides;
- new project first-pass validation;
- prompt sampling in ChatGPT or another platform;
- any task where the user wants to inspect prompts before generation.
## Task Authorization Rule
The user gives concrete instructions to the main session for:
- agent running mode;
- slide range;
- generation permission;
- review/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 range and exceptions.
Core, repair, identity-heavy, or otherwise high-risk slides may still require prompt-only handling or an explicit pause if the task plan says so.
## Brief Structure
The brief is the universal slide execution card. It has the same structure whether or not GPT supplied a dedicated single-slide skeleton.
Recommended structure:
```text
# S-NN Slide Brief V1
## Status
## Source Basis
## slide Function
## First Read
## Risk Class
## Reference Plan
## Visual Requirements
## Character Handling
## Composition / Scale
## Light / Color / Texture
## Forbidden Drift
## Acceptance Checklist
## Prompt Handoff
```
### Brief Field Rules
`Status` records document status, task id, slide id, version, and current execution state.
`Source Basis` lists only the key sources used for this brief. Do not turn this into a full review manifest.
`slide Function` states what this slide does in the sequence.
`First Read` states what the viewer should notice first.
`Risk Class` classifies the slide, for example:
```text
environment-only
object/body detail
distant human
medium human
close/face human
core motif
repair
```
`Reference Plan` names the required style module and character references, or says `none` with a reason.
For style, the reference plan must point to the active style module in:
```text
visual-system/style/style-prompt-master.md
```
For visible character slides, the reference plan must select active character reference images from:
```text
visual-system/characters/character-reference-registry.md
```
If the slide contains a visible character and identity matters, the brief must say which reference image should be loaded for generation. Text-only character description is not enough for those slides.
`Visual Requirements` lists the positive content requirements.
`Character Handling` records visibility, identity burden, scale, posture, and prop continuity.
`Composition / Scale` records frame logic, figure size, first-read hierarchy, and placement.
`Light / Color / Texture` records the local light and material rules.
`Forbidden Drift` records the main failure modes.
`Acceptance Checklist` is the minimum local check list.
`Prompt Handoff` tells the slide agent what the prompt must carry into generation.
## Prompt Structure
The prompt file is an attachment to the brief. It should be directly runnable or easy to use for cross-platform prompt validation.
Recommended structure:
```text
# S-NN Slide Prompt V1
## Status
## Based On Brief
## Reference Inputs
## Operation Notes
## Final Prompt
## Negative / Avoid
## Output Intent
```
### Prompt Field Rules
`Status` records slide id, version, mode, and execution state.
`Based On Brief` links to the brief path.
`Reference Inputs` lists actual image references and roles.
Every prompt must preserve the visual-system usage from the brief:
- style module from `visual-system/style/style-prompt-master.md`;
- active style reference path(s), when applicable;
- active character reference path(s), when a character is visible and identity matters;
- explicit `none` with reason when no character reference should be used.
When using reference-capable host generation, use explicit visible-context roles:
```text
Image 1: identity reference
Image 2: style reference
```
`Operation Notes` records only generation-relevant steps, such as loading reference images before calling the host image tool.
For character-visible slides, `Operation Notes` must state whether image-to-image / reference-by-visible-context generation is required. 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.
`Final Prompt` should be rendered through the `gpt-image-2` Skill Advisor workflow and should be copyable into another image-generation platform with minimal cleanup.
`Negative / Avoid` should be copyable as a negative prompt or avoid list.
`Output Intent` records the intended project output path and cross-validation note if relevant.
Do not put these in normal prompt files unless needed for the run:
- full project explanation;
- long source-file audit;
- detailed Skill file narrative;
- review conclusions;
- task orchestration history.
## Review Structure
Reviews are optional by default.
Create `sNN-vN-review.md` only when:
- the slide is a core trial slide;
- the slide is identity-heavy;
- the slide is a repair target;
- the user explicitly requests a review record;
- the agent detects likely failure or uncertainty;
- the image is being accepted as a durable reference.
Recommended structure:
```text
# S-NN Slide Review V1
## Status
## Generation Trace
## Local File Check
## Local Visual Check
## Acceptance Checklist
## Issues
## Decision / Next Action
```
Default review rule:
- Use local capabilities 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 visual-system character reference was actually loaded or whether the run was only text-guided.
- For style-sensitive slides, check whether the prompt used the active style module rather than a one-off style paragraph.
Non-core generated slides may instead be recorded in:
```text
tasks/<task-id>/task-log.md
slides/slides.md
```
## Task File Structures
### `task-plan.md`
```text
# <Task Title>
## Status
## User Instruction
## Worker Profile
## Running Mode
## slide Scope
## Child Session Split
## Shared Context
## Rules
## Visual-System Usage
## Expected Outputs
## User Review / Sampling Plan
## Stop Conditions
```
### `child-session-plan.md`
```text
# Child Session NN Plan
## Status
## Parent Task
## Assigned slides
## Shared Context To Read
## Visual-System Files To Read
## Per-slide Work Order
## Agent Packet Paths
## Stop Conditions
```
### `slide-agent-packet.md`
```text
# S-NN Slide Agent Packet V1
## Status
## Target slide
## Allowed Actions
## Input Files
## Output Files
## Reference Roles
## Visual-System Requirements
## Gpt-Image-2 Advisor Rule
## Generation Rule
## Review Rule
## Return File
```
### `slide-agent-return.md`
```text
# S-NN Slide Agent Return V1
## Status
## Files Written
## Generation Result
## Review Result
## Blockers
## Next Action
```
### `child-session-handoff.md`
```text
# Child Session NN Handoff
## Status
## Completed slides
## Files Written
## Problems / Repairs Needed
## User Decisions Needed
## Next Session Input
```
### `task-log.md`
Keep this compact. It is not a full audit.
```text
# Task Log
## Status
## Timeline
## Child Session Results
## slide Status Summary
## Open Decisions
```
## Planned File And Folder Changes
This plan should be implemented after user review.
### Add Docs
```text
docs/workflows/slide-task-orchestration.md
docs/workflows/slide-brief-structure.md
docs/workflows/slide-prompt-structure.md
docs/workflows/slide-review-structure.md
docs/workflows/slide-agent-packet.md
```
Possible consolidation:
- If this is too many files, keep one stable workflow document and one templates document.
### Add Templates
```text
docs/templates/task-plan-template.md
docs/templates/child-session-plan-template.md
docs/templates/child-session-handoff-template.md
docs/templates/slide-agent-packet-template.md
docs/templates/slide-agent-return-template.md
docs/templates/slide-brief-template.md
docs/templates/slide-prompt-template.md
docs/templates/slide-review-template.md
```
### Update Workspace Rules
```text
VIDEO_WORKBENCH.md
AGENTS.md
```
Expected updates:
- add `tasks/` as the local task orchestration directory;
- define main session / child session / slide agent boundaries;
- define the two slide-agent running modes;
- state that task-level user instruction controls generation authorization;
- state that child sessions and slide agents must use active `visual-system` materials;
- state that visible character identity requires actual character image references, not text-only prompting;
- state that slide prompts must use the `gpt-image-2` Skill Advisor workflow;
- state that review defaults to local-only and does not call Minimax MCP.
### Add Project Task Directory During First Trial
For the `在路上` character-consistency trial:
```text
projects/2026-06-23-在路上/tasks/2026-06-24-character-consistency/
```
Expected substructure:
```text
task-plan.md
task-log.md
session-01/
session-02/
```
### Existing Slide Artifact Changes During First Trial
Likely generated or updated:
```text
projects/2026-06-23-在路上/slides/s05/s05-v1-brief.md
projects/2026-06-23-在路上/slides/s05/s05-v1-prompt.md
projects/2026-06-23-在路上/slides/s21/s21-v1-brief.md
projects/2026-06-23-在路上/slides/s21/s21-v1-prompt.md
projects/2026-06-23-在路上/slides/s14/s14-v1-brief.md
projects/2026-06-23-在路上/slides/s14/s14-v1-prompt.md
projects/2026-06-23-在路上/slides/s25/s25-v1-brief.md
projects/2026-06-23-在路上/slides/s25/s25-v1-prompt.md
projects/2026-06-23-在路上/slides/s33/s33-v1-brief.md
projects/2026-06-23-在路上/slides/s33/s33-v1-prompt.md
```
Image and review files depend on task running mode.
## First Trial Recommendation
Use the character-consistency slides as the first orchestration trial.
Task:
```text
projects/2026-06-23-在路上/tasks/2026-06-24-character-consistency/
```
Child session split:
```text
session-01: s05 -> s21 -> s14
session-02: s25 -> s33
```
Recommended first running mode:
```text
prompt only
```
Reason:
- This validates the new brief and prompt structure without spending image-generation context.
- The user can sample prompts externally if desired.
- A later task can use the same prompts for generation.
If the user chooses `prompt and generate`, the task plan must record that instruction and the exact slide scope.
## Open Implementation Decisions
1. Whether to split the stable docs into five files or keep a single workflow document plus templates.
2. Whether to update `AGENTS.md` immediately or only update `VIDEO_WORKBENCH.md` for this local workflow.
3. Whether the first trial should be `prompt only` or `prompt and generate`.
4. Whether old broad-run candidate images for `s05`, `s14`, `s21`, `s25`, and `s33` should be marked as comparison-only before the character-consistency task starts.
Reference in New Issue View Git Blame Copy Permalink