| name | docs-maintenance |
| description | Maintain agent-workflows documentation by updating README entries, workflow docs, shared references, skill docs, examples, links, headings, and cross-file consistency after documentation or workflow changes. Use when Codex is asked to update docs, fix stale references, add examples, improve documentation structure, or validate agent-workflows documentation. |
Docs Maintenance
Quick Start
- Run
scripts/docs_inventory.py <path> to inventory Markdown docs and common documentation signals.
- Run
../workflow-maintainer/scripts/audit_workflow_library.py when maintaining this agent-workflows repository.
- Read references/docs-maintenance-checklist.md before finalizing documentation changes.
- Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
- Keep edits scoped to the documentation goal; do not change workflow semantics accidentally.
Maintenance Workflow
- Identify the doc change type: new doc, renamed file, changed workflow step, new skill, example update, typo, or consistency fix.
- Inventory docs:
python3 scripts/docs_inventory.py /path/to/agent-workflows
- Update all cross-references affected by the change:
- README inventories and setup instructions.
- Workflow routing and library-loading references.
- Skill docs and canonical agent metadata prompts in
agents/interface.yaml.
- Shared conventions if repeated wording appears in multiple workflow files.
- Validate links, anchors, inventories, and helper scripts.
- Report changed docs, validation run, and any skipped checks.
Output Rules
- Prefer precise wording over broad rewrites.
- Preserve existing tone and structure.
- Keep examples executable or clearly marked as templates.
- Do not add duplicate safety language if a shared reference is the canonical source.
