HAL9000
c76433f756
CI / lint (pull_request) Successful in 39s
CI / push-validation (pull_request) Successful in 29s
CI / build (pull_request) Successful in 35s
CI / helm (pull_request) Successful in 34s
CI / quality (pull_request) Successful in 45s
CI / security (pull_request) Successful in 57s
CI / typecheck (pull_request) Successful in 1m4s
CI / e2e_tests (pull_request) Successful in 3m19s
CI / integration_tests (pull_request) Successful in 4m12s
CI / unit_tests (pull_request) Successful in 5m20s
CI / docker (pull_request) Successful in 11s
CI / coverage (pull_request) Successful in 13m7s
CI / status-check (pull_request) Successful in 9s
CI / benchmark-publish (pull_request) Has been cancelled
CI / benchmark-regression (pull_request) Has been cancelled
132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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](automation-tracking.md)
|
|
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:
|
|
|
|
1. Finds the previous open `[AUTO-DOCS] Documentation Report (Cycle N)` issue
|
|
2. Posts a closure comment
|
|
3. Closes the issue
|
|
4. Creates the new tracking issue with the `Automation Tracking` label
|
|
|
|
Announcement issues (`[AUTO-DOCS] Announce: …`) are **never** deleted.
|
|
|
|
---
|
|
|
|
## Documentation Standards
|
|
|
|
All documentation produced by this agent follows the project's
|
|
[CONTRIBUTING.md](../../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](automation-tracking.md) — full tracking system reference
|
|
- [System Watchdog](system-watchdog.md) — health monitoring that watches this agent
|
|
- [Quality Automation](quality-automation.md) — quality gate context
|