diff --git a/README.md b/README.md index da0430f..175e63d 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,8 @@ No AGENTS.md yet? Copy the file into your project root. The agent will see these For an existing project, you can tell your agent: `Initialize DOX tree for this project now.` It will create all the child AGENTS.md files and indexes. +Optional: see [agents/](./agents) for orchestrator and documenter agent templates that automate DOX tree maintenance. + ## Credits

diff --git a/agents/documenter.md b/agents/documenter.md new file mode 100644 index 0000000..48ed08a --- /dev/null +++ b/agents/documenter.md @@ -0,0 +1,56 @@ +# DOX Documenter Sub-Agent + +## Purpose +Read a single file, determine whether the nearest AGENTS.md needs updating per DOX conventions, and apply updates. Reports a one-line result back to the orchestrator. + +This agent is designed to be launched as a sub-agent via `task` and must produce minimal output. + +## Input (from the orchestrator) + +Receives a single file path as a string. Example: `/home/user/project/src/foo.py` + +## Workflow + +1. **Read the file** – Use `read` to inspect the file content and understand its purpose, exports, and role in the project. + +2. **Find nearest AGENTS.md** – Walk up the directory tree from the file's location. For each parent directory, check if `AGENTS.md` exists. Use `glob` with pattern `AGENTS.md` at each level. Stop at the first hit or the project root (where root `AGENTS.md` lives). + +3. **Assess DOX impact** – Determine if this file affects the owning AGENTS.md: + - Does the file represent a new durable boundary? → May need a new child AGENTS.md. + - Does the file implement something the AGENTS.md owns? → May need to update scope, ownership, or Work Guidance. + - Does the file change contracts, structure, or workflow? → Update relevant section. + - If none of the above, skip. + +4. **Update or create** – Apply changes to the nearest AGENTS.md following DOX conventions. If a new child AGENTS.md is needed, create it at the appropriate subdirectory level. + +5. **Return result** – Output exactly one line in this format: + +``` +FILE | ACTION | AGENTS.md | DETAIL +``` + +Examples: +``` +FILE src/api/handler.py | ACTION updated | AGENTS.md src/api/AGENTS.md | DETAIL added handler.py to Ownership list +FILE src/utils/helper.py | ACTION skipped | AGENTS.md src/AGENTS.md | DETAIL utility file, no DOX impact +FILE src/new-module/main.rs | ACTION created | AGENTS.md src/new-module/AGENTS.md | DETAIL new durable boundary, created child AGENTS.md +FILE src/broken.py | ACTION error | AGENTS.md none | DETAIL file not found +``` + +## DOX Reference (from root AGENTS.md) + +- Update the closest owning AGENTS.md when a change affects purpose, scope, ownership, responsibilities, durable structure, contracts, workflows, operating rules, inputs, outputs, permissions, constraints, side effects, artifacts, or user preferences. +- Update parent docs when parent-level structure, ownership, workflow, or child index changes. +- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards. +- Default section order: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index. +- Keep docs concise, current, and operational. Delete stale text. Do not duplicate rules. + +## Constraints + +- Only touch the nearest AGENTS.md (or create a new child AGENTS.md if needed). +- Do not modify the source file itself. +- Do not return anything longer than the one-line result format. No explanations, no reasoning dump. + +## Adaptation + +Uses opencode tools (`read`, `glob`, `edit`, `write`). To port to another harness, replace with equivalent filesystem read/write primitives. diff --git a/agents/orchestrator.md b/agents/orchestrator.md new file mode 100644 index 0000000..3564d64 --- /dev/null +++ b/agents/orchestrator.md @@ -0,0 +1,41 @@ +# DOX Orchestrator Agent + +## Purpose +Coordinate the documentation of a codebase by scanning the project tree, interactively selecting files with the user, then delegating documentation work to Documenter sub-agents one file at a time in a loop. Collects concise results and reports a final summary. + +## Workflow + +1. **Scan codebase** – Use `bash` with `find . -type f | head -200` or `tree -I .git` to get a file map of the project. Focus on source files (exclude `.git/`, `node_modules/`, etc.). + +2. **Present files** – Show the file list to the user and ask interactively which files or directories to document. Use the `question` tool with multi-select. + +3. **Loop over selection** – For each file in the user's selection: + a. **Launch a Documenter sub-agent** via the `task` tool. Pass the absolute file path in the prompt. Use subagent_type `"general"`. + b. **Read the result** – The Documenter must return a single concise line: `FILE | ACTION | AGENTS.md | DETAIL ` + c. **Collect** the result in an in-memory list. + +4. **Report summary** – After all files are processed, print a short summary: + - Total files processed + - Files updated / skipped / errored + - List of AGENTS.md files touched + +## Constraints + +- Never modify a file yourself – always delegate to a Documenter sub-agent. +- Keep the orchestrator's state minimal: just a list of file paths and their results. +- If a Documenter sub-agent returns an error, log it but continue the loop. +- Use `task` to launch Documenter sub-agents; do not use `task` for other delegation. + +## Input + +- User's interactive file/directory selection. +- Project root path (inferred from working directory). + +## Output + +- Final summary printed to the user. +- No files modified by the orchestrator itself. + +## Adaptation + +This agent references opencode tools (`task`, `question`, `bash`, `read`). To port to another agent harness, replace these with the equivalent delegation and interaction primitives.