Skip to content

Change Workflow

This document defines how implementation changes should be planned, executed, verified, and documented in anuva-unity-video-creator.

It follows the Anuva Engineering Handbook Implementation Repository Change Workflow and customizes only Unity-specific risk areas, docs references, generated files, and verification commands.

flowchart LR
  request["Change request"] --> size{"Small or large?"}
  size --> small["Small: inline plan"]
  size --> large["Large: docs/changes folder"]
  small --> inspect["Inspect Unity scripts, scenes, assets, and docs"]
  large --> breakdown["ChangeBreakdown.md"]
  breakdown --> plan["ImplementationPlan.md"]
  plan --> inspect
  inspect --> implement["Implement after approval or explicit proceed"]
  implement --> verify["Verification"]
  verify --> docs["Docs parity"]
  docs --> log["ImplementationLog.md when large"]

1. Change Sizes

Small Change

A small change can be planned inline in chat.

A change is usually small when it:

  • touches one narrow Unity behavior, local doc, editor helper, template, or scene setting
  • affects a small number of files
  • does not change PresentationConfig.cs, Python/Unity protocol messages, generated virtual-screen contracts, package dependencies, build settings, or repository boundaries
  • does not change render orchestration assumptions, capture lifecycle, canonical scene selection, bot/camera/screen product behavior, or cross-repository acceptance criteria
  • can be verified with a targeted docs build, Unity import/compile check, focused manual scene inspection, simulator check, or targeted Unity Test Runner command
  • needs only a small docs update, if any

Small changes still require docs updates when Unity behavior, scene setup, render contracts, virtual screen behavior, bot motion, capture workflow, or verification expectations change.

Large Change

