How to Keep AGENTS.md Current Automatically with dox

Why your AGENTS.md wrong after three weeks

AGENTS.md file dey go stale because nothing connect am to the code. You write am once, by hand, for the day wey repository look one particular way. Later, test runner change, dem rename package, dem delete service, but the file still dey describe June. Nothing fail because no build step dey read am.

Agent read am and believe wetin e talk. Na this part dey cost you. Repository wey no get AGENTS.md make coding agent look around before e act. Repository wey get wrong AGENTS.md make am stop to look because e don already get answer. E run the command wey your file name, shell answer Missing script: "test", and now agent start to guess. Many times, e edit package.json to add the script wey your documentation promise. The stale file no fail quietly. E cause edit wey you no want.

dox na one answer to this problem. Na set of rules wey dem write for agent. E make documentation update part of finishing the work, so the file change for the same commit with the code wey make am wrong.

Wetin dox be, and wetin e no be

dox na one Markdown file. The repository na agent0ai/dox, e get MIT license, and as of 11 August 2026 the whole project na one 3906-byte AGENTS.md, one README, one LICENSE and two images. No package dey to install, and no runtime dey.

This matter because the word generator fit make person think say na program wey dey parse your code. Nothing dey parse your code. dox na contract wey your coding agent dey read: your agent na the generator, and dox na the instruction set wey dey tell am when to read the docs, when to rewrite dem, and the format wey each document suppose get.

The file get ten sections, and two of dem dey do the main work. "Read Before Editing" dey tell the agent make e trace every path wey e plan touch from the repository root, and make e read every AGENTS.md wey e meet for each route, for the current session, without relying on memory. "Update After Editing" dey tell am say every meaningful change need DOX pass, meaning say e must run documentation update step before the task fit count as done. The pass dey update the nearest owning document when purpose, structure, workflow, permissions or user preferences change.

The remaining sections na about format. A child AGENTS.md get default section order: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index. The root file hold project-wide rules plus the top-level Child DOX Index, wey agent dey use discover the child documents. "Closeout" na the checklist wey agent dey run at the end of task: check the changed paths again against the chain, update the nearest owning docs, refresh every affected index, delete contradictions, run existing verification, and report which docs e deliberately leave untouched.

Pin dox to one commit, no be main

The repository no get tags and no releases, so no version number dey to pin. Pin the commit instead. The current AGENTS.md na commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, dated 1 August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c suppose print 3906. If e print different number, e mean say you no fetch the file wey this guide dey describe, so read am before you trust am. If you type the commit hash wrong, -f go make curl stop with curl: (22) The requested URL returned error: 404 and e no go write any content, while wc -c go then print 0. Truncated file worse pass no file, because the agent go follow half contract without knowing am.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

That cp na for repository wey never get AGENTS.md. If you already get one, no overwrite am. Put the dox sections above your existing content, keep your own rules underneath, then read the result once from top to bottom. Two documents wey contradict each other go make agent follow whichever line e read last.

Then ask your agent, inside the repository, to do the first pass. The README get the exact wording:

Initialize DOX tree for this project now.

E go create the child AGENTS.md files and the indexes wey point to dem. Check wetin e do before you believe am:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Every file for that find output suppose appear for one Child DOX Index somewhere above am. If no index mention a child document, agent fit miss am, because na the index dey help am find documents wey no dey directly for the path wey e dey walk.

Wetin dox fit see, and wetin e no fit know

The agent wey dey build your tree dey read the repository, so anything wey dey inside the repository fit enter the inventory: the directory layout, package manifests and lockfiles, the scripts for package.json or Makefile or pyproject.toml, CI workflow files, Dockerfiles, entry points, and CODEOWNERS if you get one. Inventory wey dem build from these things fit maintain itself well. When package move, the next pass go move the line wey describe am.

Everything wey dey below na your responsibility to state, because e no dey inside the repository for the agent to read:

• why rule dey exist, because na this dey stop agent from remove am as unnecessary complexity
• which one of two working paths dey supported, and which one dey wait for deletion
• anything outside the repository, like the staging environment or why dependency dey pinned two versions behind
• wetin you plan do next week, because na this be the difference between file wey current and file wey useful

dox know this about itself. Its own rules talk say Work Guidance must reflect the current standards of the project or the user's instructions, and if no such standards dey yet, you leave the section empty. Verification must reflect an existing check, so if no test framework dey for the repo, that section go remain empty until one dey. Generated file wey invent standard worse pass empty section, because agent go then enforce the invention.

Hand-written intent no dey enter generated inventory

Na this failure dey make people abandon generated docs. You write paragraph wey explain say jobs queue must remain single consumer. Three weeks later one pass rewrite the file and your paragraph disappear inside diff of forty lines wey mostly rearrange file names, and nobody notice am.

Two mechanisms dey, and you need both.

First, move durable intent go another file. Design decisions and the reasoning behind dem belong for DESIGN.md wey agent fit read, while notes wey people need belong where you separate HUMAN.md from AGENTS.md. AGENTS.md then hold the inventory and local contracts. Na exactly this part suppose change when code change.

Second, fence the intent wey must remain inside AGENTS.md. Put am inside markers and treat the block as human-owned:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown comments no dey render for the page, but agent still dey read dem. Now make the block survival checkable, so any pass wey remove am go fail loudly. Run this for CI (continuous integration) on every pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff no dey print anything and e exits 0 when nobody touch the block. Any output mean say the pass rewrite human-owned text, so person must approve am or revert am. The check go work without anybody needing remember am.

Regenerate for the pull request, no be on timer

The best time to refresh document na when commit make am wrong. Put DOX pass for the same pull request with the structural change, so the diff remain small enough for person to actually read.

