Stack update

This kit installs by copying files into ~/.claude — once copied, an installed file has no link back to the repo. This skill is the manual apply step for the update the SessionStart hook noticed: fetch upstream, show what changed, gate on approval, and (critically) reconcile CLAUDE.md, which install.sh's default ("auto") mode never overwrites once it exists — a --claude-md=replace run (not used by this skill's step 6) does.

State dir: ${CLAUDE_HOME:-$HOME/.claude}/.claude-code-setup/ — installed (SHA that skills, agents, and settings are at), claude-md-installed (SHA whose global/CLAUDE.md the user actually accepted — written only when they applied the upstream hunks or confirmed a completed hand-merge, never on a plain skip; if absent, there is no known base — install.sh only writes it when it copied CLAUDE.md for a user who had none, so anyone with a pre-existing personal CLAUDE.md has no stamp at all; never fall back to installed, see step 5), claude-md-skipped (SHA of upstream's global/CLAUDE.md at the point the user last declined to reconcile it — suppresses re-showing an identical comparison in step 5; never used as a diff base and never implies acceptance), last-check (epoch of last poll), remote (<installed> <remote> <count> from the last successful poll — replayed at each session start while installed still matches), notice (the session-start notice in the user's language, see step 7), disabled (presence silences the SessionStart check entirely; touch it to opt out).

Repo: https://github.com/TurboKach/claude-code-setup.git, default branch master (not main).

Procedure

Steps 1–3 are read-only reconnaissance — nothing outside the scratchpad clone is touched, and no state-dir file is written, until the approval gate in step 4 passes.

1. Read state. Read installed from the state dir — this is the SHA to diff against. Do not modify any state file yet.

2. Clone. Full git clone (not --depth) of the repo into the session scratchpad. Full history, because step 3 needs <installed> reachable to diff against; the repo is small, so a shallow clone buys nothing here. The clone is read-only reconnaissance — nothing is copied out of it until approval.