Use the large-change workflow when a change affects any of:

  • core Unity renderer behavior owned by this repository
  • PresentationController, playback sequencing, capture behavior, bot motion, camera directing, virtual screens, or remote render handling
  • PresentationConfig.cs, sample config expectations, generated screen payloads, or other public config contracts
  • AnuvaPythonServerCommunication.cs, protocol message names, ports, payload shape, lifecycle state, heartbeat/status behavior, or simulator behavior
  • Unity scenes, prefabs, serialized fields, render textures, materials, lighting, build settings, packages, or Unity editor version
  • generated artifacts such as Assets/StreamingAssets/AnuvaVirtualScreens/generated/*.html
  • source templates, themes, registries, or bridge assets under Assets/StreamingAssets/AnuvaVirtualScreens/
  • vendor/plugin integration behavior for AVPro, Vuplex, DOTween, Cinemachine, URP, Bakery, Magic Lightmap Switcher, Beautify, ShinySSRR, OneJS, or NetMQ
  • more than 4-6 implementation files
  • unclear product behavior, unresolved render acceptance criteria, or any Web/Python/product-main coordination need

If a small change expands into one of these areas, stop and switch to the large-change workflow.

2. Large Change Folder

Large changes must be grouped under:

docs/changes/<YYYY-MM-DD-HHMM-change-name>/

Use UTC time unless the user specifies otherwise.

Example:

docs/changes/2026-05-17-1430-unity-remote-render-output/

Required files:

BrainDump.md
ChangeBreakdown.md
ImplementationPlan.md
ImplementationLog.md

New documents created under docs/changes/<change-folder>/ must include a Mermaid diagram. If BrainDump.md is copied directly from user notes, preserve the raw notes and add a short Mermaid context diagram separately.

3. Large Change Documents

BrainDump.md

Raw user thoughts.

This file can be messy. It may contain product ideas, bugs, questions, references, half-decisions, and unrelated threads.

Do not implement directly from BrainDump.md.

ChangeBreakdown.md

Created by Codex from BrainDump.md.

It should contain:

  • summary of the change
  • grouped change areas
  • Mermaid diagram for the affected Unity flow, scene/runtime dependency map, protocol path, render lifecycle, or decision structure
  • explanation for each change
  • affected product surfaces
  • likely affected Unity scripts, scenes, prefabs, generated files, StreamingAssets, packages, and project settings
  • likely affected docs under docs/core, docs/state, docs/process, and docs/changes
  • risks and dependencies, especially serialized scene/prefab risk, .meta files, capture output, generated virtual-screen drift, and cross-repository contracts
  • out-of-scope items, including Web, Python server, product-main, handbook, and docs-publisher work when they are not part of this repository change
  • open questions

Questions should be written so the user can answer directly in the same file.

Recommended question format:

### Questions

#### Q1. <question>

Answer:

#### Q2. <question>

Answer:

ImplementationPlan.md

Created after the user answers questions in ChangeBreakdown.md.

It should be an execution-grade plan, not just a summary.

It should contain:

  • goal
  • non-goals
  • current behavior
  • target behavior
  • Mermaid diagram for the planned implementation sequence, Unity data flow, scene/runtime relationships, or protocol lifecycle
  • assumptions
  • affected files and modules
  • affected docs
  • config, protocol, generated artifact, scene, prefab, package, or project setting impact
  • implementation phases
  • task checklist
  • verification plan
  • docs parity checklist
  • acceptance criteria
  • rollback or recovery notes, if relevant

Task checklist format:

## Tasks

- [ ] 1. Investigate current behavior
- [ ] 2. Update Unity implementation or assets
- [ ] 3. Update generated artifacts, if required
- [ ] 4. Update docs
- [ ] 5. Run verification
- [ ] 6. Update ImplementationLog.md

ImplementationLog.md

Updated during and after implementation.

It should contain:

  • date/time started
  • date/time completed
  • tasks completed
  • Mermaid diagram for the implemented Unity flow, state transition, dependency shape, or final change sequence
  • files changed
  • docs updated
  • tests and commands run
  • scene, config source, capture output path, frame rate, resolution, and integration mode when render behavior was verified
  • decisions made during implementation
  • deviations from the plan
  • known gaps or follow-ups

4. Codex Behavior

Codex should not implement during the ChangeBreakdown.md or ImplementationPlan.md phases unless the user explicitly asks for implementation.

During planning, Codex may:

  • read files
  • inspect code, scenes, serialized assets, docs, package manifests, and project settings
  • run non-mutating commands
  • ask clarifying questions
  • create or update planning documents requested by the user

During implementation, Codex should:

  • follow the approved plan
  • update task status as work progresses
  • keep code, Unity assets, generated artifacts, and docs in parity
  • preserve unrelated user changes
  • preserve Unity .meta files with any asset add, move, rename, or delete
  • avoid editing Unity cache output such as Library/, Logs/, UserSettings/, generated .csproj, generated solution files, and package cache content as durable source
  • treat vendor/plugin assets as third-party unless the task explicitly targets them
  • run targeted verification
  • update ImplementationLog.md for large changes

Before major work, read the local files that match the scope:

  • docs/bootstrap/BootstrapContext.md
  • AGENTS.md
  • this workflow
  • relevant docs under docs/core and docs/state
  • ProjectSettings/ProjectVersion.txt
  • Packages/manifest.json and Packages/packages-lock.json
  • relevant Unity scripts, scenes, prefabs, generated files, or StreamingAssets
  • existing tests or CI configuration, if present

5. Small Change Workflow

For small changes, the user can prompt:

Small change: <describe change>.

First give me an inline implementation plan with affected files, docs impact, and verification. If this appears larger than a small change, stop and recommend switching to the large-change workflow.

Codex should respond with:

  • short implementation plan
  • affected files
  • docs impact
  • verification plan
  • whether it still qualifies as small

Implementation should begin only after user approval unless the user explicitly asks to proceed immediately.

After implementation, Codex must summarize:

  • code or asset changes
  • docs changes
  • tests or checks run
  • any remaining risks

6. Large Change Workflow

Step 1. Create Change Folder

The user may provide a high-level change name.

Codex should create:

docs/changes/<YYYY-MM-DD-HHMM-change-name>/

Codex should also add the new change folder to the Changes group in the nav section of mkdocs.yml, using the same folder name and the four standard change documents.

If the user has an existing docs/BrainDump.md, copy it into the change folder as BrainDump.md.

If the user provides new text in chat, write it into BrainDump.md.

Step 2. Create ChangeBreakdown.md

Codex reads BrainDump.md and creates ChangeBreakdown.md.

Codex should not implement code at this stage.

Step 3. User Answers Questions

The user edits ChangeBreakdown.md and adds answers under each question.

Step 4. Create ImplementationPlan.md

Codex reads the answered ChangeBreakdown.md and creates ImplementationPlan.md.

Codex should not implement code unless explicitly asked.

Step 5. Implement

Codex follows ImplementationPlan.md.

During implementation:

  • update task status as work progresses
  • preserve user changes
  • keep edits scoped
  • update docs in the same change
  • run targeted verification
  • update generated virtual-screen files when their source inputs changed
  • preserve .meta files when Unity assets are added, moved, renamed, or deleted
  • record render verification details when scene, playback, capture, or Python integration behavior changes
  • do not leave running sessions open

Step 6. Update ImplementationLog.md

At the end, Codex updates ImplementationLog.md with:

  • what changed
  • why it changed
  • docs updated
  • tests run
  • render, scene, capture, config, or protocol evidence when applicable
  • unresolved risks
  • recommended follow-ups

7. Docs Parity Rule

Every implementation must consider docs impact.

Docs must be updated when behavior changes in:

  • Unity renderer responsibilities, boundaries, or architecture
  • local workflows, agents, tools, verification commands, or contributor process
  • PresentationConfig fields, sample config behavior, generated artifacts, or integration contracts
  • Unity/Python protocol messages, ports, lifecycle, status, heartbeat, simulator, or remote render behavior
  • playback, timing, media loading, virtual screens, bot motion, camera directing, scene setup, capture, or output
  • Unity scenes, prefabs, serialized references, package dependencies, build settings, or Unity editor version
  • public config, renderer, preview, persistence, or generation jobs owned by this repository

Primary docs to update:

docs/core/
docs/state/
docs/process/
docs/changes/<change-folder>/

Use these local routing rules:

  • docs/core/UnityRendererRole.md for repository boundary and owned/not-owned behavior
  • docs/core/SystemArchitecture.md for runtime structure and lifecycle
  • docs/core/PresentationConfigRuntime.md and docs/state/PresentationConfigFieldMap.md for config model changes
  • docs/core/PythonServerIntegration.md and docs/state/PythonProtocolMap.md for ZeroMQ protocol changes
  • docs/core/VirtualScreensAndMedia.md, docs/state/MediaPipelineMap.md, and docs/state/RuntimeComponentMap.md for virtual screens, media, templates, bridge code, and generated HTML
  • docs/core/VirtualProductionFramework.md, docs/core/ScenePlaybackAndDirecting.md, and docs/state/SceneAndPrefabMap.md for scenes, bot motion, cameras, directing, and prefabs
  • docs/core/CaptureAndOutput.md, docs/core/TestingAndVerification.md, and docs/state/BuildAndRunCommands.md for capture, render output, and verification changes
  • docs/state/KnownGaps.md and docs/state/RecentDecisions.md when implementation confirms, closes, or introduces repo state gaps
  • docs/state/DocsUpdateChecklist.md when docs routing itself changes

docs/core should describe current system behavior.

docs/state should provide current implementation maps, operational facts, known gaps, verification commands, and dependency state.

docs/process should describe durable workflow and contributor process rules.

docs/changes should preserve change-specific reasoning and execution history.

Update or request updates in anuva-main-video-creator when a change affects product roadmap, product architecture, feature scope, repository impact, release readiness, product capability maps, cross-repository task breakdown, or acceptance criteria.

Update or request updates in anuva-engineering-handbook when a change affects shared engineering process, repository architecture, capability ownership, Codex workflows, templates, skills, prompts, standards, or publishing rules.

Report docs publishing impact when local docs should be surfaced through anuva-dev-docs.

Mermaid Documentation Rule

Docs are rendered with Material for MkDocs, so Mermaid diagrams should use fenced code blocks:

```mermaid
flowchart TD
  current["Current behavior"] --> target["Target behavior"]
```

New docs created under these folders must include at least one Mermaid diagram:

  • docs/core
  • docs/state
  • docs/process
  • docs/changes

When updating existing docs in those folders, add or revise Mermaid diagrams when documenting:

  • architecture, topology, Unity scene/runtime relationships, or service relationships
  • user, worker, render, API, protocol, or workflow sequences
  • config model relationships
  • readiness states, render states, retry behavior, or playback state machines
  • implementation phases or decision paths
  • docs/process rules that benefit from a visual workflow

Use flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, or classDiagram based on the content. Keep headings and prose free of emojis; emojis may remain inside Mermaid node labels only when they improve scanability.

MkDocs Nav Rule

The Material for MkDocs config lives at the repository root in mkdocs.yml, with docs_dir using the default project docs folder. Nav paths are therefore relative to docs/.

When a doc is created, renamed, moved, or deleted under these folders, update the nav section:

  • docs/core
  • docs/state
  • docs/process
  • docs/changes

Only edit the nav section of mkdocs.yml. Do not change theme, plugins, markdown extensions, CSS, hooks, metadata, or any other config section while performing a docs nav update.

flowchart TD
  docChange["Doc created, renamed, moved, or deleted"] --> tracked{"Under tracked docs folder?"}
  tracked -->|yes| nav["Update mkdocs.yml nav only"]
  tracked -->|no| skip["No MkDocs nav update required"]
  nav --> paths["Use paths relative to docs/"]
  paths --> verify["Run git diff --check and mkdocs build --strict"]

For normal docs, place the page under the matching top-level nav group: Core, State, or Process.

For change folders, use this Changes format in mkdocs.yml:

- Changes:
  - Change Name:
    - Brain Dump: changes/<YYYY-MM-DD-HHMM-change-name>/BrainDump.md
    - Change Breakdown: changes/<YYYY-MM-DD-HHMM-change-name>/ChangeBreakdown.md
    - Implementation Plan: changes/<YYYY-MM-DD-HHMM-change-name>/ImplementationPlan.md
    - Implementation Log: changes/<YYYY-MM-DD-HHMM-change-name>/ImplementationLog.md

8. Verification Expectations

Verification should match change risk.

Docs-only:

git diff --check
mkdocs build --strict

Unity import/compile smoke check when Unity is available and the change warrants it:

& "C:\Program Files\Unity\Editor\Unity.exe" -batchmode -quit -projectPath "$PWD" -logFile "Logs/UnityBatchmode.log"

Unity Test Runner when tests exist or the change warrants regression coverage:

& "C:\Program Files\Unity\Editor\Unity.exe" -batchmode -quit -projectPath "$PWD" -runTests -testPlatform EditMode -testResults "TestResults/EditMode.xml" -logFile "Logs/EditModeTests.log"
& "C:\Program Files\Unity\Editor\Unity.exe" -batchmode -quit -projectPath "$PWD" -runTests -testPlatform PlayMode -testResults "TestResults/PlayMode.xml" -logFile "Logs/PlayModeTests.log"

Virtual screen source/template changes:

Use Unity menu Anuva/Virtual Screens/Build HTML Files or enter Play Mode with the builder hook active.
Confirm generated outputs under Assets/StreamingAssets/AnuvaVirtualScreens/generated/.

Manual render, scene, or capture verification should record:

  • Unity editor version, currently 6000.3.14f1
  • scene path
  • config source URL/path
  • media source availability
  • Python communication enabled or disabled
  • simulator, local playback, or full Python-driven render mode
  • target resolution, frame rate, and output path
  • capture/render plugin settings changed
  • final MP4 existence and non-zero file size when capture is expected
  • Unity log warnings/errors
  • Python render.* messages, if running remote mode

Current known verification facts:

  • Docs dependencies are listed in requirements.txt and currently include mkdocs-material.
  • Unity Test Framework 1.6.0 is present.
  • No first-party NUnit/EditMode/PlayMode test assembly was discovered under Assets/Anuva.
  • Files with Tester in their names are manual/editor/play-mode helper components, not automated test suites.
  • No repository-specific Unity player build command or custom CI workflow was discovered.

If a check cannot be run, Codex must say why.

9. Escalation From Small To Large

Codex should recommend switching to the large-change workflow when:

  • the initial plan reveals cross-cutting work
  • the change requires unanswered product decisions
  • implementation touches risky shared contracts such as PresentationConfig.cs, AnuvaPythonServerCommunication.cs, render lifecycle, capture output, generated virtual-screen payloads, or package/build settings
  • serialized scenes, prefabs, materials, render textures, or project settings need coordinated edits
  • more than 4-6 files are likely to change
  • docs impact spans multiple core docs
  • tests require broad integration, scene, render, or Python server coverage
  • the change introduces migration, rollout, scene selection, worker launch, or cross-repository coordination concerns

Recommended response:

This is larger than a small change because <reason>. I recommend switching to the large-change workflow: create a dated change folder, produce ChangeBreakdown.md, answer open questions, then create ImplementationPlan.md before implementation.

10. Standard Prompts

Large Change From Existing BrainDump

Use the large-change workflow.

Create a new folder under docs/changes using the current UTC date-time and this change name: <change-name>.

Copy docs/BrainDump.md into that folder as BrainDump.md. Add the change folder to the Changes nav in mkdocs.yml, editing only the nav section. Then read it and create ChangeBreakdown.md with grouped changes, explanations, affected code/docs, risks, out-of-scope items, and open questions. Do not implement yet.

Large Change From Chat Notes

Use the large-change workflow.

Create a new folder under docs/changes using the current UTC date-time and this change name: <change-name>.

Create BrainDump.md from the notes below. Add the change folder to the Changes nav in mkdocs.yml, editing only the nav section. Then create ChangeBreakdown.md with grouped changes, explanations, affected code/docs, risks, out-of-scope items, and open questions. Do not implement yet.

<notes>

Create Implementation Plan

Read docs/changes/<change-folder>/ChangeBreakdown.md, including my answers.

Create ImplementationPlan.md as an execution-grade plan. Include goal, non-goals, current behavior, target behavior, affected files, affected docs, data/schema impact, ordered tasks, verification plan, docs parity checklist, and acceptance criteria. Do not implement yet.

Implement Approved Plan

Implement docs/changes/<change-folder>/ImplementationPlan.md.

Update task status as you work. Keep code, Unity assets, generated artifacts, and docs in parity. Update relevant docs/core or docs/state files. If tracked docs are created, renamed, moved, or deleted, update only the nav section of mkdocs.yml. Run targeted verification. At the end, update ImplementationLog.md and summarize code changes, docs changes, tests, and remaining risks.

Small Change Plan

Small change: <describe change>.

First give me an inline implementation plan with affected files, docs impact, and verification. If this appears larger than a small change, stop and recommend switching to the large-change workflow.

Small Change Implementation

Proceed with the small change plan.

Implement it, update affected docs, update only the nav section of mkdocs.yml if tracked docs are created, renamed, moved, or deleted, run targeted verification, and summarize code changes, docs changes, tests, and remaining risks.

11. Completion Criteria

A change is complete when:

  • implementation matches the approved plan
  • Unity assets and .meta files are consistent
  • docs are updated
  • tests/checks have been run or explicitly skipped with reason
  • generated files are updated when required
  • render verification details are recorded when scene, playback, capture, or Python integration behavior changes
  • ImplementationLog.md is updated for large changes
  • product-main, Python server, Web app, handbook, or docs-publisher gaps are reported when ownership or cross-repository planning is affected
  • remaining risks or follow-ups are clearly listed