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 (committed, project-wide) in the adopter repo, if present, and applies any agent-readable overrides it finds. See 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. 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/), 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 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/.
• 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 (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.
• 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 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: 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 and resume the sync walk-through from step 2 (typically "in sync, nothing to do").