Documentation Bot Plugin

Universal documentation bot for Claude Code - Automatically updates documentation when code changes.

Features

• ✅ Universal: Works for ANY Claude Code session (not just Dr. Zero)
• ✅ Smart filtering: Skips trivial changes (<5 lines)
• ✅ User control: Prompts for confirmation or auto-runs
• ✅ Context-aware: Uses git diff to understand changes
• ✅ Configurable: YAML-based settings
• ✅ Diataxis-aware: Loads the diataxis-framework shared skill so updates land in the correct quadrant (tutorial / how-to / reference / explanation), respect the doc_type ↔ filename-prefix contract, and don't accidentally mix modes.

Diataxis framework integration

When this plugin proposes or writes documentation, it consults the diataxis-framework shared skill in this repo. The skill is the canonical source for:

• The two-axis compass (action vs cognition, acquisition vs application) and the four documentation types it produces.
• Per-quadrant disciplines (rules and anti-patterns specific to each type).
• The doc_type ↔ filename-prefix contract (how-to-, ref-, runbook-, ts-, concept-, adr-YYYYMMDD-).
• The iterative audit workflow Diataxis itself recommends — small, organic improvements rather than big-bang restructures.
• The catalogue of common documentation failure modes (anti-patterns.md) with fix recipes.

Upstream source of truth: https://diataxis.fr. The shared skill is a practitioner's distillation for this org's megadoc family.

Installation

Method 1: From otc-awesome-llm

# Add marketplace
claude plugin marketplace add /path/to/otc-awesome-llm

# Install plugin
claude plugin install documentation-bot@otc-awesome-llm

Method 2: Session-only (testing)

claude --plugin-dir /path/to/otc-awesome-llm/claude-code/plugins/documentation-bot

Configuration

Create ~/.claude/plugins/documentation-bot/config.yaml:

# Documentation Bot Configuration
auto_run: false # true = auto-run, false = prompt user
skip_trivial: true # Skip if <5 lines changed
skip_extensions: # Don't doc these file types
  - .md
  - .txt
  - .json
  - .yaml
min_files_changed: 1 # Minimum files to trigger

Usage

The plugin runs automatically when any Claude Code session ends AND code was modified:

# Example: Manual coding session
$ claude "Add user authentication"
... (Claude writes auth code) ...

✓ Session complete! 8 files changed.

📝 Documentation Bot
──────────────────────────────────────
Files changed: 8
Lines changed: 245 insertions(+), 12 deletions(-)

Code files modified:
  - src/auth/login.py
  - src/auth/session.py
  - src/models/user.py

Update documentation? (y/n): y

▶️  Invoking documentation agent...

✓ Documentation updated successfully!

📄 Documentation files updated:
  - docs/architecture.md
  - docs/api/auth.md
  - README.md
  - CHANGELOG.md

Changes:
  docs/architecture.md   | 34 ++++++++++++++++++++++++++++++++++
  docs/api/auth.md       | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  README.md              | 12 ++++++++++++
  CHANGELOG.md           |  3 +++
  4 files changed, 116 insertions(+)

Auto-Run Mode

To automatically update docs without prompting:

# ~/.claude/plugins/documentation-bot/config.yaml
auto_run: true

Now the bot runs silently:

$ claude "Refactor user service"
... (Claude refactors code) ...

✓ Session complete! 3 files changed.
📝 Documentation bot auto-updating...
✓ Documentation updated: docs/architecture.md, CHANGELOG.md

Integration with Dr. Zero

This plugin works seamlessly with Dr. Zero:

$ /drzero:drzero "Improve test coverage"

Iteration 1: reward=0.92
✓ High-quality iteration
📝 Dr. Zero-specific doc bot (with HRPO metrics)...
✓ docs/testing-strategy.md, CHANGELOG.md updated

Iteration 2: reward=0.55
⏭️  Low-quality iteration - skipping Dr. Zero doc bot
📝 Universal doc bot (basic update)...
✓ README.md updated

Coordination:

• Dr. Zero hook runs first (if high-quality iteration)
• Universal hook skips if Dr. Zero hook already ran
• Universal hook provides fallback for low-quality iterations

Disabling

Temporarily disable:

