feat: make main DOX framework non editable by agents

[Rare-Programmer]

I found that on first run agents overwrite the core part of the DOX framework. With the main DOX framework removed agents stop editing any of the AGENTS.md files after every edit. They also lose context of what a DOX framework is.

Making the main DOX framework non removable helps agents always follow DOX instructions and make edits to AGENTS.md files

[BlueboxC]

Thanks for raising this. We use a complementary separation that may help with the failure described here.

In our setup, AGENTS.md retains the DOX framework/entry instructions, while the evolving project and domain contracts live in a hierarchy of DOX.md files:

AGENTS.md          # Framework rules and explicit instructions to read DOX
DOX.md             # Project scope, ownership, contracts and child index
src/DOX.md         # Local domain contracts
src/api/DOX.md     # More specific contracts where needed

This separates the framework from the material agents are expected to maintain. It also keeps project/module documentation separate from agent roles, tool setup and other integrations that may add their own sections to AGENTS.md. Mixing those responsibilities in the same instruction file can create conflicting guidance, blur module boundaries and cause the always-loaded context to grow.

PR #4 specifically addresses agents overwriting the framework itself. Using DOX.md for the editable hierarchy complements its preservation markers; changing the filename alone does not prevent framework edits or incorrect code changes.

The entry-point contract must explicitly require agents to:

• Read the root DOX.md, every applicable parent and the nearest local contract before editing.
• Preserve the framework while updating affected project contracts and child indexes after meaningful changes.
• Keep unrelated project/domain responsibilities in their owning scopes; child contracts must not weaken the framework.

An arbitrary DOX.md filename is not automatically recognized by every agent client, so the explicit read instruction is essential. Where a client automatically injects AGENTS.md, this design can keep growing domain documentation behind scoped reads instead of automatic injection. We have not measured token savings, and they depend on the client's loading behavior.

Would an optional “stable framework in AGENTS.md + maintained project hierarchy in DOX.md” convention be useful alongside this PR? It preserves DOX's Markdown-only approach and does not require another runtime.

Published adaptation

The implementation is now available in our DOX Scope fork, at commit 1132dc46.

• Stable AGENTS.md framework, with explicit DOX.md hierarchy reads and preservation markers.
• Adoption guide and root/child contract templates, kept separate from the fork's own project index.
• Optional Beads continuity instructions for already initialized workspaces; no installation, database initialization or hook changes are performed.

We checked document links, template structure and the published file contents. The upstream MIT license and image assets remain unchanged. This is a reusable, Markdown-only implementation; it does not claim measured context savings or enforced protection against agents editing the framework.

BlueboxC