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 the create-card skill to file
the disagreement as a card for follow-up.
Cross-references
- the
kickoff skill — 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.
- the
card-schema skill — frontmatter and DoD conventions the upgraded
engine may have evolved.
- the
deck skill — the methodology surface the regenerated AGENTS.md /
CLAUDE.md block documents.
1---2name: upgrade-33description: 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". If the catalog location path is unreadable, fetch the body via the goc tool verb "skill", args ["upgrade"].4metadata:5 source: https://skillmd.com/skills/zauberzeug/upgrade-36---78## When to invoke910Invoke 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.1112# Upgrade GoC1314`goc upgrade` is deterministic and safe by construction — it never15overwrites authored content under `.game-of-cards/`. That guarantee16holds for every consumer regardless of whether an agent is present17(headless CI runs, scheduled cron, scripted upgrades).1819But "never overwrite" is not the same as "stay current". Two files20under `.game-of-cards/` ship real, evolving content that the upstream21template may have changed across versions:2223- `README.md` — the hook-point catalogue documenting which content24 stubs and workflow hooks the skills consume, and where.25- `config.yaml` — the runtime-neutral closure attestation config26 (`layer_2_project_dod`, `layer_3_goc_dod`) plus workflow options.2728If the engine has preserved a *diverged* copy of either, the engine29itself has nothing to say about whether real upstream changes need to30land in the consumer's local copy. **That is this skill's job.**3132For the 12 user-owned content stubs and workflow hooks, the engine's33"preserved" verdict is the whole story — the templates ship blank by34design, so there is nothing to reconcile. This skill confirms that to35the user so they know nothing was lost.3637For the `AGENTS.md` / `CLAUDE.md` GoC marker block, the engine38regenerates the goc-owned region wholesale via the marker-bounded39merge (`<!-- BEGIN GOC vX.Y.Z -->` … `<!-- END GOC -->`). That region40is goc-owned, not user-owned, so nothing to reconcile — this skill41summarizes what methodology guidance changed across the upgrade so42the user knows what new behavior the agents will now follow.4344## Workflow45461. **Run `goc upgrade` and capture stdout.** The engine emits a47 sentinel-marked JSON divergence report after its normal upgrade48 output. Plain `goc upgrade` is the whole invocation: the report49 follows on every run, including one that answers50 `already at goc X — nothing to do.` because the version is51 already current (someone ran `goc upgrade` in a terminal first,52 or an earlier session stopped after this step). A diverged file53 gives the engine nothing to write, but it is still in the report:5455 ```56 GoC project-state divergence report (JSON):57 {"version": 1, "templates_root": "...", "files": [...]}58 ```5960 Parse the JSON on the line immediately following the marker. Each61 entry has `path` (relative to `.game-of-cards/`), `status`62 (`create` / `unchanged` / `preserved`), and `ownership`63 (`user-owned` / `evolving`).64652. **For each `evolving` file with `status: preserved`** — read the66 local file at `.game-of-cards/<path>` AND the shipped template at67 `<templates_root>/<path>`. Drive a 2-way reconcile:6869 - Diff the two files mentally. Identify what changed *upstream*70 (lines present in the template that are absent or different in71 the local copy).72 - For each upstream change, decide whether it should land:73 - **Mechanical updates** (new key with default value, new74 comment, new doc paragraph that does not contradict local75 customization) → propose the merged content and `AskUserQuestion`76 for confirmation.77 - **Conflicting with the user's customization** → describe both78 sides and ask the user how to resolve. Default to keeping the79 user's value; surface the upstream change as informational.80 - When the user approves, write the merged content back to81 `.game-of-cards/<path>` directly. Do not invoke `goc upgrade`82 again — the engine has already done its work; this is a one-shot83 reconciliation.84 - If the local file and template are obviously compatible (e.g.,85 local added a new top-level key the template doesn't know about,86 and the template added an unrelated comment), apply both sides87 and report the merged result.88893. **For each `user-owned` file with `status: preserved`** — confirm90 to the user, in one line per file: "kept your `<path>` (nothing91 upstream)". The shipped template is permanently blank by design,92 so there is no upstream content to bring across. The confirmation93 exists so the user does not have to wonder whether the upgrade94 silently overwrote anything.95964. **For files with `status: create`** — these are absent locally and97 were scaffolded by the engine. Mention them so the user knows new98 files appeared (e.g., a new workflow-hook stub for a skill that99 landed in this version).1001015. **For files with `status: unchanged`** — silent. The local copy102 already matches the template; nothing to report.1031046. **Summarize AGENTS.md / CLAUDE.md GoC block changes.** Diff the105 `<!-- BEGIN GOC vX.Y.Z -->` … `<!-- END GOC -->` region before and106 after the upgrade (the engine already rewrote it; `git diff` on107 the working tree surfaces the delta), and present a short list of108 substantive methodology changes — new verbs documented, new109 conventions enforced, behavioral defaults flipped. This is110 informational, not a merge — the marker-bounded region is111 goc-owned and the upgrade contract is that it gets regenerated.1121137. **Commit follows repo policy.** If the reconciliation pass114 modified any files, the user typically wants those staged115 alongside the engine's own changes (the bumped `.goc-version`,116 the rewritten methodology block, any newly-scaffolded files). The117 engine's `goc upgrade` does NOT auto-commit; commit the union of118 engine writes + reconciliation edits with a subject like119 `chore(goc): upgrade to vX.Y.Z`.120121## Why the engine is safe without this skill122123The engine's `_sync_game_of_cards_config` classifies every shipped124file against the on-disk copy and only writes when the destination is125absent. Diverged files are preserved unconditionally — no prompt, no126confirmation, no agent in the loop. This means:127128- A scripted upgrade in CI does not lose authored content.129- A scheduled cron `goc upgrade` does not lose authored content.130- A user running `goc upgrade` in a terminal without invoking this131 skill does not lose authored content.132133What the user loses without this skill is *informational reconciliation*134of upstream changes to the two evolving files. The local copies stay135exactly as the user left them; the upstream changes sit in the136template payload until the next time someone runs this skill (or137manually diffs `.game-of-cards/README.md` against138`<templates_root>/README.md`). That holds after the version is139already current too, because the engine's no-op run still prints140the report.141142## What this skill does NOT do143144- Does NOT re-run `goc upgrade`. The engine has already done its145 work by the time this skill is reading the report. Re-running146 would write nothing (version is now current) and print the same147 report again.148- Does NOT overwrite user-owned content stubs or workflow hooks. The149 templates are blank by design — there is nothing upstream to150 bring across, so the reconcile pass for those files is purely a151 confirmation.152- Does NOT touch the `AGENTS.md` / `CLAUDE.md` GoC marker block.153 The engine regenerates that region wholesale on every upgrade; the154 contract is "do not edit between the markers."155- Does NOT bisect or `git revert` the engine's writes. If the156 reconciliation pass produces a result the user dislikes, the user157 edits the file by hand or invokes the `create-card` skill to file158 the disagreement as a card for follow-up.159160## Cross-references161162- the `kickoff` skill — first-time setup in a fresh repo. The kickoff163 skill writes the initial `.game-of-cards/` scaffold; this skill is164 the follow-up that runs every time the user wants to pull a new165 goc version into an existing repo.166- the `card-schema` skill — frontmatter and DoD conventions the upgraded167 engine may have evolved.168- the `deck` skill — the methodology surface the regenerated AGENTS.md /169 CLAUDE.md block documents.