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
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- site/llms.txtllms.txt
- advance-cardSkill
- audit-deckSkill
- card-schemaSkill
- claude-kickoffSkill
- create-cardSkill
- decide-cardSkill
- deckSkill
- finish-cardSkill
- kickoffSkill
- next-cardSkill
- pull-cardSkill
- refine-deckSkill
- retrospectiveSkill
- scan-deckSkill
- standupSkill
- tune-cadenceSkill
- upgradeSkill
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
- Very specific: line 52
Stay on the
0.0.xline for now: Every release is a patch bump of the last 0.0.N tag (next is 0.0.N+1). - Distinctive: line 82
NOT in the tripwire's tracked set — humans edit its non-marker content freely.)
- Distinctive: line 229
Every runtime hook is inert in a repo that never opted in.
- Very specific: line 525
No venv, no uv, no first-call latency.
- Distinctive: line 545
If it lists files you did not stage, another agent is in its commit window.
- Very specific: line 549
When it is your turn, stage only explicit file paths with git add <path>....
- Distinctive: line 561
When filing GoC cards in this repo:
- Distinctive: line 563
English only: All card titles, summaries, body, and DoD items are written in English, even when the conversation that motivated the card …
- Distinctive: line 593
No direct quotes from discussions: Do not paste verbatim quotes from meetings, transcripts, chat, or coding-coffee retrospectives into card …
- Very specific: line 607
Only the two example names are guarded: scripts/check_card_language.py fails on either one anywhere under .game-of-cards/deck/ — …
- Very specific: line 621
YAML format for list fields: All four bidirectional-edge list fields — advances, advanced_by, supersedes, and superseded_by — use …
- Very specific: line 646
When the user asks for persistent work, the agent invokes the matching GoC skill — file → claim → implement → close — silently.
- Distinctive: line 660
Always-loaded rules — one line each.
- Very specific: line 663
README is a dashboard; log.md is the journal: When evidence changes a claim, rewrite the README section in place — never append a …
≈ “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.
Files
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 YAMLtests/ 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.ZThat 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 onlyThe 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, interceptsinstall/upgradeonargv[0]and routes them to standalone argparse parsers overinstall.py, and delegates every other invocation toengine.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 ingoc --help— see the open cardgoc-help-omits-install-and-upgrade-subcommands. Wired asgoc = "goc.cli:main"inpyproject.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—installandupgradecommands. Reads templates viaimportlib.resourcesso it works from a wheel.goc/schema.yaml— single source of truth for card frontmatter, loaded at runtime byengine.load_schema(). Thecard-schemaskill ships a byte-identical second copy atgoc/templates/skills/card-schema/schema.yaml, whichgoc installand the plugin mirrors copy verbatim as a sibling file besideSKILL.md, which references it rather than embedding it. No script syncs those two: a schema change is a deliberate two-file edit, andtests/test_skill_schema_yaml_parity.pyfails 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 path | Installed 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.md | merged 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:
| Ownership | Files | Engine behavior on upgrade |
| user-owned | the 6 content stubs (canonical-tags.md, domain-vocabulary.md, domain-examples.md, file-path-map.md, tooling-conventions.md, documentation-conventions.md) + hooks/*.md | absent → scaffold blank stub; identical → no-op; diverged → preserve (never overwrite) |
| evolving | README.md, config.yaml | same engine behavior (never overwrite); the Skill(upgrade) reconciliation pass offers a 2-way LLM merge of upstream changes into the local copy |
| goc-owned | the marker-bounded block in AGENTS.md / CLAUDE.md / CLAUDE.local.md | regenerated 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:
| Value | Meaning |
plugin | Skills 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. |
vendored | Skills 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 / unset | The 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 path | Source-of-truth |
claude-plugin/skills/ | goc/templates/skills/ |
claude-plugin/hooks/deck_prompt_router.py | goc/templates/hooks/deck_prompt_router.py |
claude-plugin/hooks/deck_session_start.py | goc/templates/hooks/deck_session_start.py |
claude-plugin/hooks/pattern_generalization_check.py | goc/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 path | Source-of-truth |
codex-plugin/skills/ | goc/templates/skills/ filtered for Codex |
codex-plugin/hooks/deck_prompt_router.py | goc/templates/hooks/deck_prompt_router.py |
codex-plugin/hooks/deck_session_start.py | goc/templates/hooks/deck_session_start.py |
codex-plugin/hooks/pattern_generalization_check.py | goc/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.tsexports adefinePluginEntry({ register(api) })callback that registers capabilities programmatically. - OpenClaw has no auto-PATH-prepend for plugin
bin/directories (verified via spike on theprovide-openclaw-plugin-for-skills-and-hookscard). Sogocis exposed as a registered tool viaapi.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 bygocCommand), never with-m, so the agent-supplied cwd cannot put a project's owngoc/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 undergoc/templates/hooks/are used only by the--local-skillsinstall path on Claude — the OpenClaw plugin reimplements them in TS insideindex.ts.
| Plugin path | Source-of-truth |
openclaw-plugin/goc/ | goc/ (engine, schema, templates — auto-synced) |
openclaw-plugin/skills/<name>/SKILL.md | goc/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 thecard-languagepre-commit hook and fromtests/test_card_authoring_rules.pyin CI. It scanstitle,summaryanddefinition_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 whatemit_frontmatterproduces, andvalidate_cardchecks parsed field values rather than the block's YAML legality — so a hand-edited card can passgoc validatewhile a strict parser refuses it. Quote any scalar holding:or a TAB, or opening with a YAML indicator — the spec's closedc-indicatorlist, held once ingoc.engineas_YAML_INDICATORSand 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 byscripts/check_card_frontmatter_yaml.py, which runs as thecard-frontmatter-yamlpre-commit hook and fromtests/test_card_frontmatter_yaml.pyin CI. Repo-local for the same reason:goc validateships 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.pyfails on either one anywhere under.game-of-cards/deck/— frontmatter, body,log.md, sibling files — except a README'sworker: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, andsuperseded_by— use block-style (one- itemper line) when non-empty; empty lists stay as[]. Thetagsfield uses inline flow style. The emitter enforces this automatically; when editing frontmatter by hand, follow the same convention to avoid merge conflicts. workerfield: 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> activeauto-populates it at claim time. Filter withgoc --worker <X>or setGOC_WORKERenv 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 thewaiting_onimpediment 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 -->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
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.

