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 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 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 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 — full tracking system reference
• System Watchdog — health monitoring that watches this agent
• Quality Automation — quality gate context