When to invoke
Invoke when the user says "upgrade goc", "pull the latest goc", "sync goc templates", "run goc upgrade", or asks how to upgrade the GoC version in this repo. The engine's safety guarantee — never overwrite authored project state — holds with or without this skill; the skill exists to reconcile evolving upstream content into the local copy where the engine's "preserve" verdict alone leaves real upstream changes on the floor.
Upgrade GoC
goc upgrade is deterministic and safe by construction — it never
overwrites authored content under .game-of-cards/. That guarantee
holds for every consumer regardless of whether an agent is present
(headless CI runs, scheduled cron, scripted upgrades).
But "never overwrite" is not the same as "stay current". Two files
under .game-of-cards/ ship real, evolving content that the upstream
template may have changed across versions:
README.md — the hook-point catalogue documenting which content
stubs and workflow hooks the skills consume, and where.
config.yaml — the runtime-neutral closure attestation config
(layer_2_project_dod, layer_3_goc_dod) plus workflow options.
If the engine has preserved a diverged copy of either, the engine
itself has nothing to say about whether real upstream changes need to
land in the consumer's local copy. That is this skill's job.
For the 12 user-owned content stubs and workflow hooks, the engine's
"preserved" verdict is the whole story — the templates ship blank by
design, so there is nothing to reconcile. This skill confirms that to
the user so they know nothing was lost.
For the AGENTS.md / CLAUDE.md GoC marker block, the engine
regenerates the goc-owned region wholesale via the marker-bounded
merge (<!-- BEGIN GOC vX.Y.Z --> … <!-- END GOC -->). That region
is goc-owned, not user-owned, so nothing to reconcile — this skill
summarizes what methodology guidance changed across the upgrade so
the user knows what new behavior the agents will now follow.
Workflow
Run goc upgrade and capture stdout. The engine emits a
sentinel-marked JSON divergence report after its normal upgrade
output. Plain goc upgrade is the whole invocation: the report
follows on every run, including one that answers
already at goc X — nothing to do. because the version is
already current (someone ran goc upgrade in a terminal first,
or an earlier session stopped after this step). A diverged file
gives the engine nothing to write, but it is still in the report:
GoC project-state divergence report (JSON):
{"version": 1, "templates_root": "...", "files": [...]}
Parse the JSON on the line immediately following the marker. Each
entry has path (relative to .game-of-cards/), status
(create / unchanged / preserved), and ownership
(user-owned / evolving).
For each evolving file with status: preserved — read the
local file at .game-of-cards/<path> AND the shipped template at
<templates_root>/<path>. Drive a 2-way reconcile:
- Diff the two files mentally. Identify what changed upstream
(lines present in the template that are absent or different in
the local copy).
- For each upstream change, decide whether it should land:
- Mechanical updates (new key with default value, new
comment, new doc paragraph that does not contradict local
customization) → propose the merged content and
AskUserQuestion
for confirmation.
- Conflicting with the user's customization → describe both
sides and ask the user how to resolve. Default to keeping the
user's value; surface the upstream change as informational.
- When the user approves, write the merged content back to
.game-of-cards/<path> directly. Do not invoke goc upgrade
again — the engine has already done its work; this is a one-shot
reconciliation.
- If the local file and template are obviously compatible (e.g.,
local added a new top-level key the template doesn't know about,
and the template added an unrelated comment), apply both sides
and report the merged result.
For each user-owned file with status: preserved — confirm
to the user, in one line per file: "kept your <path> (nothing
upstream)". The shipped template is permanently blank by design,
so there is no upstream content to bring across. The confirmation
exists so the user does not have to wonder whether the upgrade
silently overwrote anything.
For files with status: create — these are absent locally and
were scaffolded by the engine. Mention them so the user knows new
files appeared (e.g., a new workflow-hook stub for a skill that
landed in this version).
For files with status: unchanged — silent. The local copy
already matches the template; nothing to report.
Summarize AGENTS.md / CLAUDE.md GoC block changes. Diff the
<!-- BEGIN GOC vX.Y.Z --> … <!-- END GOC --> region before and
after the upgrade (the engine already rewrote it; git diff on
the working tree surfaces the delta), and present a short list of
substantive methodology changes — new verbs documented, new
conventions enforced, behavioral defaults flipped. This is
informational, not a merge — the marker-bounded region is
goc-owned and the upgrade contract is that it gets regenerated.
Commit follows repo policy. If the reconciliation pass
modified any files, the user typically wants those staged
alongside the engine's own changes (the bumped .goc-version,
the rewritten methodology block, any newly-scaffolded files). The
engine's goc upgrade does NOT auto-commit; commit the union of
engine writes + reconciliation edits with a subject like
chore(goc): upgrade to vX.Y.Z.
Why the engine is safe without this skill
The engine's _sync_game_of_cards_config classifies every shipped
file against the on-disk copy and only writes when the destination is
absent. Diverged files are preserved unconditionally — no prompt, no
confirmation, no agent in the loop. This means:
- A scripted upgrade in CI does not lose authored content.
- A scheduled cron
goc upgrade does not lose authored content.
- A user running
goc upgrade in a terminal without invoking this
skill does not lose authored content.
What the user loses without this skill is informational reconciliation
of upstream changes to the two evolving files. The local copies stay
exactly as the user left them; the upstream changes sit in the
template payload until the next time someone runs this skill (or
manually diffs .game-of-cards/README.md against
<templates_root>/README.md). That holds after the version is
already current too, because the engine's no-op run still prints
the report.
What this skill does NOT do
- Does NOT re-run
goc upgrade. The engine has already done its
work by the time this skill is reading the report. Re-running
would write nothing (version is now current) and print the same
report again.
- Does NOT overwrite user-owned content stubs or workflow hooks. The
templates are blank by design — there is nothing upstream to
bring across, so the reconcile pass for those files is purely a
confirmation.
- Does NOT touch the
AGENTS.md / CLAUDE.md GoC marker block.
The engine regenerates that region wholesale on every upgrade; the
contract is "do not edit between the markers."
- Does NOT bisect or
git revert the engine's writes. If the
reconciliation pass produces a result the user dislikes, the user
edits the file by hand or invokes Skill(create-card) to file
the disagreement as a card for follow-up.
Cross-references
Skill(kickoff) — first-time setup in a fresh repo. The kickoff
skill writes the initial .game-of-cards/ scaffold; this skill is
the follow-up that runs every time the user wants to pull a new
goc version into an existing repo.
Skill(card-schema) — frontmatter and DoD conventions the upgraded
engine may have evolved.
Skill(deck) — the methodology surface the regenerated AGENTS.md /
CLAUDE.md block documents.
1---2name: upgrade-23description: Run goc upgrade, then drive LLM reconciliation of evolving .game-of-cards/ files from the engine's divergence report, preserving user-owned content. AUTO-INVOKE on "upgrade goc", "run goc upgrade", "sync goc templates".4argument-hint: (no arguments)5metadata:6 source: https://skillmd.com/skills/zauberzeug/upgrade-27---89## When to invoke1011Invoke when the user says "upgrade goc", "pull the latest goc", "sync goc templates", "run goc upgrade", or asks how to upgrade the GoC version in this repo. The engine's safety guarantee — never overwrite authored project state — holds with or without this skill; the skill exists to reconcile *evolving* upstream content into the local copy where the engine's "preserve" verdict alone leaves real upstream changes on the floor.1213# Upgrade GoC1415`goc upgrade` is deterministic and safe by construction — it never16overwrites authored content under `.game-of-cards/`. That guarantee17holds for every consumer regardless of whether an agent is present18(headless CI runs, scheduled cron, scripted upgrades).1920But "never overwrite" is not the same as "stay current". Two files21under `.game-of-cards/` ship real, evolving content that the upstream22template may have changed across versions:2324- `README.md` — the hook-point catalogue documenting which content25 stubs and workflow hooks the skills consume, and where.26- `config.yaml` — the runtime-neutral closure attestation config27 (`layer_2_project_dod`, `layer_3_goc_dod`) plus workflow options.2829If the engine has preserved a *diverged* copy of either, the engine30itself has nothing to say about whether real upstream changes need to31land in the consumer's local copy. **That is this skill's job.**3233For the 12 user-owned content stubs and workflow hooks, the engine's34"preserved" verdict is the whole story — the templates ship blank by35design, so there is nothing to reconcile. This skill confirms that to36the user so they know nothing was lost.3738For the `AGENTS.md` / `CLAUDE.md` GoC marker block, the engine39regenerates the goc-owned region wholesale via the marker-bounded40merge (`<!-- BEGIN GOC vX.Y.Z -->` … `<!-- END GOC -->`). That region41is goc-owned, not user-owned, so nothing to reconcile — this skill42summarizes what methodology guidance changed across the upgrade so43the user knows what new behavior the agents will now follow.4445## Workflow46471. **Run `goc upgrade` and capture stdout.** The engine emits a48 sentinel-marked JSON divergence report after its normal upgrade49 output. Plain `goc upgrade` is the whole invocation: the report50 follows on every run, including one that answers51 `already at goc X — nothing to do.` because the version is52 already current (someone ran `goc upgrade` in a terminal first,53 or an earlier session stopped after this step). A diverged file54 gives the engine nothing to write, but it is still in the report:5556 ```57 GoC project-state divergence report (JSON):58 {"version": 1, "templates_root": "...", "files": [...]}59 ```6061 Parse the JSON on the line immediately following the marker. Each62 entry has `path` (relative to `.game-of-cards/`), `status`63 (`create` / `unchanged` / `preserved`), and `ownership`64 (`user-owned` / `evolving`).65662. **For each `evolving` file with `status: preserved`** — read the67 local file at `.game-of-cards/<path>` AND the shipped template at68 `<templates_root>/<path>`. Drive a 2-way reconcile:6970 - Diff the two files mentally. Identify what changed *upstream*71 (lines present in the template that are absent or different in72 the local copy).73 - For each upstream change, decide whether it should land:74 - **Mechanical updates** (new key with default value, new75 comment, new doc paragraph that does not contradict local76 customization) → propose the merged content and `AskUserQuestion`77 for confirmation.78 - **Conflicting with the user's customization** → describe both79 sides and ask the user how to resolve. Default to keeping the80 user's value; surface the upstream change as informational.81 - When the user approves, write the merged content back to82 `.game-of-cards/<path>` directly. Do not invoke `goc upgrade`83 again — the engine has already done its work; this is a one-shot84 reconciliation.85 - If the local file and template are obviously compatible (e.g.,86 local added a new top-level key the template doesn't know about,87 and the template added an unrelated comment), apply both sides88 and report the merged result.89903. **For each `user-owned` file with `status: preserved`** — confirm91 to the user, in one line per file: "kept your `<path>` (nothing92 upstream)". The shipped template is permanently blank by design,93 so there is no upstream content to bring across. The confirmation94 exists so the user does not have to wonder whether the upgrade95 silently overwrote anything.96974. **For files with `status: create`** — these are absent locally and98 were scaffolded by the engine. Mention them so the user knows new99 files appeared (e.g., a new workflow-hook stub for a skill that100 landed in this version).1011025. **For files with `status: unchanged`** — silent. The local copy103 already matches the template; nothing to report.1041056. **Summarize AGENTS.md / CLAUDE.md GoC block changes.** Diff the106 `<!-- BEGIN GOC vX.Y.Z -->` … `<!-- END GOC -->` region before and107 after the upgrade (the engine already rewrote it; `git diff` on108 the working tree surfaces the delta), and present a short list of109 substantive methodology changes — new verbs documented, new110 conventions enforced, behavioral defaults flipped. This is111 informational, not a merge — the marker-bounded region is112 goc-owned and the upgrade contract is that it gets regenerated.1131147. **Commit follows repo policy.** If the reconciliation pass115 modified any files, the user typically wants those staged116 alongside the engine's own changes (the bumped `.goc-version`,117 the rewritten methodology block, any newly-scaffolded files). The118 engine's `goc upgrade` does NOT auto-commit; commit the union of119 engine writes + reconciliation edits with a subject like120 `chore(goc): upgrade to vX.Y.Z`.121122## Why the engine is safe without this skill123124The engine's `_sync_game_of_cards_config` classifies every shipped125file against the on-disk copy and only writes when the destination is126absent. Diverged files are preserved unconditionally — no prompt, no127confirmation, no agent in the loop. This means:128129- A scripted upgrade in CI does not lose authored content.130- A scheduled cron `goc upgrade` does not lose authored content.131- A user running `goc upgrade` in a terminal without invoking this132 skill does not lose authored content.133134What the user loses without this skill is *informational reconciliation*135of upstream changes to the two evolving files. The local copies stay136exactly as the user left them; the upstream changes sit in the137template payload until the next time someone runs this skill (or138manually diffs `.game-of-cards/README.md` against139`<templates_root>/README.md`). That holds after the version is140already current too, because the engine's no-op run still prints141the report.142143## What this skill does NOT do144145- Does NOT re-run `goc upgrade`. The engine has already done its146 work by the time this skill is reading the report. Re-running147 would write nothing (version is now current) and print the same148 report again.149- Does NOT overwrite user-owned content stubs or workflow hooks. The150 templates are blank by design — there is nothing upstream to151 bring across, so the reconcile pass for those files is purely a152 confirmation.153- Does NOT touch the `AGENTS.md` / `CLAUDE.md` GoC marker block.154 The engine regenerates that region wholesale on every upgrade; the155 contract is "do not edit between the markers."156- Does NOT bisect or `git revert` the engine's writes. If the157 reconciliation pass produces a result the user dislikes, the user158 edits the file by hand or invokes `Skill(create-card)` to file159 the disagreement as a card for follow-up.160161## Cross-references162163- `Skill(kickoff)` — first-time setup in a fresh repo. The kickoff164 skill writes the initial `.game-of-cards/` scaffold; this skill is165 the follow-up that runs every time the user wants to pull a new166 goc version into an existing repo.167- `Skill(card-schema)` — frontmatter and DoD conventions the upgraded168 engine may have evolved.169- `Skill(deck)` — the methodology surface the regenerated AGENTS.md /170 CLAUDE.md block documents.