Auto-Sync

Mode Detection

EXECUTE using Bash tool (args: $ARGUMENTS ):

bash "${CLAUDE_SKILL_DIR}/scripts/detect-mode.sh" $ARGUMENTS

Parse output: MODE|ARG|FLAGS . If exit code non-zero → report error, EXIT.

Mode Trigger Scope

STATUS status

Report INDEX state → EXIT

INIT init <path>

Tag file + add to INDEX → EXIT

GLOBAL global

~/.claude/** (excludes managed dirs)

PROJECT empty .claude/** (excludes managed dirs)

FILE file path Single file

FOLDER folder path All .md in folder

Managed directories (excluded from auto-scan, explicit path required):

• rules/ — sync via /brewdoc:auto-sync .claude/rules

• agents/ — sync via /brewdoc:auto-sync .claude/agents

• skills/ — sync via /brewdoc:auto-sync .claude/skills

INDEX Format

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

Field Description

p

Relative path

t

Type: skill /agent /rule /config /doc

u

Last sync date (YYYY-MM-DD)

pr

Protocol: default /override

Paths: Project .claude/auto-sync/INDEX.jsonl | Global ~/.claude/auto-sync/INDEX.jsonl

Frontmatter Fields

Required (3):

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

Optional override (multiline YAML):

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

Override Field

When auto-sync-override: present in frontmatter → INDEX gets pr: "override" .

Stored in frontmatter only — never in document body.

• Read INDEX.jsonl, verify indexed files exist

• Find all .md files in scope

• Compare indexed vs found → identify non-indexed

• Detect type for non-indexed (discover.sh typed ) — output: TYPE|PATH per line

• Output report: Indexed (path, type, protocol, last sync, stale), Non-Indexed (path, detected type, reason), Summary (counts)

• EXIT

Input: init <path>

• Read <path> — if NOT found → error, EXIT

• If has auto-sync: enabled → "Already tagged", EXIT

• Detect type via discover.sh

• Add frontmatter: auto-sync: enabled , auto-sync-date: {today} , auto-sync-type: {type}

• Check frontmatter auto-sync-override: → set pr: override|default

• Add to INDEX.jsonl

• Output: path, type, protocol; EXIT

Sync Mode (PROJECT/GLOBAL/FILE/FOLDER)

Phase 1: Setup INDEX

EXECUTE using Bash tool:

SCOPE="project" # or "global" INDEX_DIR=".claude/auto-sync" [ "$SCOPE" = "global" ] && INDEX_DIR="$HOME/.claude/auto-sync" mkdir -p "$INDEX_DIR" && INDEX_FILE="$INDEX_DIR/INDEX.jsonl" && touch "$INDEX_FILE" echo "INDEX=$INDEX_FILE"

Phase 2: Discover + Queue (load config: INTERVAL_DAYS , PARALLEL_AGENTS from .claude/tasks/cfg/brewdoc.config.json )

• Find tagged files — EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/discover.sh" "$SCOPE_PATH" typed

Output: TYPE|PATH per line (types: skill , agent , rule , config , doc ). Capped at MAX_FILES (default 50).

For each file not in INDEX → auto-add:

• Read file, use type from discover output

• If no frontmatter → add auto-sync: enabled , auto-sync-date , auto-sync-type

• Check <auto-sync-override> → set pr

• Add to INDEX (index-ops.sh add )

Find stale entries — EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/index-ops.sh" stale "$INDEX_FILE" "$INTERVAL_DAYS"

• Queue: new + stale files

Phase 3: Process + Report

Launch bd-auto-sync-processor agents (max PARALLEL_AGENTS batches, model="sonnet"):

Task(subagent_type="brewdoc:bd-auto-sync-processor", prompt="PATH: {path} | TYPE: {type} | FLAGS: {flags}")

Context: BD_PLUGIN_ROOT is injected into agent prompt by pre-task.mjs hook.

For each result:

• If status = updated or unchanged → update INDEX u to today (index-ops.sh update )

• If status = error → log to Errors table, do NOT update INDEX (file remains stale for retry)

Output report:

Auto-Sync Complete

Updated

Errors

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"

/brewdoc:doc called "Use /brewdoc:auto-sync"