Agent documentation improvements

Current maturity

Agent documentation is currently a guided recurring-improvement prototype. The published runbook verifies repository access, reads repository guidance, and produces a synthetic scheduled-status report. It does not yet inspect AGENTS.md or CLAUDE.md drift deeply, edit documentation, create a branch, or open a pull or merge request.

This page describes the intended product direction separately from the behavior available today.

Intended goal

The mature workflow should keep agent-facing guidance current enough that coding agents can find product intent, safe-change boundaries, repository commands, verification, and handoff expectations without relying on private memory. It should prefer concise, authoritative entry points and links over duplicating every project document.

Planned evidence and proposal

A future implementation can compare agent entry files with current manifests, scripts, architecture and product sources, provider workflow, and recent repository conventions. A proposal should name the stale or missing instruction, its authoritative source, affected agent behavior, and the smallest documentation-only change that restores alignment.

It should not manufacture a vendor-specific file when an equivalent portable system already works, and it should not rewrite product decisions or code as part of a docs cleanup.

Human review boundary

Any future write path should remain a documentation-only, reviewable change. Repository owners decide which files are authoritative and whether a tool-specific instruction belongs in the project. Guard must never merge automatically or allow agent guidance to override security, provider, or runbook safety boundaries.

What you can do now

Use the current job as a repository-access and scheduling demonstration only. For real agent-context health, read the AI readiness audit and Cognitive debt audit, then make the necessary documentation change through your normal review process.