Skip to content

Change Workflow

This document defines how implementation changes should be planned, executed, verified, and documented in Anuva CMS.

The goal is to keep code, docs, tests, and project reasoning in parity.

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 Payload schema
  • does not change Mastra workflow contracts
  • does not change billing, RAG, auth, or generation-job behavior
  • can be verified with a targeted test 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:

  • Presentation Video creation flow
  • Mastra agents, workflows, tools, or memory
  • Payload collections, migrations, generated types, or import map
  • public config, compilation contracts, scene persistence, or renderer/preview behavior
  • RAG ingestion, retrieval, source handling, or embeddings
  • billing, coins, subscriptions, content entitlements, or payment integration
  • auth, workspace boundaries, access control, or tenant isolation
  • workers, queues, generation jobs, or long-running scripts
  • framework upgrades such as Payload, Mastra, Next.js, React, Better Auth, or AI SDK
  • more than 4-6 implementation files
  • unclear product behavior or unresolved requirements

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-generic-presentation-video-flow/

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 UI
- [ ] 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
  • 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
  • update docs in the same change
  • run targeted verification
  • update generated files when required
  • 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:

  • Presentation Video flow
  • Mastra workflows, agents, tools, or contracts
  • Payload collections or public APIs
  • RAG ingestion or retrieval
  • billing, coins, entitlements, or payment flows
  • auth or workspace behavior
  • workers, scripts, or operational commands
  • public config, renderer, preview, or generation jobs

Primary docs to update:

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

docs/core should describe current system behavior.

docs/state can provide routing, backend, or operational orientation.

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

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

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
  • user, worker, API, or workflow sequences
  • Payload collection relationships
  • state machines, readiness states, or retry 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_dir set to the 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"]

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

For change folders, use the Changes format already shown 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.

Common commands:

pnpm lint
pnpm typecheck
pnpm test:int
pnpm test:e2e
pnpm generate:types
pnpm generate:importmap

Guidelines:

  • docs-only changes: run git diff --check; verify Mermaid fences are balanced; update only the nav section of mkdocs.yml when tracked docs are created, renamed, moved, or deleted; use targeted stale-term scans when replacing concepts
  • schema changes: run pnpm generate:types and pnpm generate:importmap
  • Presentation Video generation changes: run pnpm test:int
  • route or full workflow changes: consider pnpm test:e2e
  • framework upgrades: run install, typecheck, lint, relevant tests, and smoke checks

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
  • more than 4-6 files are likely to change
  • docs impact spans multiple core docs
  • tests require broad integration coverage
  • the change introduces migration or rollout 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 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
  • remaining risks or follow-ups are clearly listed