# ~/.claude/plugins/documentation-bot/config.yaml
enabled: false

Or uninstall:

claude plugin uninstall documentation-bot

Customization

Custom Documentation Agent

The plugin invokes meeseeks-documentation agent by default. You can create your own:

---
name: my-doc-agent
description: Custom documentation agent for my team
---

# My Documentation Agent

You are a documentation specialist for [Company/Team].

## Style Guidelines

- Use our custom Markdown template
- Include Mermaid diagrams for architecture
- Generate OpenAPI specs for APIs
- Follow Diataxis framework (tutorial/how-to/reference/explanation)

## Outputs

- docs/architecture.md (system overview)
- docs/api/ (API reference)
- CHANGELOG.md (semantic versioning)
- README.md (user-facing changes)

Update plugin config:

# ~/.claude/plugins/documentation-bot/config.yaml
agent_name: my-doc-agent # Use custom agent

Troubleshooting

Hook not firing

Check that the Stop event is triggering:

export CLAUDE_PLUGIN_DEBUG=1
claude "Make changes"

# Check logs
cat ~/.claude/logs/plugin-documentation-bot.log

Agent not found

Ensure meeseeks-documentation agent is installed:

# Check available agents
claude --list-agents | grep documentation

# Install Dr. Zero plugin (includes meeseeks agents)
claude plugin install drzero@otc-awesome-llm

No git repository

The hook requires a git repository:

cd /path/to/your/project
git init  # Initialize if needed

Trivial changes ignored

Adjust threshold:

# ~/.claude/plugins/documentation-bot/config.yaml
skip_trivial: false # Document all changes
# OR
min_lines_changed: 3 # Lower threshold

Examples

Example 1: API Development

$ claude "Add GET /users endpoint"

... (Claude adds endpoint) ...

📝 Documentation Bot
Files changed: 2 (src/api/users.py, tests/test_users.py)

Update documentation? (y): y

✓ Updated:
  - docs/api/endpoints.md (added GET /users)
  - docs/api/schemas.md (added User schema)
  - CHANGELOG.md (added feat: GET /users endpoint)

Example 2: Architecture Refactor

$ claude "Extract database logic into repository pattern"

... (Claude refactors) ...

📝 Documentation Bot
Files changed: 12 (major refactor detected)

Update documentation? (y): y

✓ Updated:
  - docs/architecture.md (added Repository Pattern section with diagram)
  - docs/design-decisions.md (added ADR-007: Repository Pattern)
  - CHANGELOG.md (added refactor: extract repository layer)

Example 3: Bug Fix

$ claude "Fix null pointer in user login"

... (Claude fixes bug) ...

📝 Documentation Bot
Files changed: 1 (src/auth/login.py, 3 lines)

ℹ️  Trivial changes (3 lines) - skipping documentation bot

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Claude Code Session Ends (any session)                         │
└─────────────────────────────────────────────────────────────────┘
│
│  Stop Event
│
▼
┌─────────────────────────────────────────────────────────────────┐
│  Documentation Bot Hook (claude-code/plugins/documentation-bot)  │
├─────────────────────────────────────────────────────────────────┤
│  1. Check if code changed (git diff)                             │
│  2. Filter trivial changes                                       │
│  3. Prompt user (or auto-run)                                    │
│  4. Build context from git diff                                  │
│  5. Invoke documentation agent                                   │
│  6. Show results                                                 │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│  meeseeks-documentation Agent                                    │
├─────────────────────────────────────────────────────────────────┤
│  - Analyze code changes                                          │
│  - Update architecture.md                                        │
│  - Update API docs                                               │
│  - Update README.md                                              │
│  - Add CHANGELOG.md entry                                        │
└─────────────────────────────────────────────────────────────────┘

Contributing

Improvements welcome! Key areas:

1. Smart detection: Use AI to determine if docs need updating
2. Incremental updates: Only update affected sections
3. Multi-format: Generate docs in multiple formats
4. Dependency tracking: Update docs for dependent modules

License

Internal use only (Optum)

Credits

• Author: Thomas Hudak ([email protected])
• Part of otc-awesome-llm repository
• Integrates with Dr. Zero autonomous improvement system