auto-sync — fix docs drift

Caution

Skill files, agent definitions, and rule docs go stale as code changes. Manual checks don’t scale — one forgotten SKILL.md means Claude operates on outdated instructions. The longer the drift, the bigger the fix.

Tip

One command syncs everything in scope. Auto-Sync discovers markdown files, checks what’s stale via an INDEX, and delegates parallel updates to bd-auto-sync-processor agents. Run status first to see what’s out of date before touching anything.

Quick reference

Field	Value
Command	`/brewdoc:auto-sync [mode] [path]`
Arguments	`status` · `init <path>` · `global` · `<file>` · `<folder>` · (empty = project)
Model	opus
Tools	Read, Write, Edit, Glob, Grep, Bash, Task, WebFetch, Skill

When to use

After upgrading plugins — skill and agent READMEs may have changed upstream; run project sync to pull them in
Before a release — verify all .claude/** docs reflect the current codebase state
New file onboarding — init <path> tags a file for tracking without running a full sync
Global audit — global mode sweeps ~/.claude/** to catch personal rule and config drift
Single file refresh — pass a path directly when only one doc needs updating

Modes

Mode	Command	Scope
STATUS	`/brewdoc:auto-sync status`	Report INDEX state — no writes
INIT	`/brewdoc:auto-sync init <path>`	Tag one file, add to INDEX
PROJECT	`/brewdoc:auto-sync`	All `.md` under `.claude/**`
GLOBAL	`/brewdoc:auto-sync global`	All `.md` under `~/.claude/**`
FILE	`/brewdoc:auto-sync path/to/file.md`	Single file
FOLDER	`/brewdoc:auto-sync path/to/folder`	All `.md` in folder

Managed directories (rules/, agents/, skills/) are excluded from automatic scanning — pass the path explicitly to sync them.

Examples

# See what's tracked and what's stale — no writes
/brewdoc:auto-sync status

# Tag a new file for tracking (auto-detects type, adds frontmatter)
/brewdoc:auto-sync init .claude/agents/my-agent.md

# Sync everything in the current project
/brewdoc:auto-sync

# Sync managed directories explicitly
/brewdoc:auto-sync .claude/rules
/brewdoc:auto-sync .claude/agents

# Sync all personal docs across &#126;/.claude/**
/brewdoc:auto-sync global

# Refresh a single file
/brewdoc:auto-sync .claude/agents/reviewer.md

Flow

Detect mode
The detect-mode.sh script parses $ARGUMENTS and outputs MODE|ARG|FLAGS. STATUS and INIT exit after their own phase; sync modes continue.
Setup INDEX
Resolves the INDEX file path — project-relative .claude/auto-sync/INDEX.jsonl for PROJECT/FILE/FOLDER, or $BD_PLUGIN_DATA/auto-sync/INDEX.jsonl for GLOBAL (the ~/.claude/* path is blocked by Claude Code’s protected-path policy).
Discover + queue
Runs discover.sh typed to find markdown files and classify each as skill, agent, rule, config, or doc. Files absent from INDEX are auto-added with frontmatter. Stale entries (past INTERVAL_DAYS) join the queue. Cap: 50 files per run.
Parallel processing
Spawns bd-auto-sync-processor agents (sonnet model) up to PARALLEL_AGENTS concurrently. Each agent receives PATH | TYPE | FLAGS and BD_PLUGIN_ROOT via the pre-task hook. Agents analyze sources, compare with current doc content, and apply changes.
Update INDEX + report
Successful results (updated or unchanged) refresh the INDEX date via index-ops.sh update. Errors leave the entry stale for the next run. A summary table lists discovered, queued, updated, unchanged, and error counts.

Internals

INDEX format — JSONL, one record per tracked file:

{"p":"skills/auth/SKILL.md","t":"skill","u":"2026-02-05","pr":"default"}

Field	Description
`p`	Relative path from scope root
`t`	Type: `skill` / `agent` / `rule` / `config` / `doc`
`u`	Last sync date (YYYY-MM-DD)
`pr`	Protocol: `default` or `override`

Frontmatter tags — required to include a file in sync:

auto-sync: enabled
auto-sync-date: 2026-02-05
auto-sync-type: skill

Override protocol — optional block for fine-grained control:

auto-sync-override: |
  sources: src/**/*.ts, .claude/agents/*.md
  focus: API endpoints, error handling
  preserve: ## User Notes, ## Custom Config

When auto-sync-override is present, INDEX records pr: "override". The block lives in frontmatter only — never in the document body.

Error handling:

Error	Action
INDEX corrupt	Rebuild from discovery
File not found	Skip, add to errors
Agent timeout	Retry once
No tagged files	Report “0 found”

📄

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.

auto-sync — fix docs drift

Caution

Tip

Quick reference

When to use

Modes

Examples

Flow

My Claude

Memory

GitHub source

Brewdoc overview

Updating plugins