From 395daecda886e8c3e57e2cb9bac1bc17494d24a0 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Tue, 20 Jan 2026 12:30:42 -0500 Subject: [PATCH] feat: add doc-guardian plugin for documentation lifecycle management Adds automatic documentation drift detection and synchronization: - PostToolUse hook detects when code changes affect docs - Stop hook reminds of pending updates before session ends - /doc-audit command for full project documentation scan - /doc-sync command to batch apply pending updates - doc-analyzer agent for cross-reference analysis - doc-patterns skill for documentation structure knowledge Co-Authored-By: Claude Opus 4.5 --- .../doc-guardian/.claude-plugin/plugin.json | 13 +++++ plugins/doc-guardian/README.md | 49 ++++++++++++++++ plugins/doc-guardian/agents/doc-analyzer.md | 41 +++++++++++++ plugins/doc-guardian/claude-md-integration.md | 22 +++++++ plugins/doc-guardian/commands/doc-audit.md | 50 ++++++++++++++++ plugins/doc-guardian/commands/doc-sync.md | 58 +++++++++++++++++++ plugins/doc-guardian/hooks/hooks.json | 26 +++++++++ .../doc-guardian/skills/doc-patterns/SKILL.md | 39 +++++++++++++ 8 files changed, 298 insertions(+) create mode 100644 plugins/doc-guardian/.claude-plugin/plugin.json create mode 100644 plugins/doc-guardian/README.md create mode 100644 plugins/doc-guardian/agents/doc-analyzer.md create mode 100644 plugins/doc-guardian/claude-md-integration.md create mode 100644 plugins/doc-guardian/commands/doc-audit.md create mode 100644 plugins/doc-guardian/commands/doc-sync.md create mode 100644 plugins/doc-guardian/hooks/hooks.json create mode 100644 plugins/doc-guardian/skills/doc-patterns/SKILL.md diff --git a/plugins/doc-guardian/.claude-plugin/plugin.json b/plugins/doc-guardian/.claude-plugin/plugin.json new file mode 100644 index 0000000..c800c65 --- /dev/null +++ b/plugins/doc-guardian/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "doc-guardian", + "description": "Automatic documentation drift detection and synchronization", + "version": "1.0.0", + "author": { + "name": "Leo Miranda", + "email": "leobmiranda@gmail.com" + }, + "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": ["documentation", "sync", "drift-detection", "automation", "hooks"] +} diff --git a/plugins/doc-guardian/README.md b/plugins/doc-guardian/README.md new file mode 100644 index 0000000..0349700 --- /dev/null +++ b/plugins/doc-guardian/README.md @@ -0,0 +1,49 @@ +# doc-guardian + +Automatic documentation drift detection and synchronization for Claude Code projects. + +## Problem Solved + +Documentation gets outdated. Functions get renamed, configs change, versions bump—but docs lag behind. This creates: +- Multiple review cycles finding stale references +- Unnecessary commits fixing docs piecemeal +- User confusion from outdated instructions + +## Solution + +doc-guardian watches your code changes and automatically: +1. Detects when changes affect documentation +2. Queues updates silently (doesn't interrupt your flow) +3. Syncs all doc changes in a single commit when ready + +## Commands + +| Command | Description | +|---------|-------------| +| `/doc-audit` | Full project scan - reports all drift without changing anything | +| `/doc-sync` | Apply all pending documentation updates in one commit | + +## Hooks + +- **PostToolUse (Write\|Edit)**: Silently checks if code changes affect docs +- **Stop**: Reminds you of pending doc updates before session ends + +## What It Detects + +- **Broken References**: Function/class renamed but docs still use old name +- **Version Drift**: Python 3.9 in docs but 3.11 in pyproject.toml +- **Missing Docs**: Public functions without docstrings +- **Stale Examples**: CLI examples that no longer work + +## Installation + +This plugin is part of the claude-code-marketplace. + +```bash +/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git +/plugin install doc-guardian +``` + +## Integration + +See claude-md-integration.md for CLAUDE.md additions. diff --git a/plugins/doc-guardian/agents/doc-analyzer.md b/plugins/doc-guardian/agents/doc-analyzer.md new file mode 100644 index 0000000..9e84604 --- /dev/null +++ b/plugins/doc-guardian/agents/doc-analyzer.md @@ -0,0 +1,41 @@ +--- +description: Specialized agent for documentation analysis and drift detection +--- + +# Documentation Analyzer Agent + +You are an expert technical writer and documentation analyst. Your role is to detect discrepancies between code and documentation. + +## Capabilities + +1. **Pattern Recognition** + - Identify documentation references to code elements + - Parse docstrings, markdown, and inline comments + - Understand common documentation structures (README, API docs, man pages) + +2. **Cross-Reference Analysis** + - Map documentation claims to actual code + - Detect renamed, moved, or deleted code still referenced in docs + - Identify undocumented public interfaces + +3. **Semantic Understanding** + - Recognize when documentation meaning is correct but wording is outdated + - Distinguish between cosmetic issues and functional inaccuracies + - Prioritize user-facing documentation over internal notes + +## Analysis Approach + +When analyzing drift: +1. Parse the changed file to understand what was modified +2. Search for documentation files that might reference the changed code +3. Extract specific references (function names, class names, config keys) +4. Verify each reference against current code state +5. Categorize findings by severity (broken, stale, missing) + +## Output Style + +Be precise and actionable: +- Quote the exact line in documentation +- Show the exact discrepancy +- Suggest the specific fix +- Never report vague or uncertain findings diff --git a/plugins/doc-guardian/claude-md-integration.md b/plugins/doc-guardian/claude-md-integration.md new file mode 100644 index 0000000..6a481c0 --- /dev/null +++ b/plugins/doc-guardian/claude-md-integration.md @@ -0,0 +1,22 @@ +# Doc Guardian Integration + +Add to your project's CLAUDE.md: + +## Documentation Management + +This project uses doc-guardian for automatic documentation synchronization. + +### Behavior +- Documentation drift is detected automatically when files change +- Pending updates are queued silently during work +- Run `/doc-sync` to apply all pending documentation updates +- Run `/doc-audit` for a full project documentation review + +### Documentation Files Tracked +- README.md (root and subdirectories) +- CLAUDE.md +- API documentation in docs/ +- Docstrings in Python/TypeScript files + +### Commit Convention +Documentation sync commits use: `docs: sync documentation with code changes` diff --git a/plugins/doc-guardian/commands/doc-audit.md b/plugins/doc-guardian/commands/doc-audit.md new file mode 100644 index 0000000..20e4aed --- /dev/null +++ b/plugins/doc-guardian/commands/doc-audit.md @@ -0,0 +1,50 @@ +--- +description: Full documentation audit - scans entire project for doc drift without making changes +--- + +# Documentation Audit + +Perform a comprehensive documentation drift analysis. + +## Process + +1. **Inventory Documentation Files** + - README.md (root and subdirectories) + - CLAUDE.md + - API documentation + - Docstrings in code files + - Configuration references + +2. **Cross-Reference Analysis** + For each documentation file: + - Extract referenced functions, classes, endpoints, configs + - Verify each reference exists in codebase + - Check signatures/types match documentation + - Flag deprecated or renamed items still in docs + +3. **Completeness Check** + - Public functions without docstrings + - Exported modules without README coverage + - Environment variables used but not documented + - CLI commands not in help text + +4. **Output Format** +``` +## Documentation Drift Report + +### Critical (Broken References) +- [ ] README.md:45 references `calculate_total()` - function renamed to `compute_total()` + +### Stale (Outdated Info) +- [ ] CLAUDE.md:23 lists Python 3.9 - project uses 3.11 + +### Missing (Undocumented) +- [ ] api/handlers.py:`create_order()` - no docstring + +### Summary +- Critical: X items +- Stale: X items +- Missing: X items +``` + +5. **Do NOT make changes** - audit only, report findings diff --git a/plugins/doc-guardian/commands/doc-sync.md b/plugins/doc-guardian/commands/doc-sync.md new file mode 100644 index 0000000..02803bf --- /dev/null +++ b/plugins/doc-guardian/commands/doc-sync.md @@ -0,0 +1,58 @@ +--- +description: Synchronize all pending documentation updates in a single commit +--- + +# Documentation Sync + +Apply all pending documentation updates detected by doc-guardian hooks. + +## Process + +1. **Review Pending Queue** + List all documentation drift detected during this session. + +2. **Batch Updates** + For each pending item: + - Show the specific change needed + - Apply the update + - Track in change list + +3. **Update Types** + + **Reference Fixes:** + - Renamed function/class → update all doc references + - Changed signature → update parameter documentation + - Removed item → remove or mark deprecated in docs + + **Content Sync:** + - Version numbers (Python, Node, dependencies) + - Configuration keys/values + - File paths and directory structures + - Command examples and outputs + + **Structural:** + - Add missing sections for new features + - Remove sections for deleted features + - Reorder to match current code organization + +4. **Commit Strategy** + - Stage all doc changes together + - Single commit: `docs: sync documentation with code changes` + - Include summary of what was updated in commit body + +5. **Output** +``` +## Documentation Sync Complete + +### Files Updated +- README.md (3 changes) +- CLAUDE.md (1 change) +- src/api/README.md (2 changes) + +### Changes Applied +- Updated function reference: calculate_total → compute_total +- Updated Python version: 3.9 → 3.11 +- Added docstring to create_order() + +Committed: abc123f +``` diff --git a/plugins/doc-guardian/hooks/hooks.json b/plugins/doc-guardian/hooks/hooks.json new file mode 100644 index 0000000..accaac1 --- /dev/null +++ b/plugins/doc-guardian/hooks/hooks.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "prompt", + "prompt": "A file was just modified. Silently check if this change affects any documentation:\n\n1. If a code file changed: check if README, CLAUDE.md, docstrings, or API docs reference the modified functions/classes/configs\n2. If drift detected: add to internal queue (do NOT interrupt user flow)\n3. At natural breakpoints or when user runs /doc-sync: report pending doc updates\n\nDo NOT announce this check unless drift is found. Work silently." + } + ] + } + ], + "Stop": [ + { + "matcher": ".*", + "hooks": [ + { + "type": "prompt", + "prompt": "Before ending, check if there are pending documentation updates queued by doc-guardian. If yes, ask user: 'I detected documentation drift in X files. Run /doc-sync to update, or skip for now?'" + } + ] + } + ] + } +} diff --git a/plugins/doc-guardian/skills/doc-patterns/SKILL.md b/plugins/doc-guardian/skills/doc-patterns/SKILL.md new file mode 100644 index 0000000..ac585c2 --- /dev/null +++ b/plugins/doc-guardian/skills/doc-patterns/SKILL.md @@ -0,0 +1,39 @@ +--- +description: Knowledge of documentation patterns and structures for drift detection +--- + +# Documentation Patterns Skill + +## Common Documentation Structures + +### README.md Patterns +- Installation section: version requirements, dependencies +- Usage section: function calls, CLI commands +- Configuration section: env vars, config files +- API section: endpoint references + +### CLAUDE.md Patterns +- Project context: tech stack versions +- File structure: directory layout +- Commands: available operations +- Workflows: process descriptions + +### Code Documentation +- Docstrings: function signatures, parameters, returns +- Type hints: should match docstring types +- Comments: inline references to other code + +## Drift Detection Rules + +1. **Version Mismatch**: Any hardcoded version in docs must match package.json, pyproject.toml, requirements.txt +2. **Function References**: Function names in docs must exist in codebase with matching signatures +3. **Path References**: File paths in docs must exist in current directory structure +4. **Config Keys**: Environment variables and config keys in docs must be used in code +5. **Command Examples**: CLI examples in docs should be valid commands + +## Priority Levels + +- **P0 (Critical)**: Broken references that would cause user errors +- **P1 (High)**: Outdated information that misleads users +- **P2 (Medium)**: Missing documentation for public interfaces +- **P3 (Low)**: Style inconsistencies, minor wording issues