Implementation Repository Change Workflow Template
Use this template for docs/process/ChangeWorkflow.md in implementation repositories.
The structure intentionally matches the Anuva CMS implementation workflow, including the Standard Prompts section. Replace repository-specific examples, risky areas, and verification commands before committing.
# Change Workflow
This document defines how implementation changes should be planned, executed, verified, and documented in `<repository-name>`.
The goal is to keep code, docs, tests, and project reasoning in parity.
```mermaid
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 `<repository-specific risky contract>`
- 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:
- `<core product flow>`
- `<workflow, worker, agent, tool, or integration contract>`
- `<schema, migration, generated artifact, or import map>`
- `<auth, billing, entitlement, persistence, renderer, or runtime area>`
- framework or platform upgrades
- 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:
```text
docs/changes/<YYYY-MM-DD-HHMM-change-name>/
```
Use UTC time unless the user specifies otherwise.
Example:
```text
docs/changes/2026-05-17-1430-generic-presentation-video-flow/
```
Required files:
```text
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:
```md
### 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:
```md
## 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:
```text
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:
```text
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.
Primary docs to update:
```text
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:
```md
```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`
### 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.
```mermaid
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`.
## 8. Verification Expectations
Verification should match change risk.
Common commands:
```text
<lint command>
<typecheck command>
<test command>
<build command>
<generated artifact command>
```
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:
```text
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
```text
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
```text
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
```text
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
```text
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
```text
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
```text
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