Claude Code Sync

Updates an existing setup without blowing away user customizations. Idempotent — safe to run weekly, monthly, or on a schedule.

What sync does

1. Re-fingerprint: scan the repo for stack changes since last setup. New framework? New DB? New CI/CD tool?
2. Delta propagation: push plugin rule updates (cc-always.md, cc-patterns.md) into the repo's .claude/rules/.
3. Section-merge CLAUDE.md: update the "Build & Test", "Tech Stack", "Key Paths" sections if stack changed; leave custom sections alone.
4. Fix drift (--fix-drift flag): find config that drifted from plugin defaults — missing hooks, missing MCP servers, outdated skill versions — and repair.
5. Propagate to sub-repos: for monorepos, walk workspace children and apply changes to their .claude/ dirs.
6. Scaffold docs/context/ (if absent): create the 22-template knowledge base that complements .claude/.
7. Auto-install LSPs: detect missing LSP servers from the stack and offer install commands.
8. Persist sync state: write .claude/sync-state.json with timestamp, plugin version, delta summary.

Section-merge protocol for CLAUDE.md

CLAUDE.md sections are identified by ## headings. Sync protocol:

Section	Action
## Build & Test	Replace (regenerated from fingerprint)
## Tech Stack	Replace
## Key Paths	Replace
## Architecture	Preserve (user-curated)
## Conventions	Merge (preserve user additions, update detected items)
## Don't Touch	Merge (preserve user additions)
## Knowledge Library (Obsidian)	Replace if managed-by-plugin marker present
Any other section	Preserve as-is

Managed sections carry a <!-- plugin:cc-setup managed --> marker. Unmarked sections are never touched.

Drift detection (--fix-drift)

Compares current state to plugin baseline:

Check	Fix
Missing .claude/rules/cc-always.md	Copy from plugin
Missing .claude/rules/cc-obsidian-intro.md	Copy from plugin
cc-patterns.md older than plugin's	Offer update (user confirms)
Hook script path doesn't match registered hook	Reconcile or remove dead registration
Settings allowlist has entries for removed tools	Prune
MCP server in .mcp.json has no backing install	Warn
Skills in .claude/skills/ belong to old plugin version	Offer replacement

Never deletes user-added config. All destructive fixes require explicit confirmation.

Sub-repo propagation

For monorepos (turbo/nx/lerna/pnpm-workspaces), sync walks workspace packages and:

1. If package has its own .claude/ → sync it (same protocol as root).
2. If package has no .claude/ → create a minimal one that references the root's CLAUDE.md.
3. Generate per-package CLAUDE.md stubs for LOC > 10k packages.

docs/context/ scaffolding

If docs/context/ does not exist, create from 22 templates:

• docs/context/README.md
• docs/context/architecture/overview.md
• docs/context/architecture/modules.md
• docs/context/conventions/code-style.md
• docs/context/conventions/git-workflow.md
• docs/context/conventions/testing.md
• docs/context/decisions/0001-use-claude-code.md
• docs/context/runbooks/deploy.md
• docs/context/runbooks/rollback.md
• docs/context/glossary.md
• ... (full list via cc_kb_docs_context_templates)

Sync state file

.claude/sync-state.json:

{
  "version": "1.0",
  "last_synced": "2026-04-16T14:00:00Z",
  "plugin_version": "8.0.0",
  "stack_fingerprint": "node-ts-nextjs-postgres-prisma-jest-vercel",
  "sub_repos_synced": 0,
  "drift_fixed": ["added missing cc-obsidian-intro.md", "pruned 2 dead hook registrations"],
  "next_check_due": "2026-05-16"
}

MCP delegation

Need	Tool
Hook pack recommendations after stack change	cc_docs_hook_pack_recommend(signals)
LSP config for newly detected language	cc_kb_lsp_config(language)
Topology for new work patterns	cc_docs_team_topology_recommend(...)

Anti-patterns

• Running sync without reading .claude/sync-state.json → can't tell what changed since last sync.
• --fix-drift without user confirmation → destroys custom config that looks like drift.
• Syncing sub-repos without their owners' awareness → surprises.
• Re-running setup instead of sync → overwrites user customizations.

Reference

• drift-rubric.md — what counts as drift vs. valid customization