3. Summarize what's new, grouped by surface. First check history shape with git merge-base --is-ancestor <installed> HEAD:

   • Ancestor (normal case) — derive the summary from git log --oneline <installed>..HEAD and git diff --stat <installed>..HEAD; raw commit subjects are not the deliverable, a "what changes for me" bullet list is.
   • Reachable but not an ancestor — upstream rewrote history (force-push). Label the summary as divergent history, not "what changed since you installed": <installed>..HEAD is a set difference, not a lineage, and would misrepresent it. Base the bullets on git diff <installed>..HEAD instead (endpoint comparison — stays correct regardless of rewritten history).
   • <installed> empty, unknown, or unreachable at all — say plainly that a change summary is unavailable because there's no base to diff against. Show only the current HEAD SHA and short subject, and the last ~10 commit subjects (git log --oneline -10) as context — and label that list explicitly as not a diff against what the user has installed.

   Write the summary in the language you answer the user in — Claude Code's language setting when set, else the conversation's — not the commit subjects' language. Group bullets by the surfaces the user actually has installed, each stated in user-facing terms (not a hash dump):

   • global/CLAUDE.md → their always-on rules — what changed, in a sentence.
   • skills/* → which skills are new or changed.
   • agents/* → which role agents changed.
   • global/rules/* → which path-scoped user rules are new or changed.
   • hooks/* → what now happens differently at session start or on tool calls.
   • install.sh / settings.example.json → what the installer will now do differently, including a changed recommended master (model / modelSettings) — step 6 may ask about it. Omit a group with no changes.

4. Approval gate #1 — apply the update at all? AskUserQuestion whose question text opens with step 3's summary — What's new since <installed short SHA> (<N> commits): and the bullets, or step 3's divergent-history / no-base label in their place — and ends "Apply this update?", with options Apply / Show the full diff first / Cancel. The summary goes in the question even when the user wrote the commits.

   • Show the full diff first → show it, then re-ask this same question; it is not itself an answer.
   • Cancel → stop here. Nothing is written and the state dir is left exactly as it was — do not touch installed or last-check, so the update notice correctly reappears next session.
   • Silence, or the question going unanswered, is not approval — never infer Apply from a default or from the user being away.
   • Only Apply proceeds past this point.

5. The CLAUDE.md three-way diff and approval gate #2 — this is the step that justifies the skill. Step 6 below runs install.sh with no --claude-md flag, so its default (--claude-md unset, i.e. "auto") mode applies: it deliberately never overwrites an existing ~/.claude/CLAUDE.md (see the CLAUDE.md block in install.sh) — it just prints a reminder to merge by hand. So step 6's install refreshes skills and agents but silently skips the single most important file, and a two-way diff can't tell an upstream improvement apart from the user's own customization. Do it properly. Use claude-md-installed as the base for this diff, not installed — it's the SHA the user actually accepted CLAUDE.md at, which may lag installed if a prior run was skipped or handed off for manual merge.

   • claude-md-installed exists (normal case) — three-way diff:
     • git show <claude-md-installed>:global/CLAUDE.md — what the user last accepted.
     • the clone's global/CLAUDE.md — what upstream has now.
     • the live ~/.claude/CLAUDE.md — the user's file, possibly hand-edited. Diff the first two to isolate what actually changed upstream, then show that upstream change against the live file.
   • claude-md-installed is absent — unknown base, do not fall back to installed. This is the common case: install.sh only writes claude-md-installed when it copies CLAUDE.md for a user who had none, so anyone who already had a personal CLAUDE.md (i.e. every existing user) ends up with an installed SHA but no claude-md-installed. Falling back to installed would silently claim they accepted that revision's global/CLAUDE.md, which they never did, and would permanently hide every upstream change made before it. Check claude-md-skipped first:
     • Absent, or upstream's global/CLAUDE.md has changed since the SHA it records — say plainly there's no record of which global/CLAUDE.md revision they've accepted (either their CLAUDE.md predates the marker, or they've always kept their own), and show a two-way diff instead — the clone's current global/CLAUDE.md against the live ~/.claude/CLAUDE.md — labeled explicitly as "upstream's current version vs yours", not as "what changed upstream since you installed". This diff will be noisy if they carry heavy local edits — expected and honest. Proceed to the gate #2 question below.
     • Present, and upstream's global/CLAUDE.md is unchanged since that SHA — nothing new to show. Note in one line that the CLAUDE.md reconciliation the user previously declined is still outstanding, skip re-rendering the diff, and skip gate #2 for this run. Then a separate AskUserQuestion — approving the bundle in gate #1 is not approval to rewrite CLAUDE.md, it's a distinct decision because the live file may carry local edits — with three choices: apply the upstream hunks (back up the live file first, preserve any local edits that don't conflict) / show the full diff and let the user decide by hand / skip CLAUDE.md entirely. Never rewrite ~/.claude/CLAUDE.md without an explicit answer to this question — silence is not approval.

6. Install. First, the master-model question — asked on every update unless the user already has it or said not to. Ask only when both hold:

   • the live ~/.claude/settings.json doesn't match the clone's settings.example.json recommendation: model differs ignoring a trailing [1m] in any casing — it selects the same model's 1M window — or any master modelSettings.<id>.effortLevel there differs (every entry except claude-sonnet-5-5, the executors' level, which install.sh fills in only where none is saved);
   • ~/.claude/.claude-code-setup/master-dont-ask is absent, or its content differs from python3 -c 'import json,sys; e=json.load(open(sys.argv[1])); print(json.dumps({"model": e["model"], "modelSettings": {k: v for k, v in e["modelSettings"].items() if k != "claude-sonnet-5-5"}}, separators=(",", ":"), sort_keys=True))' settings.example.json run in the clone (a changed recommendation asks again).

   Then AskUserQuestion, showing their current model and effort, with options the recommended model and effort, named from the clone's settings.example.json (recommended) → --master=recommended / keep current, ask next time → --master=keep / don't ask again → --master=dont-ask / other, the user types MODEL_ID or MODEL_ID:EFFORT → --master=<typed>. Not asked → no --master flag.

   Run ./install.sh from the clone, with that --master flag if one was chosen. It already backs up skills and agents to ~/.claude/.backup-<stamp> and merges settings.json keys — reuse it, don't reimplement its logic here.

   • If it exits non-zero: stop — do not write installed or claude-md-installed, the run is not complete. Report exactly what was and wasn't applied (skills/agents may be partially updated; CLAUDE.md may already have been changed by gate #2 above, before this step ran). Point the user at the restore path: ~/.claude/.backup-<stamp> (skills/agents backup install.sh already took) and, if gate #2 applied hunks, the CLAUDE.md backup it took. Don't invent a rollback — just leave the state files untouched and tell the user where the backups are.

7. Update state. Only now write to the state dir, and only on a zero-exit install:

   • installed — the clone's new HEAD SHA. After install.sh succeeds, skills, agents, and settings genuinely are at this revision.
   • claude-md-installed and claude-md-skipped — one rule, unconditional, no per-path exception, applies whether this was the three-way or unknown-base case in step 5:
     • Gate #2 answered apply the upstream hunks — write claude-md-installed at the clone's new HEAD SHA, and delete claude-md-skipped if present. This is the only answer that stamps acceptance, because it's the only one where CLAUDE.md was actually rewritten.
     • Gate #2 answered skip or show the full diff and decide by hand, or gate #2 wasn't asked this run (step 5's suppressed case) — leave claude-md-installed untouched (do not write it, even if absent), and write claude-md-skipped at the clone's new HEAD SHA. The declined or unconfirmed CLAUDE.md change stays pending and resurfaces in the next run's step 5 instead of being silently dropped or falsely marked accepted.
   • Delete last-check so the next session re-polls fresh instead of trusting the 24h cache.
   • notice — the hook shows this line at session start, before the user has typed anything, so it can't take the language from the conversation. Write one line in the language you answer in, with the placeholders {n} (commit count, or ?), {from} and {to} (short SHAs), phrased so any count reads correctly — e.g. New changes: {n} ({from} → {to}) — run /stack-update, translated. When that language is English, delete notice instead; the hook's built-in English wording is used.

8. Tell the user to restart Claude Code. Skills, agents, hooks, and settings env are all read at session start — nothing applied by this run is live in the current session until it's restarted.

Opt-out

touch ~/.claude/.claude-code-setup/disabled silences the SessionStart update check permanently (delete the file to re-enable).