# Video Workbench Agent Rules

## Text Encoding

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

When reading Markdown, JSON, YAML, text, handoff, prompt, or discussion files from PowerShell, use explicit UTF-8 by default:

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

When writing text files, preserve UTF-8. Do not rely on PowerShell encoding defaults for Chinese Markdown.

## CCPE Interface

The default external CCPE entrypoint is:

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

For CCPE setup or invocation work, read that file first, then follow it to:

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

Do not hardcode old Agent, Lite, Skill, Runtime, or protocol paths as default CCPE entrypoints. Read narrower CCPE artifacts only when the consumer setup contract, a project-local registry, or the active task requires them.

Formal CCPE participant output requires a project-local registry, an invocation packet, a real participant carrier, and returned output saved only after the participant returns. Main-session roleplay is not formal CCPE output.

## Image Prompt Workflow

All image-generation prompts in this repository must be produced through the `gpt-image-2` Skill workflow. Do not draft final image prompts directly from memory or from a derived project skeleton alone.

Before writing any project-bound image prompt, run the Skill mode check and follow the resulting mode:

```powershell
node C:\Users\wangq\.agents\skills\gpt-image-2\scripts\check-mode.js --json
```

- Mode A: use the Skill's Garden generation/edit scripts and save prompt/image traces under `garden-gpt-image-2/`.
- Mode B: use the Skill as a prompt-engineering workflow, save the rendered prompt, then pass it to the host image tool only after user approval.
- Mode C / Advisor: use the Skill as a high-quality prompt advisor, save the rendered prompt, and do not claim an image was generated.

Current default success path for project-bound image generation:

1. Generate the final prompt/spec with the `gpt-image-2` Skill Advisor workflow.
2. When image references are needed, load the real reference image into the conversation context before generation.
3. Use the host `image_gen` tool with the loaded reference image assigned an explicit role such as `Image 1`.

Use this successful channel now and for future work. Do not switch normal Video Workbench image generation to API/Garden paths unless the user explicitly changes this policy.

For every project-bound image prompt document:

- Read the relevant `gpt-image-2` Skill template or reference file before drafting.
- Record the Skill mode, template/reference path, and source files actually read.
- Treat accepted `intake/` files and user-provided references as primary sources; use derived files such as `visual-system.md`, `execution-plan.md`, or `slides/slides.md` only as execution control summaries.
- If a prompt was drafted without the Skill workflow, label it as a non-generation-ready draft and rebuild it through the Skill before any image generation.
- When a local image outside the workspace is used, label its role explicitly as identity reference, edit target, or supporting reference, and do not proceed if the file cannot be read or approved.
- For near / identity-heavy shots, prefer a relevant crop reference. For distant / landscape-led shots, prefer the accepted anchor board or project-approved distant reference. Do not repeatedly re-ask whether references can work; the verified route is Skill Advisor prompt plus loaded reference image plus host `image_gen`.

Project-bound image generation must remain approval-gated: save the prompt/spec first, wait for user approval, then execute generation only when explicitly requested. A task-level user instruction that records the running mode and slide scope counts as explicit generation approval for that task scope. If the task mode is `prompt only`, do not generate images.

## Slide Task Workflow

For long slide / video production work, use the local slide task orchestration workflow:

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

### Runtime Vocabulary / Default Carrier

Use these terms as the default implementation contract for Video Workbench slide tasks. Do not re-investigate old session artifacts or broad runtime mechanism docs just to infer this mapping.

| User term | Meaning | Default carrier |
| --- | --- | --- |
| `子会话` / `session` | A user-visible separate Codex session for brief / orchestration work, started from a clean prompt rather than inherited orchestration history. | `codex_app.create_thread` to create, `codex_app.send_message_to_thread` to continue, `codex_app.read_thread` to inspect. |
| `继续前子会话` | Continue the already recorded visible child session instead of creating a new one. | Send the next instruction to the recorded `threadId`. |
| `Agent` / `SubAgent` | An internal one-shot worker used for test/audit, exception handling, or explicitly isolated slide work. It is not the default production-light carrier. | `multi_agent_v1.spawn_agent(agent_type="worker")`; one worker handles exactly one slide when used. |
| `无 review` / `review: none` | Review is disabled for the named scope. This is the production default after the test / audit line has established the project's core look. | Do not write `sNN-vN-review.md`; record only compact status, image paths, and task-log / handoff notes needed for continuation. |

Do not use `codex_app.fork_thread` as the default carrier for production child sessions. Forking copies completed orchestration history from the parent thread and can contaminate the child session's context. Use `fork_thread` only when the user explicitly wants an inherited-context branch.

If the default tools are not already exposed in a new session, use `tool_search` to expose `create_thread`, `send_message_to_thread`, `read_thread`, and `spawn_agent` by name, then proceed with this contract.

Default preflight for a slide/session run:

