HAL9000
c76433f756
3.8 KiB
Documentation Writer Agent
Agent: docs-writer
Tracking Prefix: AUTO-DOCS
Reporting Interval: Every 10 cycles (~3.3 hours)
The docs-writer agent is a continuous documentation monitoring and generation
service. It runs in an isolated clone of the repository, polls for merged code
and milestone completions, and keeps project documentation current without human
intervention.
Responsibilities
| Task | Output |
|---|---|
| README updates | README.md — new features appended to Highlights |
| API documentation | docs/api/ — one file per module |
| Architecture overview | docs/architecture.md — component map, data flow |
| Changelog entries | CHANGELOG.md — Keep-a-Changelog format |
| Module documentation | docs/modules/ — per-module usage guides |
The agent extends existing documentation; it never overwrites content that is already accurate.
Monitoring Loop
last_sha = master HEAD
cycle = 0
LOOP:
cycle += 1
# Create tracking issue every 10 cycles
if cycle % 10 == 0:
automation-tracking-manager: CREATE_TRACKING_ISSUE
agent_prefix: AUTO-DOCS
tracking_type: Documentation Report
# Pull latest code
git fetch && git reset --hard origin/master
current_sha = HEAD
if current_sha == last_sha and cycle > 1:
sleep 20 minutes
continue
last_sha = current_sha
# Check for documentation-worthy changes
query recently merged PRs
check milestone completions
run_docs_update() if changes found
sleep 20 minutes
The agent uses sleep 1200 (20-minute intervals) between cycles and never
voluntarily exits.
Automation Tracking
The docs-writer participates in the Automation Tracking System
via the automation-tracking-manager subagent.
Tracking Issue Format
Title: [AUTO-DOCS] Documentation Report (Cycle N)
Default label (applied automatically by the manager):
| Label | Purpose |
|---|---|
Automation Tracking |
Enables system-watchdog health monitoring |
Additional labels (for example Type/Automation, State/In Progress, or
Priority/Medium) can be added manually when teams need extra filtering, but
they are optional and not applied by the manager today.
Cleanup Protocol
The automation-tracking-manager handles all cleanup:
- Finds the previous open
[AUTO-DOCS] Documentation Report (Cycle N)issue - Posts a closure comment
- Closes the issue
- Creates the new tracking issue with the
Automation Trackinglabel
Announcement issues ([AUTO-DOCS] Announce: …) are never deleted.
Documentation Standards
All documentation produced by this agent follows the project's CONTRIBUTING.md documentation standards:
- Continuous documentation — updated alongside code, not after the fact
- Single documentation surface — one canonical location per doc type
- Traceability — logical references, not line numbers
- MkDocs-compatible — all files are valid MkDocs Markdown
Clone Isolation
The agent always works in an isolated clone at /tmp/docs-writer-<instance-id>/.
It never modifies files in /app or any shared directory. The clone is
deleted on exit (including on error).
Push conflicts are resolved with git pull --rebase origin master && git push.
After five consecutive push failures the clone is deleted and re-cloned fresh.
Since master is a protected branch, all documentation changes are submitted
as pull requests from a feature branch.
Related Documentation
- Automation Tracking System — full tracking system reference
- System Watchdog — health monitoring that watches this agent
- Quality Automation — quality gate context