| 1 | # DOX Workflow |
| 2 | |
| 3 | ## Source Anchors |
| 4 | |
| 5 | - Root DOX contract: `/a0/AGENTS.md` |
| 6 | - Skill parent contract: `/a0/skills/AGENTS.md` |
| 7 | - Local skill contract: `/a0/skills/a0-development/AGENTS.md` |
| 8 | - Reference-file contract: `/a0/skills/a0-development/references/AGENTS.md` |
| 9 | - File-level DOX examples: `/a0/api/*.py.dox.md`, `/a0/tools/*.py.dox.md`, `/a0/helpers/*.py.dox.md` |
| 10 | |
| 11 | ## Before Editing |
| 12 | |
| 13 | 1. Read the root `AGENTS.md`. |
| 14 | 2. Identify every path you expect to touch. |
| 15 | 3. Walk from the root to each target path. |
| 16 | 4. Read every `AGENTS.md` found on that route. |
| 17 | 5. If a parent `AGENTS.md` lists a child whose scope contains the path, read that child and continue. |
| 18 | 6. Use the nearest `AGENTS.md` as the local contract. Parent docs still apply. |
| 19 | 7. If docs conflict, the closer doc controls local details, but no child weakens DOX. |
| 20 | |
| 21 | Do not rely on memory for DOX. Re-read the current files. |
| 22 | |
| 23 | ## When To Update DOX |
| 24 | |
| 25 | Update the nearest owning `AGENTS.md` when a meaningful change affects: |
| 26 | |
| 27 | - Purpose, ownership, responsibilities, or scope. |
| 28 | - Durable structure, directories, file contracts, or child indexes. |
| 29 | - Runtime behavior, required inputs/outputs, side effects, or verification rules. |
| 30 | - User or agent workflow rules. |
| 31 | - Creation, deletion, rename, or movement of an `AGENTS.md` file. |
| 32 | |
| 33 | Update parent docs when parent-level structure or child indexes change. Remove stale or contradictory text rather than explaining old history. |
| 34 | |
| 35 | Small implementation edits that do not change contracts may leave DOX unchanged, but still perform the DOX closeout pass and say why docs stayed unchanged. |
| 36 | |
| 37 | Do not create or update DOX under ignored `usr/` or `tmp/` unless explicitly requested. |
| 38 | |
| 39 | ## File-Level DOX |
| 40 | |
| 41 | Some directories require per-file `.dox.md` companions: |
| 42 | |
| 43 | | Directory | Requirement | |
| 44 | |---|---| |
| 45 | | `api/` | Every direct `*.py` endpoint or `ws_*.py` module must have matching `*.py.dox.md`. | |
| 46 | | `tools/` | Every direct `*.py` tool module must have matching `*.py.dox.md`. | |
| 47 | | `helpers/` | Many helper modules use file-level DOX; follow `helpers/AGENTS.md` before changing helper behavior. | |
| 48 | |
| 49 | When adding, deleting, renaming, or behaviorally changing one of those files, update the companion DOX in the same change. |
| 50 | |
| 51 | ## Closeout |
| 52 | |
| 53 | 1. Re-check changed paths against the DOX chain. |
| 54 | 2. Update nearest owning docs and affected parents or children. |
| 55 | 3. Refresh affected Child DOX Index tables. |
| 56 | 4. Remove stale or contradictory text. |
| 57 | 5. Run relevant verification from the nearest DOX. |
| 58 | 6. Report docs intentionally left unchanged and why. |
| 59 | |
| 60 | ## Practical Verification |
| 61 | |
| 62 | - `git diff --check` for whitespace. |
| 63 | - Targeted tests named by the relevant DOX file. |
| 64 | - Manual read-through for skill/reference link changes. |
| 65 | - Shell coverage checks for file-level DOX when touching `api/` or `tools/`. |
| 66 | - Runtime or live-container proof when the user asks about the running Dockerized system. |