Skip to content

Change Workflow

This document defines how implementation changes should be planned, executed, verified, and documented in anuva-python-server.

The goal is to keep code, docs, tests, and project reasoning in parity while preserving the Python Server's worker boundaries.

flowchart LR
  request["Change request"] --> size{"Small or large?"}
  size --> small["Small: inline plan"]
  size --> large["Large: docs/changes folder"]
  small --> implement["Implement after approval or explicit proceed"]
  large --> breakdown["ChangeBreakdown.md"]
  breakdown --> plan["ImplementationPlan.md"]
  plan --> implement
  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 behavior
  • affects a small number of files
  • does not change worker-facing Web App contracts, Unity ZeroMQ contracts, local workspace layout, job status semantics, upload behavior, public config, secrets handling, or repository ownership boundaries
  • does not change core render orchestration flows, Unity lifecycle behavior, simulator state transitions, dashboard mutation behavior, or operational commands
  • can be verified with a targeted test, docs build, or inspection
  • needs only a small docs update, if any

Small changes still require docs updates when behavior changes.

Large Change

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

  • render job discovery, claiming, preparation, execution, completion, failure, retry-safety, or cancellation behavior
  • Web App worker API models, endpoint assumptions, auth, signed upload, direct upload, status, heartbeat, or package contracts
  • Unity command/event protocol, ZeroMQ topology, readiness, heartbeat, EXE process control, restart policy, or Editor Play Mode assumptions
  • local content serving, dashboard controls, simulator scenarios, simulator state machine, or operator scripts
  • worker configuration keys, environment variables, ports, local path layout, NSSM/service behavior, or Windows production assumptions
  • output validation, thumbnail generation, diagnostics, health snapshots, log redaction, or signed URL handling
  • data models, generated artifacts, generated docs, import/package boundaries, or public CLI commands
  • framework, dependency, platform, or Python version upgrades
  • more than 4-6 implementation files
  • unclear product behavior, unresolved Web App or Unity contracts, or cross-repository dependencies

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-07-06-1030-unity-render-cancellation/

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 flow, dependency map, or decision structure
  • explanation for each change
  • affected product surfaces
  • likely affected code paths
  • likely affected docs
  • risks and dependencies
  • out-of-scope items
  • 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, data flow, or affected system relationships
  • assumptions
  • affected files and modules
  • affected docs
  • data/schema/migration 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 data model
- [ ] 3. Update workflow
- [ ] 4. Update integration or runtime behavior
- [ ] 5. Update tests
- [ ] 6. Update docs
- [ ] 7. Run verification

ImplementationLog.md

Updated during and after implementation.

It should contain:

  • date/time started
  • date/time completed
  • tasks completed
  • Mermaid diagram for the implemented flow, state transition, dependency shape, or final change sequence
  • files changed
  • docs updated
  • tests and commands run
  • 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
  • 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 and docs in parity
  • preserve unrelated user changes
  • keep unresolved Web App and Unity contracts behind webapp/ and unity/ boundaries
  • keep simulator behavior aligned with worker-facing contracts
  • keep local services bound to localhost by default unless a reviewed requirement says otherwise
  • preserve one-active-job V1 behavior unless the approved plan explicitly changes it
  • keep secrets, cookies, private keys, bearer tokens, and signed URL query strings out of committed files, logs, diagnostics, and dashboard summaries
  • run targeted verification
  • update ImplementationLog.md for large changes

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 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 to this repository
  • update docs in the same change
  • run targeted verification
  • update generated files when required
  • do not modify Web App, Unity, product-main, handbook, or docs-publisher repositories from this workspace unless the user explicitly switches to that repository and asks for that work
  • 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
  • unresolved risks
  • recommended follow-ups

7. Docs Parity Rule

Every implementation must consider docs impact.

Docs must be updated when behavior changes in:

  • render job discovery, claiming, workspace preparation, status/progress updates, completion, failure, upload, retry-safety, or cancellation
  • Web App worker API assumptions, auth, endpoint paths, package models, summaries, heartbeats, upload targets, or simulator alignment
  • Unity protocol messages, ZeroMQ topology, process launch args, readiness, heartbeat, render events, cancellation, shutdown, or restart behavior
  • local dashboard controls, simulator scenarios, content server routes, operator scripts, CLI commands, or NSSM/service guidance
  • public config keys, environment variables, ports, paths, local certs, logging, redaction, diagnostics, or security expectations
  • output validation, thumbnail generation, health snapshots, system/GPU metrics, or troubleshooting flows
  • tests, verification commands, generated artifacts, or docs navigation

Primary docs to update:

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

docs/core should describe durable role, architecture, protocol, lifecycle, integration, configuration, recovery, simulation, and verification concepts.

docs/state should describe the current repository state: file maps, module maps, command maps, environment/service facts, test coverage, known gaps, recent decisions, and implementation status.

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

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

Use docs/state/DocsUpdateChecklist.md to route docs parity updates for this repository.

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, or service relationships
  • worker, Web App, Unity, dashboard, simulator, API, or CLI sequences
  • data model relationships
  • state machines, readiness states, cancellation, upload, retry, or recovery behavior
  • 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 paths relative to the project docs/ folder.

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"]

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.

Always run:

git diff --check

Common commands:

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m pytest tests\unit
.\.venv\Scripts\python.exe -m pytest tests\integration
.\.venv\Scripts\python.exe -m mkdocs build --strict

Use the lightest relevant checks:

  • docs-only changes: run git diff --check and .\.venv\Scripts\python.exe -m mkdocs build --strict; verify Mermaid fences and MkDocs nav when docs are created, renamed, moved, or deleted
  • config, model, path-safety, manifest, checksum, protocol serialization, output validation, upload strategy, simulator state, dashboard route, health, or redaction changes: run focused unit tests under tests\unit
  • simulator HTTP, fake Web App, fake Unity ZeroMQ, dashboard manual claim, lifecycle completion, upload, or cancellation changes: run focused integration tests under tests\integration
  • route, runtime, Unity lifecycle, Web App integration, or full workflow changes: consider a manual smoke flow from docs/User_Guide.md or docs/Operations.md
  • framework/dependency/platform changes: run install/build-relevant checks and the broadest practical pytest scope

There is currently no repository-local Ruff or mypy configuration. Do not present lint or typecheck commands as required checks unless config is added.

If Unity, FFmpeg/ffprobe, OpenSSL, real Web App services, S3, Windows service behavior, or an interactive graphics session is required but unavailable, say exactly what was not verified and 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 Web App, Unity, dashboard, simulator, upload, security, or operational contracts
  • more than 4-6 files are likely to change
  • docs impact spans multiple core docs
  • tests require broad integration coverage
  • the change introduces migration, rollout, service, Windows session, or recovery concerns
  • the work requires changes in Web App, Unity, product-main, handbook, or docs-publisher repositories

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 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
  • docs are updated
  • tests/checks have been run or explicitly skipped with reason
  • generated files are updated when required
  • ImplementationLog.md is updated for large changes
  • mkdocs.yml nav is updated when tracked docs are created, renamed, moved, or deleted
  • remaining risks or follow-ups are clearly listed
  • cross-repository follow-ups for Web App, Unity, product-main, handbook, or docs publishing are recorded instead of being silently encoded in this repository