docs-sync

docs-sync-plugin

A Claude Code plugin that detects documentation drift after commits and helps sync docs with code changes.

Overview

docs-sync watches your git commits and tells you when documentation may be out of date. It works in three stages:

1. Post-commit hook -- After each git commit, the plugin matches changed files against a topic map to identify which documentation files might be affected.
2. Artifact generation -- Writes analysis results to docs-sync/artifacts/<sha>.json and surfaces a notification in your next Claude Code interaction.
3. Documentation update skill -- Run /docs-sync:update-docs to review affected docs and apply targeted updates based on the actual git diff.

Installation

As a Claude Code plugin marketplace

Add this repo as a plugin marketplace in your Claude Code settings:

{
  "marketplace": "https://github.com/hagaybar/docs-sync-plugin"
}

Manual installation

1. Clone this repo
2. Copy plugins/docs-sync/ to your Claude Code plugins directory
3. Configure a global git post-commit hook to run scripts/docs_sync_hook.py

Project Setup

After installing the plugin, initialize docs-sync in any project:

/docs-sync:update-docs --init

This scans your project structure and generates a docs-sync/topic-map.json that maps code file patterns to documentation files. The topic map tells the hook which docs to flag when specific code areas change.

Topic Map

Each project needs a docs-sync/topic-map.json. Example:

{
  "config": {
    "docs_root": "docs",
    "code_extensions": [".py", ".ts", ".tsx", ".js", ".jsx"],
    "skip_prefixes": ["docs:", "chore:", "style:", "test:"]
  },
  "mappings": [
    {
      "doc": "api.md",
      "globs": ["src/api/**", "app/api/**"],
      "notes": "API endpoints and interfaces"
    }
  ]
}

A template is provided in plugins/docs-sync/templates/topic-map-template.json.

Commands

Command	Description
/docs-sync:update-docs	Process pending artifacts and update affected docs
/docs-sync:update-docs --init	Bootstrap docs-sync for a new project
/docs-sync:update-docs --since <sha>	Sync docs for all commits since a SHA
/docs-sync:update-docs --doc <file>	Update a specific doc file

How It Works

Git commit (any source: terminal, IDE, Claude Code)
  -> post-commit hook
    -> docs_sync_hook.py
      -> writes docs-sync/artifacts/<sha>.json
      -> appends to docs-sync/artifacts/.pending-notification

Next Claude Code tool call
  -> PreToolUse hook (hooks.json)
    -> reads .pending-notification
    -> displays content in conversation
    -> truncates the file

Repository Structure

.claude-plugin/
  marketplace.json          # Plugin marketplace definition
plugins/
  docs-sync/
    .claude-plugin/
      plugin.json           # Plugin metadata
    hooks/
      hooks.json            # PreToolUse hook for notifications
    scripts/
      docs_sync_hook.py     # Post-commit analysis script
    skills/
      update-docs/
        SKILL.md            # Skill definition for /update-docs
    templates/
      topic-map-template.json  # Template for project topic maps
    README.md               # Plugin-level documentation
docs/
  TEST-FLOW.md              # End-to-end test guide

License

MIT