Sync Rules

Sync rules

Solves the "same rules file copy-pasted into N repos, now I have to edit N places" problem. Canonical rule files live in this skill's rules/ folder (versioned in the claude-plugins repo — the source of truth). This skill never syncs blindly: it decides which canonical rules are relevant to the current project, then asks the user to approve the selection with a checkbox-style question before writing anything.

Paths in this skill are relative to the skill's own directory (given to you when the skill is invoked), not the target project. The bundled script finds the target project root itself by walking up from the current working directory to the nearest .git.

Steps

1. Get the status of every canonical rule against this repo, without writing anything:

   node "<skill-dir>/scripts/sync-rules.mjs" --list
   

   Running the script with no --only/--all flag is always report-only — it never writes. Each row is one candidate rule with a status: add (new), update (canonical changed, safe to pull), up to date, conflict (locally edited since last sync), or stale (removed from the source upstream).

2. Drop up to date rows — nothing to decide there. For every remaining row (add, update, conflict, stale), read the canonical file at <skill-dir>/rules/<rel> (skip this for stale, since the source file is gone) to understand what it governs and which paths: frontmatter it scopes to.

3. Judge relevance against this repo — keep this shallow. This is a cheap sanity check, not an audit: read at most two files, package.json (dependencies — Drizzle/Supabase/Next.js/etc.) and CLAUDE.md if present (stated stack/conventions), plus one Glob check each for app/ and features/ directories if their presence isn't already obvious from those two files. Do not grep the codebase, open source files, or read multiple config files looking for evidence — if package.json and CLAUDE.md don't settle it, mark the rule's relevance as unclear rather than digging further. Compare what you found against each rule's paths: scope and content, and form a one-line recommendation per rule: applies directly, applies partially, likely not relevant to this stack, or unclear.

4. Ask the user to approve the selection with AskUserQuestion, multiSelect: true. One option per candidate rule from step 2, its description stating: what it covers, its status (new / update / conflict), and your relevance judgment from step 3. AskUserQuestion caps options at 4 per question and 4 questions per call — if more than ~16 candidates need review, run multiple rounds sequentially rather than truncating the list. For conflict rows, make clear in the description that approving means overwriting a local edit.

5. Sync only what was approved. Collect the selected relative filenames and run:

   node "<skill-dir>/scripts/sync-rules.mjs" --only=<rel1>,<rel2>,...
   

   Add --force only for approved rows that were in conflict status — without it the script still refuses to overwrite local edits even if the filename is in --only.

6. Report what was written (and, for stale rows the user didn't ask to delete, remind them the file still exists locally with no upstream source). If .claude/rules/ didn't exist before this run, mention it's new and should be committed to version control.

Updating the canonical rules themselves

To change what gets distributed to every repo, edit the .md files under this skill's rules/ directory (see its own README.md) and commit to the claude-plugins repo. Nothing pushes automatically — each consuming repo re-evaluates and re-approves the change next time it runs /sync-rules.

Examples

Example 1 Input: /sync-rules in a Next.js + Drizzle/Supabase repo that has never synced before. Action: --list shows all four canonical rules as add. Read each, then check package.json (finds next, drizzle-orm, @supabase/*) and CLAUDE.md (confirms the stack) — no further digging needed. Note that db-patterns.md, nextjs-page-layout-patterns.md, and feature-architecture.md match the stack directly and code-style.md is stack-agnostic and generally applicable. Present all four as a checklist recommending all four; sync whatever the user leaves checked.

Example 2 Input: /sync-rules in a repo with no next dependency in package.json and no CLAUDE.md. Action: still list nextjs-page-layout-patterns.md as a candidate (don't silently exclude it). A quick Glob for app/**/*.tsx comes back empty, so flag in its description that this repo doesn't appear to use the Next.js App Router, so the recommendation is to leave it unchecked — don't go further (e.g. reading route files) just to be sure.

Example 3 Input: /sync-rules where code-style.md shows conflict because someone hand-edited it locally. Action: include it in the checklist with a note that it has local edits and selecting it will discard them; if approved, sync that file with --force.