Docs Maintenance Agent

Automatically detect stale documentation, broken links, and outdated examples. Keep your docs fresh with weekly scans and automated PRs.

Documentation naturally drifts. APIs change, examples become outdated, links break. Keeping docs in sync with code is a chore that's perfect for automation.

A docs maintenance agent runs on a schedule, audits your documentation, and opens PRs to fix issues before they confuse users.

What the agent does

On a weekly schedule (or on-demand via assignment), the docs agent:

Finds stale docs — detects references to old APIs, deprecated flags, or removed functions
Checks for broken links — crawls internal and external links; flags 404s
Validates examples — runs code snippets and ensures they compile/execute
Updates the changelog — extracts merged PR titles into a draft changelog
Opens a PR — consolidates findings into one PR with clear sections for review

Set it up

Prerequisites

AACWorkflow workspace with an active agent
Documentation repo (or docs folder in main repo)
Agent runtime with bash, Go, or Node.js installed

Step 1: Create the docs maintenance agent

Go to Settings → Agents and click New Agent
Choose your runtime and provider
Name it docs-audit or doc-keeper
Add this system prompt:

Role: Documentation auditor
Task: Every week or on-demand:
1. Clone the repository
2. Find all .md and .mdx files
3. Check all links (internal with grep, external with curl)
4. Find code snippets and validate syntax
5. Look for TODOs, deprecated markers, or version mismatch
6. Summarize findings in a changelog-style report
7. Create a GitHub branch "docs/maintenance-<date>"
8. Open a PR with all findings grouped by category
9. Link the PR to workspace as "docs-audit"

Output format:
## Stale References
- api/v1/GetIssue() → moved to /v2/GetIssue
- Example in quickstart.md lines 45–50 uses old syntax

## Broken Links
- Internal: docs/guides/auth.mdx → "see [Setup Guide](/setup)" (guide removed)
- External: 3 links to archived.example.com (404)

## Code Examples
- JavaScript example in index.mdx fails to parse (syntax error line 12)

## Changelog
Merged PRs since last scan:
- feat: add workspace invites
- fix: pagination token bug
- docs: update API docs

Step 2: Schedule the agent

In AACWorkflow, go to Settings → Automations and create a scheduled task:

Trigger: Weekly (e.g., Monday 9 AM)
Task: Assign to docs-audit agent
Template: docs-maintenance

Or use a cron job in your own infrastructure:

# Run docs audit every Monday at 9 AM
0 9 * * 1 curl -X POST https://aacworkflow.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "docs-audit", "title": "Weekly docs audit"}'

Step 3: Configure repo access

Add a .aacworkflow/config.yml to your repo:

docs_audit:
  paths:
    - "docs/"
    - "README.md"
    - "CHANGELOG.md"
  exclude:
    - "docs/archived/"
    - "node_modules/"
  checks:
    - link-validation
    - code-snippet-syntax
    - version-references
    - deprecated-markers

Example PR output

Title: docs: maintenance audit for 2025-06-22

Body:

## Stale References (3 items)
- Line 87 in docs/agent-setup.md: "Runtime v2" → should be "Runtime v3"
- docs/api/endpoints.md: Old Swagger URL → update to OpenAPI v3.1
- Quickstart: "Deploy to Heroku" section → remove (service EOL)

## Broken Links (7 items)
- docs/guides/docker.mdx: line 23 → /install/docker-compose (moved to /docker)
- External: https://old-api-docs.example.com → 404

## Code Examples (2 updated)
- Python snippet in examples/webhook.md uses old v1 client → fixed
- Go example missing error handling → added

## Changelog Fragment
### Merged since 2025-06-15
- feat(api): add workspace export endpoint
- fix: typo in API error messages
- docs: expand rate limiting guide

---
Review and merge to publish. Auto-close stale branches after merge.

Tips & best practices

Merge fast. Docs PRs should be low-friction. Review in under an hour, merge, publish. The agent can run weekly without blocking.

Changelog automation — extract merged PR titles into a ## Unreleased section so you have a head start on release notes
Example validation — use Docker containers to validate code examples across languages without installing everything locally
External link timeout — set a 5-second timeout for external link checks to avoid hangs
Exclude patterns — keep archived docs out of the audit (add to .aacworkflow/config.yml)
Approval gates — require at least one human approval before auto-merging docs PRs

Release Notes Agent — convert merged PRs into polished release notes
CI Triage Agent — fix broken CI, not broken docs

On this page