Add doc-audit plugin: audit codebase docs for accuracy and freshness

.claude-plugin/marketplace.json

@@ -58,6 +58,12 @@
       "source": "./plugins/agent-ready",
       "description": "Make a codebase agent-ready by scaffolding AGENTS.md, ARCHITECTURE.md, and docs/ structure following progressive disclosure patterns. Creates CLAUDE.md as a symlink for Claude Code compatibility.",
       "version": "1.1.0"
+    },
+    {
+      "name": "doc-audit",
+      "source": "./plugins/doc-audit",
+      "description": "Audit codebase documentation for accuracy, completeness, and freshness against actual code. Auto-fixes small discrepancies, reports structural changes. Companion to agent-ready.",
+      "version": "1.0.0"
     }
   ]
 }

plugins/doc-audit/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "doc-audit",
+  "version": "1.0.0",
+  "description": "Audit codebase documentation for accuracy, completeness, and freshness against actual code. Auto-fixes small discrepancies, reports structural changes. Companion to agent-ready.",
+  "author": {
+    "name": "Damian Galarza",
+    "url": "https://www.damiangalarza.com"
+  },
+  "repository": "https://github.com/dgalarza/claude-code-workflows",
+  "license": "MIT",
+  "keywords": ["ai", "agents", "documentation", "audit", "freshness", "accuracy", "maintenance"]
+}

plugins/doc-audit/README.md

