cleveragents-core/docs/development/docs-writer.md

# 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