Dotfiles Sync

Check for dotfiles updates, show what changed, pull with user approval, and re-run install.sh to apply. Environment-aware for CWS (yadm) and local (git + symlinks).

Step 1: Detect environment

Determine the layout the same way /doctor Step 1 does (_detect_layout in core's scripts/_lib.sh; see PROTOCOL.md § Path ownership):

1. CWS (yadm layout) — yadm rev-parse --show-toplevel succeeds: that is the repo root (normally $HOME). If yadm is absent but $HOME/.gitmodules declares dotfiles-core, the root is $HOME (a tree copied into $HOME without its yadm repo; use git -C $HOME).
2. Local (local layout) — otherwise. Resolve the ~/.claude/skills/forge symlink and strip everything from /.claude/dotfiles-core/ onward to get the repo root (a standalone core clone has no such segment; strip from /.claude/skills/ instead):

   target="$(readlink ~/.claude/skills/forge)"
   dotfiles_dir="${target%%/.claude/dotfiles-core/*}"

   Fall back to ~/dotfiles if the symlink doesn't exist.

CWS path: Use yadm commands (or git -C $HOME) for all git operations.

Local path: Use git commands in {dotfiles-dir}.

Step 2: Check for updates

Fetch the latest from origin (with a 10-second timeout to avoid hanging on network issues):

CWS:

cd $HOME && timeout 10 yadm fetch origin

Local:

cd {dotfiles-dir} && timeout 10 git fetch origin

Then count commits behind:

git rev-list HEAD..origin/master --count
# (or yadm rev-list HEAD..origin/master --count)

If fetch fails (network unavailable, timeout):

Cannot reach origin to check for updates.
  -> retry = Try again
  -> x     = Skip (stay on current version)

If already up to date (count = 0):

Dotfiles are current. Nothing to sync.

Stop here.

Step 3: Show what changed

If commits behind > 0, show the changes:

git log HEAD..origin/master --oneline
# (or yadm log HEAD..origin/master --oneline)

Also identify which categories of files changed:

git diff HEAD..origin/master --name-only

Categorize changes for the user:

• Skills: .claude/skills/*/SKILL.md
• Agents: .claude/agents/*.md
• Global instructions: .claude/CLAUDE.md
• Hooks: .cursor/hooks.json, .cursor/hooks/*
• Install script: install.sh
• Aliases: .aliases.local
• Other: anything else

Step 4: Present and gate

Show the summary and ask:

Dotfiles are N commits behind origin/master.

  Commits:
    abc1234 feat: add swarm-retro skill
    def5678 feat: strengthen Jira transition instructions
    ghi9012 fix: branch creation default detection

  Changed categories:
    - Skills: ticket-swarm, swarm-retro (new), ticket-pickup
    - Agents: (none)
    - Global: CLAUDE.md
    - Hooks: hooks.json

  -> pull = Pull changes and re-run install.sh
  -> diff = Show full diff before pulling
  -> x    = Skip (stay on current version)

Wait for user input. Do not pull without explicit approval.

If the user picks diff:

git diff HEAD..origin/master
# (or yadm diff HEAD..origin/master)

Then re-show the gate menu.

Step 5: Pull and install

CWS:

cd $HOME && yadm pull origin master && bash $HOME/install.sh

Local:

cd {dotfiles-dir} && git pull origin master && bash {dotfiles-dir}/install.sh

Capture the output of install.sh and present a summary.

Step 6: Report results

Show what was applied:

Dotfiles synced successfully.

  Pulled: N commits
  New skills: swarm-retro
  Updated skills: ticket-swarm, ticket-pickup
  Updated: CLAUDE.md, hooks.json
  install.sh: completed (no warnings)

Your agent definitions, skills, and hooks are now current.

If install.sh produced warnings (e.g., "exists and is not a symlink"), surface them prominently.

Edge cases

• Merge conflicts or dirty working tree (CWS): In CWS environments, always discard local changes in favor of what's latest on master. Local dotfiles edits in CWS are ephemeral — the source of truth is the repo. Run:

  yadm checkout -- .   # or git -C $HOME checkout -- .
  yadm pull origin master

  Inform the user that local changes were discarded, but do not gate on approval — CWS local changes are never authoritative.
• Merge conflicts or dirty working tree (local): On local machines, warn the user and suggest stashing or committing first. Do not auto-discard — local machines may have intentional uncommitted work.
• yadm not installed (CWS without yadm binary): Fall back to plain git if the yadm repo is at $HOME. Use git -C $HOME commands.
• Branch mismatch: If the local branch is not master, note this and ask which branch to pull from.

Gate rules

• Never auto-pull on local machines. Always show changes and wait for approval.
• CWS environments auto-discard local changes. The remote master is always authoritative in CWS. Discard local modifications and pull without gating on dirty-tree approval (still show what was pulled).
• Never modify dotfiles content. This skill pulls and installs; it does not edit skill files, agents, or CLAUDE.md.
• Network failures are non-blocking. If fetch fails, inform and offer retry. Do not error out.
• install.sh is always re-run after pull. Even if only one file changed, the install script ensures all symlinks and plugins are current.

Step 7: Submodule pointer-bump (dotfiles-core)

After pulling overlay updates, check whether the dotfiles-core submodule has upstream changes available.

Step 7a — Detect submodule

Check if .claude/dotfiles-core/ exists as a submodule in the overlay:

git -C {dotfiles-dir} submodule status .claude/dotfiles-core 2>/dev/null

If the submodule is absent or not initialized, skip this entire Step 7.

Step 7a.1 — Reconcile checked-out core with the recorded pointer

The checked-out submodule can lag the SHA the overlay records (a + prefix in the submodule status output). That drift is not an upstream change and must not be offered as a bump — the overlay already points where it should. Reconcile first so 7b compares the right SHA:

recorded=$(git -C {dotfiles-dir} ls-tree HEAD .claude/dotfiles-core | awk '{print $3}')
checked_out=$(git -C {dotfiles-dir}/.claude/dotfiles-core rev-parse HEAD)
if [ "$recorded" != "$checked_out" ]; then
  git -C {dotfiles-dir} submodule update --init --recursive .claude/dotfiles-core
fi
# (or the yadm equivalents on CWS)

If the two differed, report:

dotfiles-core checkout was at <old-short-sha>; moved to the recorded pointer <new-short-sha>.

Then re-run install.sh at the end of the sync even if no overlay commits were pulled, since the core content on disk just changed.

Step 7b — Fetch core updates

git -C {dotfiles-dir}/.claude/dotfiles-core fetch origin 2>&1

Count commits the submodule is behind:

git -C {dotfiles-dir}/.claude/dotfiles-core rev-list HEAD..origin/main --count

If count = 0, report "dotfiles-core is current." and skip Step 7c.

Step 7c — Show new core commits

git -C {dotfiles-dir}/.claude/dotfiles-core log --oneline HEAD..origin/main

Present:

dotfiles-core has N new commits upstream:

  abc1234 feat: migrate briefing skill into core
  def5678 fix: trap cleanup in lib-overlays.sh

  -> b = Bump submodule pointer to latest + reinstall
  -> s = Skip (leave submodule at current SHA)
  -> h = Help (explain what bumping does)

Wait for user input.

On h:

Bumping the pointer means:
  1. git -C .claude/dotfiles-core checkout origin/main
  2. git add .claude/dotfiles-core
  3. git commit -m "core: bump pointer to <short-sha>"
  4. Re-run install-overlay.sh then dotfiles-core/install.sh
The overlay's submodule then tracks the new core SHA.

Re-show the menu.

Step 7d — Bump pointer

On b:

# Advance submodule to origin/main
git -C {dotfiles-dir}/.claude/dotfiles-core checkout origin/main

# Commit the pointer bump in the overlay
cd {dotfiles-dir}
new_sha=$(git -C .claude/dotfiles-core rev-parse --short HEAD)
git add .claude/dotfiles-core
git commit -m "core: bump pointer to ${new_sha}"

# Re-run overlay install (apply fragments), then core install (symlinks)
bash {dotfiles-dir}/.claude/dotfiles-core/install.sh

Report:

dotfiles-core bumped to <new-sha>.
Reinstalled core symlinks and overlay fragments.

Maintenance

If you discover something during this task that would improve this skill, propose the change and ask me to confirm before saving it.