chore(development-productivity): rename /update-claude-md command to /sync-claude-md

[dylanschmittle-uniswap]

What

Renames the development-productivity command /update-claude-md → /sync-claude-md, updating all 22 references including two live hook scripts and the plugin manifest.

Why

Three different things were named some variant of "update claude md", and one name was shared outright:

Entry point	Job
/update-claude-md command (this plugin)	Staged git changes → update affected CLAUDE.md files. Explicit, pre-commit
update-claude-docs skill (this plugin)	Same job, but auto-triggers after significant code changes
update-claude-md skill (Uniswap backend repo)	Authoring individual rules in a CLAUDE.md — "add a rule", "Claude keeps doing X wrong". Not a git-diff sync

The first and third shared a name while doing unrelated work. Plugin namespacing (development-productivity:update-claude-md) mitigated it at the call site, but not for model-side selection — with three same-named entries, picking the right one came down to guessing. sync-claude-md also describes what the command actually does, which the old name did not.

Surfaced by a commands-vs-skills audit of the toolkit (see #553 for the other finding).

The part worth reviewing carefully

The rename is mechanical but it reaches two live hook scripts, either of which would have broken silently:

• scripts/lefthook/update-claude-docs.sh — shells out to claude -p "/update-claude-md" from a git hook
• packages/plugins/development-productivity/hooks/claude-md-maintenance.sh — Stop hook whose reminder text tells Claude which command to run

And the plugin manifest lists commands explicitly:

"commands": ["./commands/claude-init-plus.md", "./commands/update-claude-md.md"]

Missing that would have unregistered the command entirely — a rename that "worked" everywhere except actually loading. It's updated and plugin.json re-validates as JSON.

Changes

• git mv commands/update-claude-md.md → commands/sync-claude-md.md, with name: frontmatter updated
• All 21 files carrying /update-claude-md updated to /sync-claude-md — mostly the boilerplate CLAUDE.md footer ("Claude Code MUST run /sync-claude-md before presenting results"), plus lefthook.yml, docs/guides/claude-integration.md, the plugin README.md and CLAUDE.md, and commands/claude-init-plus.md's cross-reference
• Added a "Not to be confused with" table to the command, so the three CLAUDE.md-maintenance entry points stay distinguishable even after the rename
• Fixed a pre-existing duplicated line in the command body (constraint, or workflow decision. appeared twice)

Deliberately not renamed: two references in skill-management/skills/skill-doctor/SKILL.md that say "a standing rule → an update-claude-md skill". Those point at the backend skill (entry 3 above), not this command, and are now more accurate rather than less.

Blast radius

22 files, all markdown / shell / JSON. No TypeScript, no tests, no CI workflow logic. Behaviour of the command itself is unchanged — same frontmatter contract, same $ARGUMENTS, same workflow.

Breaking for callers, which is the whole point: anyone with /update-claude-md in muscle memory, a personal alias, or an external script gets "command not found" and needs to switch to /sync-claude-md. Both in-repo callers are updated here. Worth a heads-up in whatever channel announces toolkit changes.

Validation

• grep -rn '/update-claude-md' → 0 remaining across *.md, *.sh, *.yml
• grep -rn 'update-claude-md' in the plugin → 0 remaining (only the intentional skill-doctor references elsewhere)
• plugin.json parses and lists ./commands/sync-claude-md.md
• Both hook scripts verified to reference the new name
• git mv used, so history follows the file
• Not run end-to-end — worth invoking /sync-claude-md once and letting the lefthook path fire before merge

Left as a draft for review; happy to drop the rename and keep only the disambiguation table if the breaking change isn't wanted.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ai-toolkit-slack-oauth-backend	Ready	Preview, Comment	Jul 28, 2026 8:36pm

[github-actions]

📚 Documentation Check ❌

Verdict: Failed

Files in packages/plugins/development-productivity/ were modified (command renamed from update-claude-md.md to sync-claude-md.md, plugin.json commands array updated) but the plugin version in .claude-plugin/plugin.json was not bumped from 2.4.1. Per repo CLAUDE.md, renaming a command is an explicit Major-bump trigger, and fail_on_missing_version is true.

---

Summary

This PR renames the /update-claude-md slash command to /sync-claude-md throughout the development-productivity plugin and updates references to the old name in prose across many other CLAUDE.md files repo-wide (those are just documentation mentions, not plugin components, so they don't independently require version bumps).

Blocking issue: All actual plugin-component changes (command file rename, plugin.json commands array, plugin CLAUDE.md, plugin README.md, hook script message) are confined to packages/plugins/development-productivity/. The repo's own root CLAUDE.md mandates a version bump in .claude-plugin/plugin.json for any change under packages/plugins/<name>/, and explicitly classifies "renamed skills/agents/commands" as a Major version bump. The current plugin.json still shows "version": "2.4.1" — unchanged — so this is a missing mandatory version bump.

Non-blocking: The version table in root CLAUDE.md (| development-productivity | 2.4.1 |) will need updating once the bump lands. The README.md command/hook tables also lost their column padding alignment after the rename (purely cosmetic, doesn't break markdown rendering).

No issues found with the CLAUDE.md cross-references elsewhere in the repo — they consistently and correctly reflect the new /sync-claude-md name.

Missing Updates

Type	File	Severity	Reason
🏷️ version_bump	packages/plugins/development-productivity/.claude-plugin/plugin.json	❌ error	Command file renamed (commands/update-claude-md.md -> commands/sync-claude-md.md) and plugin.json's commands array updated, but version field still reads 2.4.1. Repo policy requires a Major bump for renamed commands.
📝 changelog	packages/plugins/development-productivity/	ℹ️ info	A breaking rename of a user-facing slash command warrants a changelog/release note so users relying on /update-claude-md know to switch to /sync-claude-md.

Suggestions (3)

💡 Inline suggestions have been posted as review comments. Click "Commit suggestion" to apply each fix directly.

• ❌ packages/plugins/development-productivity/.claude-plugin/plugin.json: Renaming a user-facing command (update-claude-md -> sync-claude-md) is a breaking change per this repo's own semver policy ("renamed skills/agents/commands" = Major bump). Current version 2.4.1 was not bumped despite the mandatory rule requiring a version bump for any change under packages/plugins/development-productivity/.
• ⚠️ CLAUDE.md: Root CLAUDE.md contains a table of current plugin versions with the note "Keep this table updated when versions change." This should be updated in the same commit as the plugin.json version bump.
• ℹ️ packages/plugins/development-productivity/README.md: The command table column alignment is broken after renaming /update-claude-md to the shorter /sync-claude-md (extra trailing spaces no longer line up with the header separator). Cosmetic only, markdown still renders correctly.

---

_{🤖 Generated by Claude Documentation Validator | Mode: suggest}

[dylanschmittle-uniswap]

Closing per author request — the 22-file breaking rename isn't wanted. The commands-vs-skills audit finding that motivated it is captured in #553; the naming ambiguity between the three CLAUDE.md-maintenance entry points remains open and unaddressed.