- confirm the target visible session id or create exactly one new clean visible session with `create_thread`;
- when creating a visible child session, set or request a user-facing title beginning with `子会话：` followed by the project / package name, so the session is distinguishable in the Codex UI;
- scan the target slide folder for the next unused `sNN-vN-*` version;
- set `Overwrite allowed: no`;
- read the project phase from `projects/<project>/project.md`; new projects default to `test/audit` until the user explicitly authorizes formal production;
- record the active line, either the project default or a user-authorized override for a named session / scope;
- record review mode; production-light defaults to `review: none`;
- use direct-child production in `production-light`; launch internal one-shot SubAgents only in `test/audit`, explicit review, repair, or exception scopes.

Use two operating lines:

- `test/audit`: use when building or debugging the workflow, proving a new project look, testing core shots, or investigating failures. Local review, richer ledgers, and longer handoffs are allowed.
- `production-light`: use after core shots have reached the expected look. This is the default normal production line once authorized in `project.md`. It keeps the content line (`brief`, `prompt`, generated image, `slides/slides.md`) and compact recovery receipts, but omits routine audit reports.

Production orchestration defaults:

- The main session dispatches the approved scope, records the parent thread id as the callback target, then stops routine waiting. It should not poll the child thread for routine completion.
- The production-light child session directly writes briefs, prompts, images, `slides/slides.md` updates, and a compact handoff. It does not launch Agent/SubAgent workers by default.
- The child session completes all allowed project writes, `slides/slides.md` updates, narrow required checks, and compact handoff writing before callback.
- The child session sends a concise callback to the parent with `codex_app.send_message_to_thread` as its final action. After a successful callback, it must not write or verify additional project files.
- The callback payload must include status, topology, resolved versions, handoff path, image paths if complete, and any problems or user decisions needed.
- After the callback wakes the parent, the parent reads the child session's short handoff and continues. It should not audit prompt / image details when the child session reports `complete` with no problems.
- The old sleep / poll schedule is a fallback only when callback tooling is unavailable or the user explicitly requests polling for a named run. If used, record the fallback in the task plan.
- The production-light child session keeps only the mandatory write guard: resolve the next unused version by scanning existing files, do not overwrite, record image paths, update required status files, perform only narrow required checks, and write a compact handoff before callback. Do not run a routine final verification pass.
- In `test/audit`, repair, or exception scopes, the child session may run the fuller completion gate: append-only version, no overwrite, expected files present, review present or absent as instructed, one owning worker per slide/version when workers are used, references loaded or blocked, and compact handoff written.
- Instruction / visual review is optional. In production-light, the default is `review: none`: generated images are recorded as production-pass outputs without per-image user review, and the user may request an append-only retry later if the result is not usable.
- A slide `Agent` / `SubAgent`, when used, is one-shot. It receives one packet, handles one slide/version, writes one return, then becomes terminal / closed. Do not continue or reuse a closed Agent; repairs, retries, and next slides require a new Agent.

Re-investigate runtime mechanics only when a tool is unavailable or errors, when an Agent becomes a user-visible session, when duplicate workers target the same slide/version, when target files collide, or when the user explicitly asks to revise the mechanism.

Rules:

- Use `projects/<project>/tasks/<task-id>/` for local orchestration records.
- The main session talks with the user and defines worker profile, running mode, slide scope, and review expectations.
- Production-light child sessions write per-slide briefs, prompts, images, and compact handoff directly; they may handle at most 8 ordinary production slides by default. Reduce to 1-3 slides for identity-heavy, repair-heavy, core-risk, or context-expensive scopes.
- Test/audit child sessions may launch slide agents; a slide agent handles exactly 1 slide per invocation.
- The default worker profile for current MV / video work is `video-slide-production`.
- Reserved future profile `ppt-page-production` may use `docs/cases/`, but must be designed when the first real PPT task needs it.
- For cover pages, PPT pages, science-video pages, title cards, explainer pages, or any slide that needs later human layout / typography / post-production, add a separate `sNN-vN-design.md` before `brief`. `design` is for the user and records visual concept, layout, text content, typography/color guidance, post-production notes, constraints, and references. `brief` remains the execution card for Codex / image generation and must not absorb human-facing design or post-production notes.
- `sNN-vN-design.md` is Chinese by default. If an English design companion is needed, write `sNN-vN-design-en.md` beside it; the English file supplements but does not replace the default Chinese design.
- For design-gated slides, write `design` first and wait for user confirmation before writing `brief`, `prompt`, or generating the image, unless the user explicitly authorizes the full chain in one task.
- `visual-system/` is the production authority for slide work.
- 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 image references.
- 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.
- New slide-task execution must append the next unused `sNN-vN-*` version and must not overwrite existing slide artifacts unless the user explicitly authorizes an overwrite repair for named files.
- Review defaults to `none` in production-light and local-only in test/audit or explicit review tasks. Do not call Minimax MCP or other external vision/review services unless the user explicitly authorizes that task.