agentleFS
zauberzeugzauberzeug/game-of-cards/AGENTS.md

game-of-cards

AGENTS.md7 starsChanged 6 months agoMITView on GitHub

This repository is the source tree for the goc package. Run GoC commands from the repo root as uv run goc ...; do not assume a bare goc executable is available on PATH in this repo. Translate every bare goc ... example in the generated guidance below to uv run goc ... while working here. The package under goc/ is the Game of Cards CLI; the assets under .claude/, .game-of-cards/, and the <!-- BEGIN GOC --> block below are this…

  • Reads credentials
  • Deletes or force-pushes
  • Installs packages
  • Commits and pushes

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Stay on the 0.0.x line for now: Every release is a patch bump of the last 0.0.N tag (next is 0.0.N+1).

    line 52
  2. Distinctive:

    NOT in the tripwire's tracked set — humans edit its non-marker content freely.)

    line 82
  3. Distinctive:

    Every runtime hook is inert in a repo that never opted in.

    line 229
  4. Very specific:

    No venv, no uv, no first-call latency.

    line 525
  5. Distinctive:

    If it lists files you did not stage, another agent is in its commit window.

    line 545
  6. Very specific:

    When it is your turn, stage only explicit file paths with git add <path>....

    line 549
  7. Distinctive:

    When filing GoC cards in this repo:

    line 561
  8. Distinctive:

    English only: All card titles, summaries, body, and DoD items are written in English, even when the conversation that motivated the card …

    line 563
  9. Distinctive:

    No direct quotes from discussions: Do not paste verbatim quotes from meetings, transcripts, chat, or coding-coffee retrospectives into card …

    line 593
  10. Very specific:

    Only the two example names are guarded: scripts/check_card_language.py fails on either one anywhere under .game-of-cards/deck/ — …

    line 607
  11. Very specific:

    YAML format for list fields: All four bidirectional-edge list fields — advances, advanced_by, supersedes, and superseded_by — use …

    line 621
  12. Very specific:

    When the user asks for persistent work, the agent invokes the matching GoC skill — file → claim → implement → close — silently.

    line 646
  13. Distinctive:

    Always-loaded rules — one line each.

    line 660
  14. Very specific:

    README is a dashboard; log.md is the journal: When evidence changes a claim, rewrite the README section in place — never append a …

    line 663

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “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
AGENTS.md

Agent Guidelines

This file provides guidance to AI agents when working with code in this repository.

Repo-Local GoC Command

This repository is the source tree for the goc package. Run GoC commands from the repo root as uv run goc ...; do not assume a bare goc executable is available on PATH in this repo. Translate every bare goc ... example in the generated guidance below to uv run goc ... while working here.

This repo is goc — and it dogfoods itself

The package under goc/ is the Game of Cards CLI; the assets under .claude/, .game-of-cards/, and the <!-- BEGIN GOC --> block below are this repo's own consumer copy of what goc install ships. The deck under .game-of-cards/deck/ is real work for the tool itself. Behavior you observe here is the behavior shipped to consumers — there is no separate "framework" repo.

Common commands

uv sync                            # install dev environment
uv pip install -e .                # editable install into the project venv (what CI does)
uv run goc --help                  # exercise the CLI from source
uv run goc validate                # check every card's frontmatter
uv run python -m unittest discover -s tests  # run the regression suite
uv build                           # produce wheel + sdist in dist/
pre-commit run --all-files         # sync plugin assets + goc validate + card language + card YAML
python scripts/sync_plugin_assets.py --check  # verify claude-plugin/ is in sync
uv run python scripts/check_card_language.py  # cards are English and name no published internal term
uv run python scripts/check_card_frontmatter_yaml.py  # card frontmatter is valid YAML

tests/ is a stdlib unittest-based regression suite (run it locally with uv run python -m unittest discover -s tests; it also passes under pytest). .github/workflows/ci.yml is a build + console-script + regression-test + goc validate matrix on Python 3.10-3.13: the Run regression tests step (uv run python -m unittest discover -s tests) gates code correctness — and, through tests/test_wheel_package_parity.py, which runs uv build, that the wheel ships every tracked goc/ file — and the validation step gates card-frontmatter drift.

Releases publish to three registries — PyPI, npm, ClawHub — all via OIDC trusted publishing. No long-lived tokens in repo secrets; each publish target is a one-time configuration (web UI for PyPI/npm, clawhub package trusted-publisher set ... for ClawHub) that authorizes this workflow to mint short-lived publish credentials at run time.

