v5.0.0 — portable agent authoring layout

Breaking packaging update: moves the six canonical skills to .agents/skills, adds byte-identical Claude mirrors and thin Cline workflows, supports Pi, and consolidates persistent rules through host instruction pointers.

Full Changelog: v4.0.0...v5.0.0

v4.0.0 — user-global install model

Breaking: DOX tooling now installs user-global. The agent-guided AGENT-INSTALL.md is the only install path (no install scripts) and never writes into a project — not even .gitignore.

• Skills and rule install once per user: ~/.agents/skills/ (Codex), ~/.claude/skills/ (Claude Code), ~/.gemini/config/skills/ (Antigravity), ~/.cline/skills/ (Cline); rule via global rules locations plus marker-guarded pointer blocks in ~/.codex/AGENTS.md / ~/.claude/CLAUDE.md.
• Project truth stays committed and is owned by the skills: the DOX.md tree and the root AGENTS.md/CLAUDE.md anchors (DOX shim) created or merged by dox-init / dox-upgrade. A fresh clone steers any agent to DOX.md with zero tooling installed.
• Cursor explicitly supported: discovers the shared global skill copies natively and reads AGENTS.md anchors root and nested — no separate install target.

Migration from v3 project-scoped installs: re-run the install prompt once per user; old gitignored project adapters and marker ignore blocks can be removed manually (with review).

v3.1.0 — agent-guided install & gitignored adapters

Highlights

• AGENT-INSTALL.md — a merge-aware install procedure for AI agents, now the preferred install path (paste the README prompt into Codex, Claude Code, Antigravity, or Cline). It audits for skill-name collisions, preserves existing AGENTS.md / CLAUDE.md, and reports every change.
• Gitignored adapters — both installers now add a marker-guarded .gitignore block for the generated skill/rule adapters. Root bridges (AGENTS.md, CLAUDE.md, DOX.md) stay tracked; fresh clones simply re-run the installer to regenerate the adapters.

No changes to the framework rules or skills themselves. Fully compatible with v3.0.0 installs — re-run the installer to pick up the gitignore block.

v3.0.0 — DOX.md rename & universal multi-harness toolchain

Breaking: the framework doc is now DOX.md

AGENTS.md has become a shared convention across AI coding harnesses (Codex, Claude Code, Copilot, Cursor, …), so using it for the DOX framework created conflicts. The framework rules now live in DOX.md; a lightweight root AGENTS.md shim points harnesses at it, and CLAUDE.md bridges Claude Code via @AGENTS.md.

Migrating from v2

Run the dox-upgrade skill — it merges the new framework rules while preserving all project content, renames confirmed legacy DOX docs to DOX.md, and creates the AGENTS.md / CLAUDE.md bridges. A no-skills prompt version is in the README. Legacy pre-v3 roots are still detected and governed until you migrate.

Universal multi-harness toolchain

• One installer (install.sh / install.ps1) replaces the Cline-only installers: portable Agent Skills go to .agents/skills/ (Codex, Antigravity, Cline) and .claude/skills/ (Claude Code), with the shared always-on rule in each host's rule directory. Each file is fetched once and copied to sibling locations; existing root instruction files are never overwritten, and a legacy v2 framework root is detected and pointed at dox-upgrade.
• Skills are now shared (skills/shared/), using only portable name/description metadata, and all understand both DOX.md and legacy AGENTS.md roots, nested-root boundaries, and the harness bridges.
• New dox-remap skill — a deep code-reading pass that rebuilds and refines every Feature Map: discovers unmapped features, retires defunct entries, fixes orphaned/mislocated entries.
• Deeper dox-audit / dox-fix — new checks for orphaned, mislocated, and unmapped Feature Map entries, legacy filenames, and the AGENTS.md/CLAUDE.md bridges.
• Hardened legacy handling — every AGENTS.md is classified (shim / legacy framework root / legacy child / unrelated harness file) before any rename; destination conflicts are reported, never overwritten; nested roots under either filename stay untouched.

v2.0.0 — Cline toolchain & versioned framework

DOX v2 turns the framework into a toolchain: Cline skills for every core workflow, an always-on rule, a one-line installer, and — the reason this is a major version — framework versioning with an upgrade path.

Why v2

From this release on, every framework copy carries a DOX vX.Y.Z marker at the top of AGENTS.md. Everything before is deliberately left unmarked: any AGENTS.md without a marker is the untracked v1 era. The mental model is one sentence — has a marker: v2+; no marker: run /dox-upgrade once to enter the versioned era. Your project content (User Preferences, Feature Map, Child DOX Index, imported rules) survives the migration.

Cline skills

Install from your project root:

curl -fsSL https://raw.githubusercontent.com/jpbaking/dox/main/install-cline.sh | sh

(sh -s -- --global installs for every project; re-run anytime to update.)

• /dox-init — initialize the tree; detects new project vs. existing codebase, and fetches the framework AGENTS.md if it is missing.
• /dox-child — give it a folder path; it runs the boundary test and either initializes a child doc (wired into the parent) or explains why the folder does not deserve one.
• /dox-audit — read-only health check (lint) by severity; now includes a best-effort framework version-drift check.
• /dox-fix — audit + auto-repair of the mechanical problems; nested roots are off-limits, judgment calls come back to you.
• /dox-upgrade — migrate the framework rules in the root AGENTS.md to the latest release without losing project content, then reconcile the tree.

Cline rule

A small always-on rule: finds each edited file's DOX root (one workspace can hold several independent projects, each with its own root), complies with that chain when it exists, and merely suggests /dox-init — once, one sentence — when it does not. It never initializes on its own.

