shared-config-sync

<!-- Placeholder convention (see AGENTS.md#placeholder-convention-used-in-skill-files): <project-config> → adopting project's `.apache-magpie/` directory --> # setup-shared-config-sync This skill pushes local edits in `~/.claude-config/` to the sync repo's remote, so other machines can pull them. It is the counterpart to the periodic `git pull --rebase --autostash` that the framework's example `sync.sh` runs on a timer: that pulls *upstream* into the local clone; this skill pushes *local* changes upstream. ## Adopter overrides <!-- BEGIN MAGPIE BLOCK: adopter-overrides — generated from tools/dev/blocks/adopter-overrides.md --> Before running its default behaviour, this skill consults `setup-shared-config-sync.md` in the personal layer (`.apache-magpie-local/` when the project adopted Magpie, falling back to the main checkout's in a linked worktree, or `<git-common-dir>/apache-magpie/` when Magpie is only installed; applied first, wins on conflict) and [`.apache-magpie-overrides/setup-shared-config-sync.md`](../../../../docs/setup/agentic-overrides.md) (committed, project-wide) in the adopter repo, if present, and applies any agent-readable overrides it finds. See [`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md) for the contract. **Hard rule**: agents NEVER modify the snapshot under `<adopter-repo>/.apache-magpie/`. Local modifications go in the override file; framework changes go via PR to `apache/magpie`. <!-- END MAGPIE BLOCK: adopter-overrides --> --- ## Hardcoded path The sync repo lives at `~/.claude-config/`, the convention documented in [`docs/setup/secure-agent-setup.md` → Syncing user-scope config across machines](../../../../docs/setup/secure-agent-setup.md#syncing-user-scope-config-across-machines). The path is intentionally not parameterised: the doc names one canonical location, so adopters with a sync repo elsewhere fork this skill. ## The default remote When the skill has to **bootstrap** a missing `~/.claude-config/` (see [Bootstrapping a missing `~/.claude-config/`](#bootstrapping-a-missing-claude-config)), it resolves the remote to clone or create in this order: 1. **An explicit URL the user passed this invocation** (e.g. *"bootstrap from `git@gitlab.com:me/claude-config.git`"*) wins over everything. 2. **The default GitHub convention**: `git@github.com:<handle>/claude-config.git`, the SSH form the doc's [Setting up a fresh host](../../../../docs/setup/secure-agent-setup.md#setting-up-a-fresh-host) snippet uses. `<handle>` comes from `gh api user --jq .login` (requires an authenticated `gh`). The repo name is `claude-config`. If neither resolves (`gh` is missing or unauthenticated **and** the user gave no URL), ask the user for the remote URL rather than guessing. Any remote the skill *creates* is **private** (see the golden rules); never public. ## Golden rules - **Never force-push.** No `--force`, no `--force-with-lease`, no `--no-verify`, no rewriting commits already pushed to the remote. The sync repo is the source of truth between machines; rewriting its history can lose work from a machine that has not been pulled here yet. - **Never modify a file outside `~/.claude-config/`.** If the user's intended change is to a file in `~/.claude/` directly (not via a symlink into `~/.claude-config/`), surface that and stop; they need a different action, not this skill. The **one** exception is the fresh-host symlink wiring during bootstrap (`ln -sfn ~/.claude-config/... ~/.claude/...`), and only after the user confirms it; see [Bootstrapping a missing `~/.claude-config/`](#bootstrapping-a-missing-claude-config). - **Any remote the skill creates is private.** When bootstrap creates a new remote (`gh repo create`), it always passes `--private`: never public, never `--internal` unless the user asks. `~/.claude/CLAUDE.md` carries personal collaboration preferences and the scripts may reference internal paths; a public config repo leaks both. This mirrors the doc's *"a **private** git repository (private, not public …)"* rule. - **Confirm before creating or pushing to a new remote.** Creating a GitHub repo and pushing the first commit is outward-facing and hard to reverse. Bootstrap shows the exact plan (repo name, `--private` visibility, remote URL, the files it will scaffold) and waits for explicit approval before running `gh repo create` or the initial `git push`. **Cloning** an existing remote is lower-risk (it writes only into the new `~/.claude-config/` checkout) and may proceed without a separate confirmation, though the skill still reports what it cloned. - **Never clobber a non-repo `~/.claude-config/`.** If the path exists but is not a git working tree, stop and surface it; do not `rm` it or `git init` over it. Bootstrap only ever *creates* a `~/.claude-config/` that was entirely absent. - **Pull-with-rebase first.** If `git fetch` shows the local checkout is behind the remote, run `git pull --rebase --autostash` *before* the commit + push. Concurrent work from another machine takes precedence; the local commit lands on top, as the example `sync.sh` does for the periodic pull. - **Draft the commit message; never auto-send.** For every uncommitted change, draft a one-line commit subject (plus a 2–4 line body if the change merits it) and show it to the user. The user replies *"go"* / *"yes"* / edits / *"split into two commits"* etc. before any `git commit` runs. - **Use the resolved attribution trailer, added with `--trailer`.** Agent-authored commits carry the trailer the user's commit-attribution convention names, resolved per [`commit-attribution.md`](../../../../docs/setup/commit-attribution.md) (the sync repo has no project file, so the user's choice applies, else `Generated-by: <agent> (<model>)`), where `<agent>` and `<model>` are the agent and model you are actually running as (e.g. `Claude (Opus 4.8)`, `OpenCode (Big Pickle)`). Add it with `git commit --trailer`, never in the message body. Do not hardcode either, and never use `Co-Authored-By:`. Canonical wording: [AGENTS.md → Commit and PR conventions](../../../../AGENTS.md#commit-and-pr-conventions). - **Stop on lock conflict.** The example `sync.sh` uses `flock --nonblock` on `~/.claude-config/.sync.lock` so two sync runs do not race. If `.sync.lock` is held, do not steal the lock; surface the conflict and stop. The other process is likely the user's recurring sync timer. ## Bootstrapping a missing `~/.claude-config/` Reached from [Walk-through step 1](#walk-through) when the sync repo is **entirely absent**. The goal is a working `~/.claude-config/` git checkout wired to a private remote, by cloning the default remote if it exists or creating it if not. The skill touches nothing outside the new checkout except the confirmed fresh-host symlink wiring at the end. ### Step B1 — resolve the remote Resolve the remote per [The default remote](#the-default-remote): an explicit URL the user passed, else `git@github.com:<handle>/claude-config.git` with `<handle>` from `gh api user --jq .login`. If neither resolves (`gh` missing/unauthenticated **and** no URL given), ask the user for the remote URL and stop until they provide one; do not guess a handle. ### Step B2 — does the remote exist? - **GitHub default:** `gh repo view <handle>/claude-config`: exit `0` ⇒ exists, non-zero ⇒ does not exist. If the error is auth/permission rather than "not found", surface it and stop rather than assuming absence. - **Explicit non-GitHub URL:** `git ls-remote <url>`: exit `0` ⇒ exists, non-zero ⇒ does not exist / unreachable. ### Step B3a — remote exists → clone `git clone <url> ~/.claude-config`. This low-risk path (it writes only the new checkout) may proceed without a separate create-confirmation; report the clone result. Then continue to [Step B4 — fresh-host symlink wiring](#step-b4--fresh-host-symlink-wiring) and resume the sync walk-through from step 2 (typically *"in sync, nothing to do"*). ### Step B3b — remote does not exist → create + scaffold + push Creating an outward-facing remote is confirm-first (golden rule). **Show the full plan and wait for explicit approval**: the repo name, `--private` visibility, the remote URL, and the files to be scaffolded. On approval: 1. **Create the private remote.** - GitHub: `gh repo create <handle>/claude-config --private --description "Personal Claude Code shared config (synced across machines)"` (no `--clone`, no auto-init; the local scaffold below becomes the first commit). - Non-GitHub explicit URL: the skill cannot create the remote; tell the user to create an **empty private** repo at that URL and re-invoke. 2. **Init + scaffold the minimal layout** under `~/.claude-config/`, matching the doc's [Layout](../../../../docs/setup/secure-agent-setup.md#layout) and [A minimal `sync.sh`](../../../../docs/setup/secure-agent-setup.md#a-minimal-syncsh): ```text git init -b main ~/.claude-config ~/.claude-config/ ├── README.md # what's in the repo + per-machine install steps ├── sync.sh # the pull/commit/push helper (chmod +x) ├── scripts/ # (empty; hooks land here as the user adopts them) └── .gitignore # excludes .sync.lock and any *.credentials* / secrets ``` `sync.sh` is the verbatim script from the doc's [A minimal `sync.sh`](../../../../docs/setup/secure-agent-setup.md#a-minimal-syncsh) section. `.gitignore` must at minimum carry `.sync.lock` (the `flock` file) so the lock is never committed. 3. **Initial commit + push.** `git add` the scaffolded files individually (never `git add -A`; see [Walk-through](#walk-through) step 5), commit with the resolved attribution trailer (via `--trailer`), `git remote add origin <url>`, then `git push -u origin main`. ### Step B4 — fresh-host symlink wiring The new (or freshly cloned) checkout only *protects* this host once its tracked artifacts are symlinked into `~/.claude/`. This is the **one** write outside `~/.claude-config/` the skill performs, and only after the user confirms. Offer to run the [Setting up a fresh host](../../../../docs/setup/secure-agent-setup.md#setting-up-a-fresh-host) wiring (the `ln -sfn ~/.claude-config/… ~/.claude/…` block, which `mv`s any pre-existing real file to `.bak` before symlinking). If the user declines, point them at that doc section. Wire only the artifacts the checkout contains; on a brand-new scaffold `scripts/` may be empty, so this step is often a no-op beyond `CLAUDE.md`. ## Walk-through 1. **`cd ~/.claude-config`** and verify it is a git working tree pointing at a private remote. - If the directory **does not exist** at all, do not stop — **bootstrap** it: jump to [Bootstrapping a missing `~/.claude-config/`](#bootstrapping-a-missing-claude-config), then resume the sync walk-through from step 2. - If the directory **exists but is not a git repo**, surface that and stop (per the golden rule — never clobber a non-repo path). The user has a stray `~/.claude-config/`; they resolve it, then re-invoke. - If it is a git repo, continue to step 2. 2. **`git fetch origin`** to learn the remote's current state. Report: - commits behind upstream (will be pulled in step 4), - commits ahead of upstream (committed local work not yet pushed), - uncommitted working-tree modifications (`git status --short`), - untracked files the user may want to either add or `.gitignore`. 3. **Decide the action.** The four reachable states: - **In sync, nothing to do.** No uncommitted changes, no unpushed commits, not behind. Report and stop. - **Push-only.** Committed local work needs to land on the remote, but not behind and no uncommitted edits. Pull-with-rebase is unnecessary; go straight to push. - **Commit-then-push.** Uncommitted edits exist. Walk each modified file with the user (diff + draft commit message + approval), commit each batch the user accepts, then push. - **Pull-then-commit-then-push.** Uncommitted edits *and* behind upstream. Run `git pull --rebase --autostash` first; if rebase succeeds cleanly, proceed to the commit-then-push flow. If rebase conflicts, stop and surface — conflicts in `~/.claude-config/` are the user's to resolve, not the skill's. 4. **Pull-with-rebase (when applicable).** Run `git pull --rebase --autostash`. Report what changed (commits pulled, files touched). 5. **Stage + commit (when applicable).** For each modification the user approves: - `git add <file>` for the specific file (never `git add -A` or `git add .` — the sync repo is the user's most personal directory and `git add -A` risks staging an editor swap file or a `.DS_Store` you forgot to gitignore), - `git commit -m '<subject>' -m '<body>' --trailer '<trailer>'` with the approved message. `<trailer>` is the resolved attribution trailer (see the golden rule above) — the actual agent and model you are running as, not a hardcoded value; omit `--trailer` when the convention is `none`. Probe the gpg-agent cache first when `commit.gpgsign` is true: a token-backed key with a cold cache stalls this commit until `gpg: signing failed: Timeout`. Surface a dialogue, or hand the user the command — see [`AGENTS.md` → *Commit and PR conventions*](../../../../AGENTS.md#commit-and-pr-conventions). 6. **Push.** `git push` to the upstream branch. No `--force`. A rejected (non-fast-forward) push means another machine pushed after our `git fetch` in step 2; stop, surface, and recommend re-invoking the skill (which repeats the fetch + pull-with-rebase). Do not retry in-flight. ## After the push lands Report: - which commit SHA is now on the remote, - a one-line summary of what was pushed (so the user can confirm in their terminal scrollback), - whether other-machine pulls are needed (the timer-driven `sync.sh` on the user's other hosts picks the change up on its next run; do not nag about this). If the changes touched a file under `~/.claude-config/scripts/` that is symlinked from `~/.claude/scripts/`, also note that the change is *immediately* live on this host, since the symlink resolves to the modified file. No re-`cp` needed.