Stay on the 0.0.x line for now. Every release is a patch bump of the last 0.0.N tag (next is 0.0.N+1); do not jump to 0.1.0 or 1.0.0 without an explicit maintainer decision. The project is deliberately pre-1.0, and the commit count between tags is not a signal to bump the minor — most of it is deck-card churn and internal engine fixes. When this policy changes, update this note.

The git tag IS the version — pyproject.toml declares dynamic = ["version"] and hatch-vcs reads git describe --tags at build time (overridden in CI by SETUPTOOLS_SCM_PRETEND_VERSION so the wheel reports the right version even before the tag is created). The five plugin manifests (openclaw-plugin/package.json + package-lock.json, claude-plugin/.claude-plugin/plugin.json, codex-plugin/.codex-plugin/plugin.json, .claude-plugin/marketplace.json), goc/__init__.py's __version__ literal, and the two dogfood self-host surfaces (.game-of-cards/deck/.goc-version, AGENTS.md's <!-- BEGIN GOC vX.Y.Z --> marker) are rewritten from the input version by scripts/release_rewrite_versions.py inside the workflow, then committed back to main by the build job as release: bump version literals to vX.Y.Z (under the github-actions[bot] identity) so consumers reading the git tree directly — plugin managers read the checked-in payloads — see the correct version, and so that tests/test_version_surfaces.py stays green on the bot's release commit. Humans never edit the publish-channel version literals; the in-job tripwire fails the build on any human commit that touches those six files, while explicitly exempting the bot's own release-bump commits so the next release dispatch reads the previous release's commit as HEAD without tripping. (AGENTS.md is NOT in the tripwire's tracked set — humans edit its non-marker content freely.)

Canonical flow:

gh workflow run release.yml -f version=X.Y.Z

That single command publishes to PyPI, npm, AND ClawHub. The workflow commits the version literals back to main and tags the rewrite commit as vX.Y.Z (the last two steps of the build job, after every consistency check passes). PyPI and npm publish from that same run. ClawHub is the exception: its OIDC trusted-publish requires the published source commit to equal the OIDC-verified sha, but a from-main dispatch mints that token for the pre-rewrite HEAD while the bundle is the bot's post-rewrite tag commit — they never match (this is why a single from-main dispatch could not publish ClawHub starting with v0.0.25). So after pushing the tag, the build job auto-dispatches release.yml again on the tag ref with clawhub_only=true (the redispatch-clawhub job). That second run is a workflow_dispatch on refs/tags/vX.Y.Z, so its OIDC sha IS the tag commit and the ClawHub publish clears the guard; it skips smoke/PyPI/npm. It is still ONE human command — the tag re-dispatch is automatic. No PAT is needed (workflow_dispatch is the documented exception to the rule that GITHUB_TOKEN-triggered events do not start new runs), and no ClawHub reconfiguration is needed (the trusted publisher pins the caller workflow filename — which stays release.yml — via the OIDC workflow_ref claim, not the ref). There is no CLAWHUB_TOKEN secret; adding one actively breaks releases (the reusable workflow's token-override path authenticates as a different publisher than the OIDC path that registered the package, and the Convex store rejects publishes with Package already exists and belongs to another publisher).

Recovery / republish on an existing tag (if a publish job transient-failed):

gh workflow run release.yml --ref vX.Y.Z                       # re-run all publishes
gh workflow run release.yml --ref vX.Y.Z -f clawhub_only=true  # ClawHub leg only

The first re-runs every publish job from the tag (PyPI/npm no-op or fail on the already-published version; ClawHub succeeds because, dispatched from the tag, the OIDC sha now equals the published commit). The second is the lean path that mirrors what redispatch-clawhub fires automatically — it skips smoke/PyPI/npm and publishes only ClawHub.

git push origin vX.Y.Z from a maintainer machine no longer triggers a release — the workflow only runs on workflow_dispatch. The closed predecessor card auto-publish-npm-and-clawhub-on-tag-push documented a two-step tag-push + workflow-dispatch flow; that conclusion was superseded by find-single-trigger-release-flow-for-all-three-registries, which verified that the workflow_dispatch event type is what unlocks OIDC publishing. That remains true, but it is not sufficient on its own: ClawHub's trusted-publish source-commit guard additionally requires the dispatched commit to equal the published commit, which is why the ClawHub leg is published by a re-dispatch on the tag (see the ClawHub paragraph above) — tracked by clawhub-publish-fails-on-every-release-until-manual-tag-redispatch.

See .github/workflows/release.yml header comment for trusted publisher configuration details.

Code architecture