Also

• README now states who this fork is for (smaller/weaker models), quantifies the root-doc context overhead (~15 KB ≈ 3.5–4k tokens/session), and points consistent frontier-model users to the leaner original: https://github.com/agent0ai/dox

Full changelog: v1.2.0...v2.0.0

v1.2.0 — Root Feature Map & nested roots (multi-VCS)

The root AGENTS.md now carries its own Feature Map, and the framework gains nested roots — first-class support for composing independently versioned projects (git submodules, SVN externals, Perforce mapped paths) that each have their own root DOX.

Root Feature Map

• The root AGENTS.md holds a Feature Map under exactly the same rules as child docs: it owns features whose lowest common subtree is the whole project, plus the project's primary system-wide features, pointing into the owning child docs when detail lives deeper.
• Ships with a "Not yet mapped" placeholder that the Initialization procedure fills, mirroring how "Not yet indexed" works for the Child DOX Index.

Nested roots

• A nested root is a sub-root that is also the root of its own independently versioned project. The marker is VCS-neutral and mechanical: any folder whose AGENTS.md carries the full DOX rules is a nested root — the same doc works whichever folder an engineer roots their workspace at.
• Five explicit rules: leave its doc as-is (never rewrite to Child Doc Shape or strip its rules), read it as a local root, never edit it to resolve a conflict (report instead), the parent records expectations in its own doc, and changes inside it belong to that project's own repository.
• Initialization, Read Before Editing, Update After Editing, and Closeout all reference nested roots at the point of action, so weaker models can't miss them.

Prompts synced

• The audit prompt marks nested roots and never flags them as shape violations; contract conflicts involving one are marked "decide with the owner."
• The auto-repair prompt gets a loud guard — "NESTED ROOTS ARE OFF-LIMITS" — before any fixing begins, plus catches for leftover "Not yet mapped" placeholders.
• Init, new-session, short forms, and scoped one-liners all updated; skip lists now include .svn.

Full changelog: v1.1.1...v1.2.0

v1.1.1 — DOX health audit & auto-repair prompts

Adds two "How to use" prompts for keeping a DOX tree correct when a weaker model skips a step or the repo is edited by hand. Docs only — no framework changes.

New prompts

• Health audit (read-only). Reports boundary coverage at every depth, Child DOX Index completeness, Feature Map file references, Child Doc Shape conformance, and parent/child contract conflicts — grouped by severity with paths and suggested fixes. Never edits.
• Auto-repair. Runs the same audit, then fixes the mechanical problems (missing boundary/sub-root docs, broken indexes, stale Feature Map entries, shape issues). Edits docs only, never source, and defers genuine judgment calls back to you.

Each ships with an explicit numbered prompt, a collapsed short form for capable/frontier models, and a scoped single-area variant.

Full changelog: v1.1.0...v1.1.1

v1.1.0 — Deep trees, Feature Map, and weaker-model prompts

DOX now scales to deep, multi-submodule projects and carries a feature-to-source map, with docs tuned for weaker models.

Framework

• Recursive boundary trees. Replaced the shallow-first bias with a concrete, mechanical boundary test applied at every depth. Every submodule and subproject gets its own AGENTS.md, recursively — the doc tree now mirrors the project's real structure.
• Sub-roots. A self-contained submodule/subproject's AGENTS.md is written like a root with its own child tree, while still bound by every parent doc.
• Feature Map. Each doc points its features to an entry file and supporting files, so an agent can start work with minimal code traversal. Walk the tree and aggregate the maps to produce an architecture overview — no separate source of truth. Maintenance is wired into Initialization, Update After Editing, and Closeout.

Docs

• Rewrote the "How to use" scenario prompts as explicit, numbered procedures that weaker models follow reliably.
• Added a collapsed short-form prompt per scenario for capable/frontier models.
• Clarified the focused-task prompt with a "use this when…" framing and a concrete example.

License

• Added the modifier copyright alongside the original Agent Zero copyright, kept under MIT.

Full changelog: v1.0.0...v1.1.0

v1.0.0

DOX is a lightweight AGENTS.md framework that gives AI agents precise project context through a hierarchy of local contracts. Copy one file into your project root and the agent builds and maintains the doc tree automatically.

What's in this release

This is the first versioned release of DOX, based on the original framework by Agent Zero, with modifications focused on cross-model reliability.

Changes from upstream

The original DOX framework is principle-based, which works well with capable models but leaves weaker models without a clear procedure to follow. This fork converts the principles into explicit steps:

• Initialization procedure — added a numbered ## Initialization section with a concrete Done when check, so the bootstrap path is spelled out rather than inferred from maintenance rules.
• Boundary heuristics — replaced the abstract "durable boundary" judgment with concrete criteria (own purpose / own audience / own build-run-test story), a bias toward fewer docs, and a shallow-first depth limit.
• Example child doc — added a worked example to ## Child Doc Shape so models have a concrete referent alongside the section list.
• Decoupled init trigger — separated the initialization instruction from the Child DOX Index placeholder, so models don't satisfy the init requirement by editing a single line.
• Scenario-specific prompts — reworked the README How to use section with copy-paste prompts for three situations: new project, existing project with no docs yet, and a new agent session on a project that already has AGENTS.md files.
• Jargon reduction — trimmed opaque terms (DOX rail, binding work contracts) on the procedural path without removing them from the conceptual sections where they carry meaning.

Usage

1. Copy AGENTS.md into your project root.
2. Use the prompt that matches your situation — see How to use in the README.