Consider an optional machine-checkable convention for AGENTS.md trees

[dgenio]

Context

Dox's hierarchy is useful because it turns AGENTS.md from a single global instruction file into scoped local contracts.

One thing I’m wondering: should there be a tiny optional machine-checkable convention for the tree?

The goal would be to keep Dox Markdown-first and copy-paste simple, while making it possible for external tooling to validate the structure when teams want CI support.

Possible convention

For example, Dox could define a minimal structural convention around:

• parent AGENTS.md files listing child AGENTS.md scopes;
• child docs declaring a stable section shape such as purpose, ownership, local contracts, work guidance, verification, and child index;
• a deterministic linter detecting stale child indexes, missing local docs for durable boundaries, or obvious parent-child structural inconsistencies;
• tools generating or validating the tree without changing the Markdown-first nature of Dox.

Why this might help

The nice property is that Dox would remain simple: copy one file and let the agent maintain local context.

But teams that use Dox in larger repos could optionally add validation in CI, catching cases where an agent changes code or workflows but forgets to update the relevant local AGENTS.md index or contract.

I’m exploring adjacent tooling around reviewed AGENTS.md guidance and deterministic PR checks, so I’d be happy to contribute a small proposal if this direction fits the project.

Non-goals

• Not proposing a runtime dependency.
• Not proposing to make Dox less Markdown-first.
• Not proposing a heavy schema for all prose content.

This would only be an optional convention for tools that want to reason about the tree structure.