Documentation Agent

The Documentation Agent (AG-DOCUMENTATION) is your specialist for technical writing, API documentation, user guides, and keeping documentation current with your codebase. This agent ensures that all documentation stays up-to-date, clear, and helpful for both new and experienced developers.

Capabilities

• API Documentation: OpenAPI/Swagger specifications, endpoint descriptions, request/response examples, and error codes
• User Guides & Tutorials: Getting started guides, step-by-step instructions, best practices, and troubleshooting
• Developer Guides: Project setup, development workflow, architecture overview, and extension patterns
• README Management: Root, module-specific, and feature-specific README files
• Changelog Maintenance: Release notes and user-facing change tracking
• Documentation Audits: Identify outdated content, broken links, and missing examples
• Auto-Generated Docs: Support for OpenAPI Generator, TypeDoc/JSDoc, and architecture diagrams

When to Use

Use this agent when you need to:

• Write or update API documentation with working examples
• Create user guides for new features (step-by-step instructions)
• Update README files to reflect current project state
• Write developer onboarding guides
• Create troubleshooting guides and FAQs for common issues
• Document architecture decisions and system design
• Maintain changelog with release notes
• Fix broken documentation links
• Audit documentation for staleness and accuracy
• Keep documentation in sync with code changes

How It Works

1. Context Loading: Agent reads expertise file (documentation patterns, file locations, conventions) and analyzes project structure (CLAUDE.md, status.json, recent releases)

2. Documentation Audit: Agent identifies documentation gaps, outdated sections, broken links, and missing examples by scanning docs/ structure and comparing against code

3. Planning: Agent proposes documentation improvements, suggests new guides, identifies stale content, and prioritizes work

4. Writing: Agent creates/updates documentation with clarity prioritized over brevity, includes working examples (copy-paste ready), and maintains consistent formatting

5. Quality Review: Agent verifies documentation is up-to-date with code, all steps explained, examples work, and navigation between docs is clear

6. Coordination: Agent updates status.json, appends completion messages, and posts updates to agent bus

Example

Copy# Via /babysit
/agileflow:babysit
> "We just released v2.17.0. Need to update the changelog and API docs for the new endpoints"

The Documentation Agent would:

1. Check the new API endpoints added in v2.17.0
2. Update API documentation with request/response examples
3. Add release notes to changelog highlighting user-facing changes
4. Update README if needed
5. Verify all links work

Key Behaviors

• Documentation Priority: Clarity over brevity - explains everything for new users
• Always Include Examples: Documentation without examples is useless; all examples are copy-paste ready
• Keep Current: Documentation must stay current with code; stale docs are worse than no docs
• Include Troubleshooting: Address common issues users will encounter
• Document Breaking Changes: Critical for users upgrading versions
• Link Checking: Proactively fixes broken documentation links
• Consistency: Maintains consistent formatting, tone, and structure across all docs
• Context Preservation: Uses compact_context (priority: high) to maintain focus during long conversations, preserving documentation coverage tracking and link validation through context compaction

Compact Context Configuration

The Documentation agent uses high priority compact_context to ensure documentation quality stays in focus:

Copycompact_context:
  priority: high
  preserve_rules:
    - "LOAD EXPERTISE FIRST: Always read packages/cli/src/core/experts/documentation/expertise.yaml"
    - "NEVER LET DOCS LAG BEHIND CODE: Stale docs are worse than no docs (misinformation)"
    - "ALWAYS INCLUDE EXAMPLES: Documentation without examples is useless"
    - "KEEP LINKS CURRENT: Run link checker, fix broken references"
    - "DOCUMENT BREAKING CHANGES: Critical for users upgrading versions"
    - "CLARITY OVER BREVITY: Explain everything for new users"
  state_fields:
    - current_story
    - documentation_coverage
    - broken_links_count
    - outdated_sections

This ensures documentation-critical rules (keeping docs current, including examples, documentation completeness) and current state (what docs are outdated, which links are broken) persist through context compaction.

Tools Available

This agent has access to:

• Read: Browse documentation files and understand structure
• Write: Create new documentation files
• Edit: Update existing documentation
• Bash: Run link checkers, validate documentation structure
• Glob: Find documentation files by pattern
• Grep: Search documentation content and identify broken links

Documentation Types

API Documentation

• OpenAPI/Swagger specifications
• Endpoint descriptions with paths, methods, parameters
• Request/response examples
• Error codes and their meanings
• Authentication and authorization details
• Rate limiting information
• Code examples in multiple languages

User Guides

• Getting started guides
• Common tasks with step-by-step instructions
• Best practices and tips & tricks
• Troubleshooting sections
• FAQ pages
• Video tutorial links

Developer Guides

• Project setup and installation
• Development workflow
• Architecture overview
• Code organization and structure
• How to extend/customize
• Testing and debugging approaches
• Common patterns and anti-patterns

README Files

• Project overview and purpose
• Installation/setup instructions
• Quick start with working examples
• Feature list
• Documentation links
• Contributing guidelines
• License and attribution

Quality Checklist

Before documenting:

• Documentation is up-to-date with code
• All new features documented with examples
• API documentation includes working examples
• Links are not broken
• Formatting is consistent across files
• Examples are working and copy-paste ready
• Troubleshooting section addresses common issues
• Navigation between docs is clear
• README is accurate and helpful
• No deprecated information remains

Related Agents

• research - Gathers technical information for documentation
• adr-writer - Documents architectural decisions referenced in guides
• epic-planner - Creates epics that documentation ensures are properly documented
• readme-updater - Audits and updates README files across project folders

Common Patterns

Documentation-as-Code

• All documentation versioned with code in git
• Source of truth is the living codebase, not separate docs
• Changes to code trigger documentation updates

Numbered Directory Structure

• Documentation organized in docs/ with numbered directories (00-meta through 10-research)
• Consistent structure across all projects

Documentation Maintenance

• Schedule quarterly audits to find stale information
• After every release, update documentation
• After every API change, update API docs
• Fix broken links proactively

Coordination Messages

The Documentation Agent communicates with other agents via bus messages:

Copy{"ts":"2025-10-21T10:00:00Z","from":"AG-DOCUMENTATION","type":"status","text":"API docs updated for v2.17.0"}
{"ts":"2025-10-21T10:05:00Z","from":"AG-DOCUMENTATION","type":"question","text":"UI component API changed - need updated documentation for props"}

When other agents complete work:

• AG-API completes endpoint → Documentation Agent updates API docs
• AG-UI releases component → Documentation Agent documents component props and usage
• Release happens → Documentation Agent updates changelog and release notes
• Architecture decision made → Documentation Agent updates ADR documentation