The Python package is intentionally small:

  • goc/cli.py — thin console-script entry point. Restores the default SIGPIPE disposition, intercepts install / upgrade on argv[0] and routes them to standalone argparse parsers over install.py, and delegates every other invocation to engine.cli(), which builds the engine parser (_build_parser) and owns the global flags including --version. Because the two install verbs never reach that parser, they do not appear in goc --help — see the open card goc-help-omits-install-and-upgrade-subcommands. Wired as goc = "goc.cli:main" in pyproject.toml.
  • goc/engine.py — the bulk of the tool: frontmatter parser, schema loader, card loader, validator, value/edge graph, table/board renderers, and every verb except install/upgrade (new, status, done, attest, decide, publish, advance, unadvance, wait, repair-edges, move, triage, show, quality-pass, validate, migrate, migrate-list-style).
  • goc/install.py — install and upgrade commands. Reads templates via importlib.resources so it works from a wheel.
  • goc/schema.yaml — single source of truth for card frontmatter, loaded at runtime by engine.load_schema(). The card-schema skill ships a byte-identical second copy at goc/templates/skills/card-schema/schema.yaml, which goc install and the plugin mirrors copy verbatim as a sibling file beside SKILL.md, which references it rather than embedding it. No script syncs those two: a schema change is a deliberate two-file edit, and tests/test_skill_schema_yaml_parity.py fails the build when only one moves.

engine.py resolves DECK_DIR to the canonical .game-of-cards/deck/ path, with legacy deck/ fallback and dual-tree conflict detection. Running uv run goc from the repo root operates on this repo's own deck.

Templates ship as package data

goc/templates/ is bundled into the wheel and is the source of truth for everything goc install writes into a consuming repo:

Template pathInstalled to
templates/skills/<verb>/<repo>/.claude/skills/<verb>/
templates/hooks/<name>.py<repo>/.claude/hooks/<name>.py
templates/game_of_cards/<repo>/.game-of-cards/
templates/AGENTS_GOC.md, templates/CLAUDE_GOC.mdmerged into AGENTS.md / CLAUDE.md