A blocking check wey enforce am:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Adjust the paths to match your repository. The benefit be say e fail for the branch, where fixing am cheap, and e fail for reason wey reviewer fit act on.

Schedule na backup, e no be the main mechanism. Weekly job go catch things wey nobody notice for branch: files wey rebase move, package wey merge delete, or document wey still name directory wey no longer exist. Run am for small box, the same one wey you fit use to run coding agent for VPS, and make am open pull request instead of pushing to main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

That comment na placeholder deliberately. Every agent get im own CLI (command line interface) and im own non-interactive flag. Command wey person copy from web page but no match your version go fail inside cron, where nobody go see the error. Fill am in, then run the script by hand once before you schedule am. The || exit 0 matter too: git commit exits non-zero with nothing to commit, working tree clean when the tree already current, and under set -e that one go report healthy run as failure.

Every pass dey cost tokens, because "Read Before Editing" make agent read the whole chain for every task. Na the trade-off be that, and e worth monitoring if you already dey count wetin your agent runs cost.

Monorepos: plenty contracts, one index

One root AGENTS.md for repository wey get forty packages fit produce regeneration diff wey nobody dey read, plus document wey mostly no relate to wetin agent dey do now. dox solution na Child DOX Index: root dey keep repo-wide rules and point to the child files, while each durable boundary dey own im own file. How to arrange that tree, and which tools dey read nested files at all, dey covered for nested AGENTS.md files for monorepos.

Wetin dox change na the review surface. Pull request wey touch packages/api suppose produce documentation diff inside packages/api and nowhere else:

git diff --stat -- '*AGENTS.md'

If that command list six files for change wey affect one package, the tree no correct. Either the boundaries too broad, or person copy rule wey belong for root into every child. dox state the fix directly: broad rules go inside parent docs, while specific details go inside child docs. Na duplicated rules dey make routine pass rewrite everything. If the same rules truly apply across separate repositories, na different problem be that, and sharing agent skills across repositories na the better tool for am.

Review diff like code

Generated documentation diff easy to approve without reading am. Na so wrong file fit ship. Read am with the same suspicion wey you go use for generated code, and look for four things.

• command wey file don add now, wey you suppose run by yourself before you merge am. Fake build instructions na the most common failure.
• deleted line wey carry important intent. Additions cheap. Na deletions dey cause the loss.
• absolute path, hostname, internal URL, or anything wey look like credential
• inventory entry for something wey no longer exist, wey ls fit settle within one second

Then check the size with wc -l AGENTS.md. If root file pass two hundred lines, na signal say you suppose split am, because the whole value of the chain na say agent go read the small relevant part instead of everything.

When e break

The pass delete your intent block. The diff check above dey print the lines wey e remove. Restore the file from the branch point with git restore --source=origin/main AGENTS.md, then run the pass again with narrower instruction wey name the sections e fit touch.

Two branches regenerate am both. You go see CONFLICT (content): Merge conflict in AGENTS.md and conflict markers <<<<<<< HEAD inside the file. No hand-edit the markers. The file na generated file, so the correct resolution na fresh pass over the merged tree.

The agent ignore the file completely. Check which filename your tool really dey read. If e dey read another one, point am to the same content with ln -s AGENTS.md CLAUDE.md and commit the symlink, so you get one source instead of 2 documents wey fit drift apart.

The tree grow children wey nobody index. Compare the find . -name AGENTS.md output with the index entries for the parent documents. If no index mention one child, the agent fit walk pass am directly.

When generator no dey necessary

One package, one test command, and two people wey both sabi the repository: write the twenty lines by hand. Twenty-line AGENTS.md no dey become stale quickly enough to justify tree, index, CI check, and weekly job. Read am again whenever you change the build. Na the complete maintenance cost be that, and e smaller than the cost of the machinery around am.

dox worth paying for when repository get boundaries wey nobody fit hold for head alone: several packages wey get different rules, or contributors wey dey join without the background knowledge. The value no be the generated text. Na say the documentation become something wey pull request fit fail because of, and na only that fit make any file for repository stay current.

FAQ

I need install anything before I fit use dox?

No. dox na one Markdown file, MIT licensed, and as of 11 August 2026 the repository no get any package or releases. You copy the content enter your project AGENTS.md, and your coding agent follow the rules from there. Pin the commit wey you copy, f34ec7ad1055d3393887e5a2670e8cb7320c9165 as at the time of writing, and put the name for your commit message so you fit know later which version of the rules your tree use.

How I fit stop regeneration from deleting rules wey I write by hand?

Keep intent and inventory separate. Put durable reasoning for another document, and put anything wey must remain inside AGENTS.md inside a marked block. Then check the block for CI: extract am from the branch and from origin/main with sed, compare both with diff, and make the build fail if any difference dey. Person go then approve or revert the change, instead make e pass unnoticed inside one large diff.

How often I suppose regenerate AGENTS.md?

For the pull request wey make am wrong. Structural change and the documentation for am suppose dey one diff, because na only that time person get the context to review both. Weekly scheduled pass na backup for drift wey escape from a branch, and e suppose open pull request instead make e commit to main.

Build commands suppose dey for root AGENTS.md or for child?

Put dem for the nearest document wey own dem. Repo-wide rules and the child index dey for root. Command wey apply to one package dey for that package AGENTS.md. dox resolve conflicts by distance: the document wey near controls local details, and no child fit weaken parent rule. Copying the same command enter every child na wetin make routine pass rewrite the whole tree.

dox worth am for small repository?

Usually no. One package with one test command and twenty-line AGENTS.md dey decay slowly, and you fit fix am within the minute wey you notice. dox earn the cost when repository get several boundaries with different rules, or contributors wey no get the background, because then the chain of documents dey do work wey no single person dey do.