agentleFS
zauberzeugzauberzeug/game-of-cards/.claude/skills/upgrade/SKILL.md

upgrade

Skill7 starsChanged 6 months agoMITView on GitHub

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".

32 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use new, context and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • codebycoreySkill

    new

    Start a new change with a proposal. Use when starting a feature, creating a proposal, or beginning planned work.

    Also in 4 projects that use this

  • aegiswizardSkill

    context

    Also in 3 projects that use this

  • MicrosoftSkill

    init

    Also in 6 projects that use this

  • AnthropicSkill

    status

    Case status summary by audience — client-facing (plain language), internal (for the professor), or court-ready (formal caption format per local rules). Same facts, different framing and depth. Use when a student needs to update the client, brief the professor, or prepare a court status report.

    Also in 5 projects that use this

  • tuistSkill

    migrate

    Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.

    Also in 3 projects that use this

  • imehrSkill

    frontend

    Use when building UI components, pages, or features - guides Claude through the approved frontend stack (Next.js 15, React 19, Shadcn, Tailwind) with design-first workflow for complex UIs, enforcing patterns and quality standards

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 4 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 26 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the engine has preserved a *diverged* copy of either, the engine itself has nothing to say about whether real upstream changes need to …

    line 27
  2. Very specific:

    When the user approves, write the merged content back to .game-of-cards/<path> directly.

    line 79
  3. Distinctive:

    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 …

    line 83
  4. Very specific:

    Commit follows repo policy: If the reconciliation pass modified any files, the user typically wants those staged alongside the engine's own …

    line 112
  5. Very specific:

    Does NOT re-run goc upgrade.

    line 143
  6. Distinctive:

    Does NOT overwrite user-owned content stubs or workflow hooks.

    line 147
  7. Distinctive:

    Does NOT touch the AGENTS.md / CLAUDE.md GoC marker block.

    line 151
  8. Very specific:

    Does NOT bisect or git revert the engine's writes.

    line 154

“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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).

  2. 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.
  3. 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.
  4. 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).
  5. For files with status: unchanged — silent. The local copy already matches the template; nothing to report.
  6. 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.
  7. 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.