The hook list is derived from templates/hooks/*.py at install time (see deck_hook_scripts in goc/install.py); dropping a new .py file in that directory wires it into the install copy and the parity mirrors automatically. The event mapping is not derived — it stays explicit in three hand-maintained registries, one per install path: GOC_CLAUDE_HOOKS (goc/install.py, the vendored --local-skills path) plus claude-plugin/hooks/hooks.json and codex-plugin/hooks/hooks.json (the plugin path, which is the default). They stay hand-written because a command is not derivable from a script name — Codex carries per-event statusMessage strings and a version-fallback shell wrapper, Claude a different root variable. goc validate covers all three, on both halves of a registration — which scripts, and which event each one fires on. validate_hook_registration checks GOC_CLAUDE_HOOKS against templates/hooks/, and validate_plugin_hook_registration checks each payload's hooks.json against the scripts that payload ships — in both directions, so a script nothing registers (installed but never invoked) and a registration naming a script the payload no longer ships (fails on every fire) each turn the build red. It then compares the event each payload binds a script to against GOC_CLAUDE_HOOKS as the reference mapping (both read it through one claude_hook_bindings() walk), so the session primer moved to Stop or the prompt router to SessionStart turns the build red too — that drift registers the right scripts and keeps exiting 0, so nothing else would notice. The comparison assumes the hosts share an event vocabulary, true of all three today; a host that renames an event needs a per-host alias map there. The plugin check runs only in the goc source tree, recognized by goc/templates/ at the repo root (the tree the payloads are built from) rather than by a payload folder, which a consuming repo may have for its own plugin. It and validate_plugin_mirror_parity, which shares the gate, are therefore inert in consuming repos. OpenClaw is out of scope for the hook check: it reimplements the deck hooks in TypeScript inside openclaw-plugin/index.ts and ships no hooks.json.

Every runtime hook is inert in a repo that never opted in. The plugin registers its hooks globally, so they run in every repo the user opens; each resolves the project dir through its own _find_project_dir mirror — all three pinned to engine._resolve_deck_root by tests/test_project_root_from_subdirectory.py — and acts only where that root opted in: deck_session_start.py and deck_prompt_router.py on a .game-of-cards/deck/ (or the legacy deck/), pattern_generalization_check.py on its explicit switch in .game-of-cards/config.yaml. goc install, run by Skill(kickoff), remains the only opt-in path (goc new refuses without a deck). A hook that acts on the prompt text alone installs the methodology as a side effect of phrasing (runtime-hooks-fire-in-repos-that-never-opted-in). The OpenClaw port carries the guard too. Its before_prompt_build handler appends the deck-first reminder only where the session's project dir holds a deck. That is the dir its session_start reads, checked as-is with no ancestor walk, and tests/test_openclaw_prompt_hook.py pins the guard. None of the OpenClaw handlers delivers anything on the SDK version the plugin pins yet, because they read guessed context shapes (openclaw-plugin-hooks-never-deliver-their-reminders-on-a-real-host).

Skill and hook files have two copies — edit the template, sync handles the rest

Because this repo dogfoods itself, every file under .claude/skills/, .claude/hooks/, and .codex/skills/ is a consumer copy of the corresponding file under goc/templates/. Always edit goc/templates/... — the sync-plugin-assets pre-commit hook regenerates those mirrors from the templates on every commit and stages them automatically, the same way it already does for claude-plugin/, codex-plugin/, and openclaw-plugin/. CI runs python scripts/sync_plugin_assets.py --check and fails the build on any drift, so editing only .claude/skills/... or .codex/skills/... is now CI-detectable (it gets overwritten by the next pre-commit pass).

Two kinds of file sit outside that auto-sync, for two different reasons. The .game-of-cards/ content stubs (project-local deck README, config) are user-owned — they're meant to be customized per repo, so nothing regenerates them. .claude/settings.json is the Claude Code hook-registration manifest, and it's excluded because it is a merge target rather than a mirrored file: goc install / goc upgrade reconcile the GOC_CLAUDE_HOOKS entries (goc/install.py) into whatever the repo already has, and the plugin-mode cleanup strips those same entries back out. So its ownership is shared — the hooks entries whose command matches GOC_CLAUDE_HOOKS are goc-owned (change them in goc/install.py, not in .claude/settings.json); any other key the repo adds is yours. The file is not one of the three hook registries goc validate covers (above), so a hand edit that drops or repoints a goc-owned registration passes goc validate. The merge is what repairs it: a vendored-mode goc upgrade re-adds every GOC_CLAUDE_HOOKS entry the file lacks, even at the same version, but a repointed entry no longer matches, so it stays behind beside the re-added one (goc-upgrade-leaves-stale-prior-version-hook-registrations-in-claude-settings). goc writes no permissions block there — the Bash(goc:*) grant is a human step, documented in Skill(claude-kickoff).

The <!-- BEGIN GOC vX.Y.Z --> marker in AGENTS.md and the .goc-version sentinel are rewritten by the release workflow (see release section above), so they're also out of scope for the pre-commit sync.

.game-of-cards/ ownership model and goc upgrade contract

Per-file ownership determines how each file under .game-of-cards/ behaves on goc upgrade:

OwnershipFilesEngine behavior on upgrade
user-ownedthe 6 content stubs (canonical-tags.md, domain-vocabulary.md, domain-examples.md, file-path-map.md, tooling-conventions.md, documentation-conventions.md) + hooks/*.mdabsent → scaffold blank stub; identical → no-op; diverged → preserve (never overwrite)
evolvingREADME.md, config.yamlsame engine behavior (never overwrite); the Skill(upgrade) reconciliation pass offers a 2-way LLM merge of upstream changes into the local copy
goc-ownedthe marker-bounded block in AGENTS.md / CLAUDE.md / CLAUDE.local.mdregenerated wholesale via _append_marker_block (the contract is "do not edit between the markers")

goc upgrade's safety is unconditional — the engine never destroys authored content under .game-of-cards/, regardless of whether an agent is present. The new Skill(upgrade) runs the engine and then reads the engine's machine-readable divergence report (printed after the sentinel GoC project-state divergence report (JSON):) to drive LLM reconciliation of the evolving files where real upstream changes need a judgment call. The engine prints that report on every run except an effecting --dry-run (which prints its plan instead), the already at goc X — nothing to do. short-circuit included: a diverged evolving file is preserved, a no-op to the write plan, so a report gated on writes would vanish whenever the version is already current — the usual state by the time the skill runs (upgrade-skill-cannot-reach-the-divergence-report-once-the-version-is-current). Headless / CI / scripted upgrades (e.g., the --keep-local-skills path) preserve content with no agent in the loop.

"already at goc X — nothing to do" is derived, never enumerated. upgrade() computes _plan_upgrade_writes first and short-circuits only when no planned write is effecting — each write's action comes from asking its own executor, in probe=True mode, whether it would change the file. So the preview and the real run answer "is there work?" from one computation, and a repair added to upgrade() is covered the moment it is planned. Do not reintroduce a pending_* allowlist term for a new write; that per-site register is what let four repairs go unreachable at the same version (goc-upgrade-cannot-repair-a-damaged-install-at-the-same-version). The plan is not writes only: a repair that deletes has no template to be derived from, so _plan_skill_prunes asks _sync_skill_tree(probe=True) which destination files its wipe-and-recopy would remove and plans one skill-prune entry per path — that is the shape to copy for the next deletion, not a new term beside the guard (upgrade-write-plan-omits-the-skill-tree-prune-from-dry-run-and-no-op-verdict). The three remaining terms next to the plan cover work the plan does not model: the interactive vendored-cleanup prompt (offered when _strip_claude_vendored_harness in probe=True mode finds GoC content to remove), the legacy-briefing strip, and the skills_source pin — the one surviving pending_* term that does gate a write, kept honest by asking _write_skills_source in probe=True mode rather than restating what it would do, and a holdover rather than a shape to copy.

skills_source — which install path owns .claude/skills/

.game-of-cards/config.yaml holds a skills_source key, written by goc install and read by both goc upgrade and goc validate. It is the per-repo signal that says where Claude Code's GoC skills come from:

ValueMeaning
pluginSkills come from the Claude Code plugin payload (${CLAUDE_PLUGIN_ROOT}/skills/). goc upgrade does not write .claude/skills/, .claude/hooks/, or GoC entries in .claude/settings.json. goc validate skips the skill-dir parity check. Written when goc install is run without --local-skills.
vendoredSkills are checked into source control under .claude/skills/. goc upgrade refreshes those templates in place; goc validate enforces parity. Written when goc install --local-skills is used.
auto / unsetThe engine detects whether a Claude Code GoC plugin payload is present on the host (looks under $CLAUDE_PLUGIN_ROOT and ~/.claude/plugins). Plugin found -> behave as plugin. Plugin not found -> behave as vendored. This is the fallback for legacy installs that predate the key.

Switching modes is a manual config edit. To move a vendored repo to plugin mode: edit skills_source: plugin in .game-of-cards/config.yaml, then goc upgrade — which prompts for cleanup whenever GoC-owned leftovers remain: GoC-named skill directories, the _goc-bootstrap.sh shim, GoC hook scripts, or GoC entries in .claude/settings.json. The detection keys on that GoC content, not on whether .claude/skills/ exists: it asks the cleanup itself in probe mode, so a .claude/skills/ holding only the repo's own skills is not re-offered on every later upgrade, and GoC hooks left without one still are. The cleanup only removes that GoC content; non-GoC skills in .claude/skills/ are preserved. Declining the cleanup is a strict no-op (the buggy "decline re-vendors and deletes user skills" path that motivated this design is gone).

Bootstrap: .claude/skills/_goc-bootstrap.sh lives under .claude/skills/ but is sourced from goc/templates/bootstrap/_goc-bootstrap.sh (not goc/templates/skills/). The sync script handles this via a preserve_files set on the skills dir-sync so the bootstrap isn't deleted as "not in src", with a separate single-file sync pair keeping its contents current.

Plugin assets are auto-synced — edit only the template

The Claude Code plugin payload at claude-plugin/ ships skills, hook scripts, and a copy of the entire goc/ package plus a bin/goc wrapper. Because Claude Code's marketplace install only extracts the source: ./claude-plugin subtree, those assets must be real files (not symlinks pointing outside the subtree, which silently disappear on consumer install). They are byte-for-byte copies of the source-of-truth files:

Plugin pathSource-of-truth
claude-plugin/skills/goc/templates/skills/
claude-plugin/hooks/deck_prompt_router.pygoc/templates/hooks/deck_prompt_router.py
claude-plugin/hooks/deck_session_start.pygoc/templates/hooks/deck_session_start.py
claude-plugin/hooks/pattern_generalization_check.pygoc/templates/hooks/pattern_generalization_check.py
claude-plugin/goc/goc/ (entire package — engine, schema, templates)

The Codex plugin payload at codex-plugin/ follows the same real-file principle, with Codex-specific frontmatter normalization for skills:

Plugin pathSource-of-truth
codex-plugin/skills/goc/templates/skills/ filtered for Codex
codex-plugin/hooks/deck_prompt_router.pygoc/templates/hooks/deck_prompt_router.py
codex-plugin/hooks/deck_session_start.pygoc/templates/hooks/deck_session_start.py
codex-plugin/hooks/pattern_generalization_check.pygoc/templates/hooks/pattern_generalization_check.py
codex-plugin/goc/goc/ (entire package — engine, schema, templates)

The flat claude-plugin/skills/ and claude-plugin/hooks/ paths exist so Claude Code's plugin runtime auto-discovers them at the layout it expects. The nested claude-plugin/goc/templates/... mirrors the rest of the package (engine, schema, agents, game_of_cards templates, hook templates — the bundled engine derives its hook list from templates/hooks/*.py, so those ARE included) but deliberately omits templates/skills/: the bundled engine refuses --local-skills on goc install and --keep-local-skills on goc upgrade (see _is_plugin_context in goc/install.py), so the skill templates are never read from inside the plugin payload. The one thing the engine still needs from them, the names of GoC's skills (so the vendored→plugin cleanup in goc upgrade can tell GoC's skill directories from a repo's own), it reads from the payload's flat skills/ tree beside its goc/ (_goc_skill_names in goc/install.py). To vendor skills into source control, install via pipx install game-of-cards instead — that path keeps the full template tree.

Do not edit claude-plugin/ or codex-plugin/ directly. The sync-plugin-assets pre-commit hook (scripts/sync_plugin_assets.py) auto-regenerates those files from the source-of-truth on every commit and stages the changes automatically. CI runs python scripts/sync_plugin_assets.py --check and fails the build on any drift. Plugin-specific files that are NOT auto-synced: claude-plugin/hooks/hooks.json, claude-plugin/bin/goc, claude-plugin/settings.json, claude-plugin/README.md, codex-plugin/.codex-plugin/plugin.json, codex-plugin/hooks/hooks.json, codex-plugin/bin/goc, codex-plugin/README.md, and .agents/plugins/marketplace.json.

The mirror trees (claude-plugin/goc/**, codex-plugin/goc/**, openclaw-plugin/goc/**, claude-plugin/skills/**, codex-plugin/skills/**, .claude/skills/**, .codex/skills/**, claude-plugin/hooks/**, codex-plugin/hooks/**, .claude/hooks/**) and the committed esbuild output (openclaw-plugin/dist/**) are marked linguist-generated=true in .gitattributes — with =false carve-outs for the authored files living inside those trees (the two hand-maintained hooks.json files and the repo-local .claude/skills/tune-cadence/ dev skill) — so GitHub collapses them in PR review by default — reviewers see each authored change once in its source-of-truth, not N times across the mirrors. When a commit's diff is mostly the mechanical mirror regeneration, prefix the subject with [sync auto] so local readers (git show, log skimming) can skip it with the same confidence the GitHub UI provides; reserve [sync auto] for commits where the only authored change is the templates the mirrors were regenerated from.

OpenClaw plugin payload — same engine, different host shape

A second plugin payload lives at openclaw-plugin/ for OpenClaw, the Node-based personal AI assistant. OpenClaw plugins have a fundamentally different shape from Claude Code's:

  • The plugin entry is TypeScript, not file-static. openclaw-plugin/index.ts exports a definePluginEntry({ register(api) }) callback that registers capabilities programmatically.
  • OpenClaw has no auto-PATH-prepend for plugin bin/ directories (verified via spike on the provide-openclaw-plugin-for-skills-and-hooks card). So goc is exposed as a registered tool via api.registerTool('goc', ...), not a shell binary on PATH. The tool handler runs the vendored engine through its launcher file (python3 <plugin>/goc/_launch.py, built by gocCommand), never with -m, so the agent-supplied cwd cannot put a project's own goc/ package or a stdlib-named module in its place.
  • The three GoC lifecycle hooks (session-start active-card reminder, deck-first prompt-injection, pattern-generalization self-assessment) are TypeScript ports registered via api.on('session_start' | ...). Claude Code's Python hook scripts under goc/templates/hooks/ are used only by the --local-skills install path on Claude — the OpenClaw plugin reimplements them in TS inside index.ts.
Plugin pathSource-of-truth
openclaw-plugin/goc/goc/ (engine, schema, templates — auto-synced)
openclaw-plugin/skills/<name>/SKILL.mdgoc/templates/skills/<name>/SKILL.md (hand-ported with invocation-neutral edits via scripts/port_skills_to_openclaw.py)
openclaw-plugin/skills/<name>/<sibling>goc/templates/skills/<name>/<sibling> (any non-SKILL.md file in the source skill dir — copied verbatim, no host-neutral rewrite, __pycache__/*.pyc excluded mirroring goc/install._iter_skill_assets)

The auto-synced engine pair (goc -> openclaw-plugin/goc) is enforced by the same byte-for-byte tripwire as the Claude one. Skills are NOT auto-synced into the commit — they go through the porting script, whose output is reviewed and committed by hand (unlike the claude/codex mirrors, the porter applies non-trivial normalization worth eyeballing). The same script handles sibling asset files (e.g. card-schema/schema.yaml) by verbatim copy, matching the full-tree walk the other four plugin consumers (goc install, the claude/codex sync, the in-repo .claude/skills/ and .codex/skills/ mirrors) already do. To re-port (e.g., after editing a source skill or adding a sibling asset), re-run python3 scripts/port_skills_to_openclaw.py and review the diff.

The port is deterministic, so a drift guard keeps it honest even though it is not auto-staged: scripts/port_skills_to_openclaw.py --check re-ports into memory and fails on any difference from the committed openclaw-plugin/skills/. The check covers SKILL.md content, sibling assets (missing, extra, or content-mismatched), and orphaned ported skill dirs symmetrically. The same comparison is enforced in CI by tests/test_plugin_mirror_parity.py (it calls the porter's drifted_skills() from the regression-test suite), so a template edit or sibling addition that is not followed by a re-port turns the build red instead of rotting silently. The guard lives in a test, not a ci.yml step, because the autonomous bot's GITHUB_TOKEN cannot edit files under .github/workflows/. The porter is idempotent — re-running --check immediately after a re-port is always green.

OpenClaw-plugin-specific files that are NOT auto-synced: openclaw-plugin/index.ts, openclaw-plugin/package.json, openclaw-plugin/openclaw.plugin.json, openclaw-plugin/tsconfig.json, openclaw-plugin/README.md, openclaw-plugin/skills/.

Plugin runs goc from a vendored engine — Python 3.10+ is the only host prerequisite

claude-plugin/bin/goc is a shell wrapper that invokes the bundled engine by the path of its launcher file (goc/_launch.py), with PYTHONPATH pointing at the plugin root. It deliberately avoids python3 -m goc.cli: -m puts the working directory first on sys.path, so a consumer repo's own goc/ package or a module named after one the engine imports would run instead (card plugin-goc-wrapper-lets-repo-local-python-replace-the-bundled-engine). The engine re-invokes itself the same way (goc.engine._goc_command). Claude Code auto-prepends the plugin's bin/ directory to the Bash tool's PATH while the plugin is enabled, so skill bodies keep calling plain goc <verb> and the wrapper transparently runs the vendored engine. No venv, no uv, no first-call latency.

The traditional pipx install game-of-cards recipe remains documented as the fallback for environments that want a globally-installed goc binary outside of the plugin.

Marker-bounded merge for AGENTS.md / CLAUDE.md

install._append_marker_block rewrites only the content between <!-- BEGIN GOC vX.Y.Z --> and <!-- END GOC -->. Content above or below those markers is preserved across goc install / goc upgrade. This section is therefore safe to extend; the block below it is generated from goc/templates/AGENTS_GOC.md and round-trips cleanly. In this repo, CLAUDE.md intentionally contains only @AGENTS.md so Claude Code loads this shared file without duplicating the guidance.

Parallel-Agent Commit Safety

Multiple agents may work on local main at the same time. Treat Git's index as shared state: before staging, run git diff --cached --name-only. If it lists files you did not stage, another agent is in its commit window; wait with a short backoff or surface the collision instead of pushing through.

When it is your turn, stage only explicit file paths with git add <path>.... Do not use git add ., git add -A, directory-wide adds, git stash, or destructive cleanup (git restore, git checkout --, git reset --hard, git clean) to isolate your work; those operations can move or discard another agent's WIP. Verify the staged set with git diff --cached --stat, then commit with an explicit pathspec: git commit -- <path>.... The pathspec is the last guard against accidentally bundling unrelated staged files. For high-risk shared-main commits, prepare the commit in a temporary worktree instead.

Card authoring rules

When filing GoC cards in this repo:

  • English only. All card titles, summaries, body, and DoD items are written in English, even when the conversation that motivated the card was in another language. Cards are read cold by future agents and contributors who may not share the original language. Guarded by scripts/check_card_language.py, which runs as the card-language pre-commit hook and from tests/test_card_authoring_rules.py in CI. It scans title, summary and definition_of_done — not bodies, which legitimately quote non-English identifiers and error strings — and it is precision-first: a slug built entirely from cognates can still slip through. The rule is this repo's convention, not goc semantics, so the guard is deliberately repo-local and ships to no consumer.
  • Frontmatter must be valid YAML, not merely yaml-lite-parseable. goc reads cards through goc/_vendor/yaml_lite.py, scoped on purpose as a superset of what emit_frontmatter produces, and validate_card checks parsed field values rather than the block's YAML legality — so a hand-edited card can pass goc validate while a strict parser refuses it. Quote any scalar holding : or a TAB, or opening with a YAML indicator — the spec's closed c-indicator list, held once in goc.engine as _YAML_INDICATORS and imported by the guard rather than restated (three of them, - ? :, bind only before a space or alone). Re-emitting the card through any goc verb is the fix: the emitter consults the same set, so it quotes every shape the guard flags and preserves a quote you added by hand. Guarded by scripts/check_card_frontmatter_yaml.py, which runs as the card-frontmatter-yaml pre-commit hook and from tests/test_card_frontmatter_yaml.py in CI. Repo-local for the same reason: goc validate ships to consumers and cannot take a YAML dependency back.
  • No direct quotes from discussions. Do not paste verbatim quotes from meetings, transcripts, chat, or coding-coffee retrospectives into card bodies. Synthesize the technical content into the card's own voice. Quotes age poorly, attribute work to individuals who may not want to be cited, and pull conversation context into a permanent artefact where it does not belong.
  • No references to internal events or projects by name. Specifically: do not name internal meetings (e.g. coding coffee), internal projects (e.g. Zoe), or individual participants in card bodies. State the technical motivation directly. If a card needs context that only an internal source provides, summarize the technical fact, not its origin: "a downstream consumer repository" for where evidence came from, "the maintainer" for who decided or signed off. Only the two example names are guarded: scripts/check_card_language.py fails on either one anywhere under .game-of-cards/deck/ — frontmatter, body, log.md, sibling files — except a README's worker: value, which may name a machine. A guard can list no other name: its list would publish what the rule protects, while this file publishes these two already. Individual names, other internal names and the quoting rule above are unguarded and hold only as far as the author's care does. The latest sweep, on 2026-11-09, rephrased the example project on 16 lines, individual attributions on 62 and three discussion quotes — all in cards an earlier audit had called clean — so treat the unguarded rules as unaudited. Mechanizing the quoting rule needs a decision nobody has made yet: permitted code/doc quoting is hard to tell from forbidden discussion quoting.
  • YAML format for list fields: All four bidirectional-edge list fields — advances, advanced_by, supersedes, and superseded_by — use block-style (one - item per line) when non-empty; empty lists stay as []. The tags field uses inline flow style. The emitter enforces this automatically; when editing frontmatter by hand, follow the same convention to avoid merge conflicts.
  • worker field: Optional free-form identifier naming who should or does work on a card. Use a flat string for a single identifier (worker: rodja), or a mapping when branch context is known (worker: {who: rodja, where: feature/foo}). The flat form is sugar for {who: <value>}. The value is unregistered — use a person slug, a machine name, or a capability tag (e.g. gpu-required, human, rendering-expert). The field persists after close as a historical record; goc status <title> active auto-populates it at claim time. Filter with goc --worker <X> or set GOC_WORKER env var for runner-specific queue views.
<!-- BEGIN GOC v0.0.28 -->

Game of Cards — methodology runtime

This repo uses Game of Cards: tasks are directories under .game-of-cards/deck/ with frontmatter, body, and a Definition-of-Done. The CLI is goc (goc --help).

When the user asks for persistent work, the agent invokes the matching GoC skill — file → claim → implement → close — silently. The card records intent; the implementation lands. The user sees goc (queue) or goc --board (kanban) only if they ask.

Skills carry the methodology (loaded on demand — read the skill before improvising):

  • deck — overview, operating modes, Andon cord, daily verbs.
  • card-schema — frontmatter, DoD, status enums, YAML conventions.
  • create-card / advance-card / finish-card — file, claim, close.
  • pull-card / next-card / scan-deck — queue and browse.
  • kickoff — first-time setup in a fresh repo.

Always-loaded rules — one line each; the named skill carries the full contract:

  • README is a dashboard; log.md is the journal. When evidence changes a claim, rewrite the README section in place — never append a correction below the stale claim. Skill(card-schema) § "What goes where".
  • Closure is not frozenness. Post-close evidence → file a new card and amend the closed one with a forward pointer. Skill(finish-card) § "After closure".
  • Three-axis stuck model. Progress status, derived dependency-readiness (⏳, advisory), and the waiting_on impediment overlay (goc wait) are independent axes. Skill(card-schema) § "Three-axis stuck model".
  • The deck is scheduler AND record. Relationship edges are first-class even on closed cards; supersession is a typed link. Skill(card-schema) § "Deck as scheduler vs deck as record".

Project-local extensions live under .game-of-cards/; see its README.md if present. The <!-- BEGIN GOC --> markers above are the discovery signal that this repo uses GoC.

<!-- END GOC -->

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.