@@ -0,0 +1,105 @@
+# doc-audit
+
+Audit codebase documentation for accuracy, completeness, and freshness against actual code. Auto-fixes small discrepancies, reports structural changes.
+
+This is the **maintenance companion** to [agent-ready](../agent-ready/). While agent-ready *scaffolds* documentation, doc-audit *keeps it accurate* as code evolves.
+
+## Install
+
+```bash
+npx skills add dgalarza/claude-code-workflows --skill "doc-audit"
+
+# Or via Claude marketplace
+/plugin install doc-audit@dgalarza-workflows
+```
+
+## Usage
+
+```
+/doc-audit              # Read-only audit, generates a report
+/doc-audit fix          # Audit + auto-fix safe issues + commit
+/doc-audit full         # Audit + fix + improvement roadmap
+```
+
+## Modes
+
+| Mode | What It Does | Modifies Files? |
+|------|-------------|-----------------|
+| **audit** (default) | Scans docs against code, reports findings by severity | No |
+| **fix** | Runs audit, auto-fixes safe issues (paths, ports, counts, links), commits changes | Yes |
+| **full** | Runs fix, then generates a prioritized improvement roadmap | Yes |
+
+## What It Checks
+
+doc-audit evaluates four dimensions:
+
+- **Completeness** -- Are expected docs present? (AGENTS.md, ARCHITECTURE.md, ADRs, docs/)
+- **Accuracy** -- Do file paths, ports, commands, and counts in docs match actual code?
+- **Freshness** -- Have docs been updated alongside code changes?
+- **Coherence** -- Are there broken links, contradictions, or unnecessary duplication?
+
+Each finding is categorized as Critical (actively misleading), Warning (stale/incomplete), or Info (minor).
+
+## Example Output
+
+```
+# Documentation Audit Report
+
+Date: 2026-03-27
+Mode: audit
+Codebase: my-project
+
+## Summary
+
+| Dimension    | Status | Findings   |
+|--------------|--------|------------|
+| Completeness | pass   | 1 findings |
+| Accuracy     | fail   | 3 findings |
+| Freshness    | warn   | 2 findings |
+| Coherence    | pass   | 0 findings |
+
+## Critical Findings
+
+1. ARCHITECTURE.md references `packages/workers/` which no longer exists (deleted in abc123)
+2. AGENTS.md says gateway runs on port 3001 but docker-compose.yml uses 4001
+3. Build command `pnpm build:all` doesn't exist in package.json scripts
+
+## Warnings
+
+1. AGENTS.md last updated 18 days ago, 12 commits since then
+2. No ADR for the migration from Express to Hono (committed 2 weeks ago)
+```
+
+## What fix Mode Auto-Corrects
+
+- File paths in codemap that moved to a new location
+- Port numbers that changed in docker-compose or .env
+- Counts in tables (agents, tools, packages) that drifted
+- Missing entries in docs/README.md index
+- Broken relative links where the target file was renamed
+- References to deleted files/directories
+
+Issues requiring human judgment (new feature docs, architectural rewrites) are reported but not auto-fixed.
+
+## Works With Any Project
+
+doc-audit auto-detects project type (Node, Ruby, Python, Go, Rust, Java) and adjusts its checks accordingly. It applies monorepo-specific checks when it detects Turborepo, Nx, Lerna, or workspace configs.
+
+No configuration needed.
+
+## Relationship to agent-ready
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| [agent-ready](../agent-ready/) | Scaffold documentation from scratch | New project or first-time setup |
+| **doc-audit** | Maintain documentation accuracy | Ongoing, after code changes |
+
+**Recommended workflow:**
+1. Run `agent-ready` to scaffold initial docs
+2. Run `doc-audit` periodically to catch drift
+3. Run `doc-audit fix` to auto-correct safe issues
+4. Run `doc-audit full` quarterly for a comprehensive review
+
+## Built By
+
+[Damian Galarza](https://www.damiangalarza.com?utm_source=github&utm_medium=readme&utm_campaign=doc-audit). If your team needs help beyond documentation -- architecture, test infrastructure, AI workflow adoption -- check out the [AI Workflow Enablement Program](https://www.damiangalarza.com/services/ai-enablement/?utm_source=github&utm_medium=readme&utm_campaign=doc-audit).

plugins/doc-audit/scripts/recon.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Doc Audit Reconnaissance Script
+# Gathers codebase metadata for documentation comparison
+# Run this script, don't read it into context
+
+set -euo pipefail
+
+echo "=== PROJECT TYPE ==="
+for f in package.json Gemfile requirements.txt pyproject.toml go.mod Cargo.toml build.sbt pom.xml *.csproj; do
+    [ -f "$f" ] && echo "Found: $f"
+done
+
+echo ""
+echo "=== DOCUMENTATION FILES ==="
+find . -maxdepth 3 \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "ARCHITECTURE.md" -o -name "README.md" -o -name "CONTRIBUTING.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | sort
+
+echo ""
+echo "=== DOCS DIRECTORY ==="
+find docs/ doc/ -type f -name "*.md" 2>/dev/null | sort || echo "No docs/ directory"
+
+echo ""
+echo "=== ADRS ==="
+find . -path "*/decisions/*.md" -o -path "*/adr/*.md" -o -path "*/adrs/*.md" 2>/dev/null | grep -v node_modules | grep -v .git | sort || echo "No ADRs found"
+
+echo ""
+echo "=== TOP-LEVEL STRUCTURE ==="
+ls -1d */ 2>/dev/null | head -20
+
+echo ""
+echo "=== SOURCE FILES (top 30) ==="
+find . -maxdepth 4 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/vendor/*" 2>/dev/null | head -30
+
+echo ""
+echo "=== ENTRY POINTS ==="
+ls -1 src/index.* src/main.* app/main.* main.* cmd/ 2>/dev/null || echo "No standard entry points"
+
+echo ""
+echo "=== CONFIG FILES ==="
+ls -1 docker-compose.yml docker-compose.yaml Dockerfile .env.example .env.sample turbo.json nx.json lerna.json 2>/dev/null || echo "No config files"
+
+echo ""
+echo "=== GIT RECENT CHANGES (files changed in last 7 days) ==="
+git log --since="7 days ago" --name-only --pretty=format:"" 2>/dev/null | sort -u | head -20 || echo "No git history"