HAL9000
885eebeb1f
- document docs-writer responsibilities and automation tracking requirements\n- enforce automation tracking label validation and clean coverage regression tags\n\nISSUES CLOSED: #7616 # Conflicts: # CHANGELOG.md # docs/development/automation-tracking.md # docs/development/docs-writer.md # mkdocs.yml
151 lines
4.8 KiB
Markdown
151 lines
4.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 on first cycle and then every 10 cycles
|
|
if cycle == 1 or 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)
|
|
```
|
|
|
|
**Required labels** (all four must be applied):
|
|
|
|
| Label | Purpose |
|
|
|-------|---------|
|
|
| `Automation Tracking` | Enables system-watchdog health monitoring |
|
|
| `Type/Automation` | Marks as automation-related |
|
|
| `State/In Progress` | Indicates agent is actively running |
|
|
| `Priority/Medium` | Default priority |
|
|
|
|
Tracking issue bodies MUST include the standard automation tracking header with
|
|
the reporting interval declaration, for example:
|
|
|
|
```
|
|
**Reporting Interval**: Every 10 cycles (~3.3 hours) (Next report expected: <timestamp>)
|
|
```
|
|
See [Automation Tracking System](automation-tracking.md#common-header-format) for
|
|
the complete required structure.
|
|
|
|
### 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 four required labels
|
|
|
|
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>/`.
|
|
The instance identifier MUST be generated with a cryptographically strong
|
|
mechanism such as `uuid.uuid4()` or `secrets.token_hex(8)` to avoid collisions
|
|
or predictable directory names. 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.
|
|
|
|
All Git authentication must rely on credential helpers or `GIT_ASKPASS`. The
|
|
agent must not embed personal access tokens in remote URLs, because git will
|
|
echo failing URLs (including credentials) to stderr when operations fail.
|
|
|
|
When interacting with the Forgejo API, the agent MUST handle `HTTP 429` rate
|
|
limit responses by backing off exponentially (starting at 60 seconds, capped at
|
|
the 20 minute cycle delay) before retrying the request. This prevents tight
|
|
retry loops during temporary throttling events.
|
|
|
|
---
|
|
|
|
## 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
|