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

deck

Skill7 starsChanged 6 months agoMITView on GitHub

Front door for the deck — the operating substrate for ALL persistent work. AUTO-INVOKE when the user references the deck/methodology/workflow, or at session start as a reminder that persistent work flows through Skill(create-card) → Skill(advance-card) → Skill(finish-card).

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 1 is distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Autonomous mode: No human is steering. Skill(pull-card) runs on a loop or schedule, draining the human_gate: none queue.

    line 39
  2. Distinctive:

    Session mode (silent runtime): When the user asks for persistent work — "rename the button to Export", "add a CSV export", "fix the auth …

    line 55
  3. Very specific:

    Check the deck — does a card already cover this?

    line 59
  4. Very specific:

    If not, file a card: goc new <kebab-title> and edit the body.

    line 60
  5. Very specific:

    Autonomous mode: Before recommending or claiming new work, agents check goc --status active and treat listed cards as already-claimed soft …

    line 70
  6. Very specific:

    Andon-cord path: When a human asks "what's up?" / "where do you need me?", surface parked cards (oldest-first, with ## Decision required …

    line 77
  7. Very specific:

    Run goc --help for the full verb list.

    line 97

“Common” is measured: kept by at least 6 in 10 of the 7 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 references the deck, the methodology, or the workflow — or at session start as a reminder that every user request producing persistent work must flow through Skill(create-card) → Skill(advance-card) → Skill(finish-card). XP-style story cards on a kanban board, designed for AI-agent collaborators.

The Deck

deck/ is the project's work-tracking surface. Each subdirectory is one card: a unit of work — bug, story, epic, idea, derivation gap, doc-drift catch — with frontmatter-driven status on a kanban board.

The deck is the runtime of the human's intent, not a ceremony they opt into: rigor (machine-checkable DoDs, audit-trail commits, supersession chains) is separated from visibility (zero by default). The user sees the code, not the bookkeeping, unless they ask.

Background and rationale live in reference.md — a sibling file in this skill's directory. Read the named section only when the situation actually calls for it:

Situationreference.md section
Why XP/Scrum/Kanban discipline is load-bearing for agent swarmsHeritage & philosophy
Why card operations stay invisible; full operating-mode proseGame of Cards as the runtime
Why the methodology is named Game of CardsThe worldview
New evidence after a card closedClosure is not frozenness
How status / waiting_on / human_gate composeStatus, overlay, and gate are orthogonal axes
Pre-2026-05-01 placeholder DoDs; v1 find-todo/work-todo namesMigration legacy

Three operating modes

  • Session mode. A human is talking. Claude runs the card pipeline silently while answering; card operations are NEVER announced unless the user explicitly asks to see the deck.
  • Autonomous mode. No human is steering. Skill(pull-card) runs on a loop or schedule, draining the human_gate: none queue; Skill(audit-deck) keeps the queue fed on a slower cadence.
  • Andon-cord mode. A human is unblocking the line: pull-card parked a card behind a raised gate; Skill(scan-deck) surfaces parked cards, Skill(decide-card) records the answer and lowers the gate, the next pull resumes the work.

Multiple sessions work cards in parallel. status: active is the soft lock, but by default a claim stays in your clone, so two clones can both claim one card; workflow.claim_push: true pushes the claim and refuses a later conflicting one (reference.md § Game of Cards as the runtime).

What this looks like in practice

Session mode (silent runtime). When the user asks for persistent work — "rename the button to Export", "add a CSV export", "fix the auth bug" — run the GoC pipeline silently:

  1. Check the deck — does a card already cover this? (goc --tag <topic>)
  2. If not, file a card: goc new <kebab-title> and edit the body.
  3. Claim it: goc status <title> active.
  4. Implement.
  5. Close: goc done <title>, then commit the work and closure.

Card operations are NEVER announced — the user sees the code, not the bookkeeping. No-card exceptions (zero work, no card): exploration ("explain X", "why is Y this way?"), one-shot tooling ("git status", "rebase this"), course-corrections inside an active card.

Autonomous mode. Before recommending or claiming new work, agents check goc --status active and treat listed cards as already-claimed soft locks. The pull principle is what makes this safe: work isn't pushed at agents on a timer; agents pull on their own terms, filtered to gate=none. The human steers by curating WHAT'S in the queue and at what gate.

Andon-cord path. When a human asks "what's up?" / "where do you need me?", surface parked cards (oldest-first, with ## Decision required body section preview). Decision recorded → gate lowered with goc decide <title> --decision "..." --because "..." → next pull-card claims and implements per the recorded decision.

Daily CLI verbs

VerbWhat it does
gocShow the open queue (value-sorted).
goc --boardMulti-column kanban view. A ⏳ after an open card's [contribution] marker flags any of three signals: human_gate != none (parked for a human — not pullable), an active impediment overlay (waiting_on / future waiting_until — not pullable), or an advisory derived dependency-block (a non-terminal advanced_by prereq — still pullable, just flagged as "has an open upstream"). Only the first two hide a card from pull-card / next-card / goc --ready; a dependency-block does not. So ⏳ ⇏ unpullable — check the cause.
goc --closed-since 7dRecently closed cards (any terminal status).
goc new <title>Scaffold a new card under .game-of-cards/deck/<title>/.
goc status <title> <state>Flip status (open/active/disproved/superseded).
goc wait <title> --reason <r> [--until <date>]Set the impediment overlay for exogenous waits; --clear to drop it.
goc done <title>Close + DoD enforcement (no auto-commit).
goc decide <title> --decision X --because YLower gate from decision/session → none.
goc validateValidate every card's frontmatter (pre-commit-friendly).

Run goc --help for the full verb list. Schema and enum constraints surface in goc validate error messages. Project-local tag extensions live in .game-of-cards/canonical-tags.md.

The deck layout

deck/
  log.md                    # deck-level journal (sprint notes, schema bumps)
  <title>/                  # one dir per card; never moves on state change
    README.md               # frontmatter + dashboard body — latest knowledge + current state
    log.md                  # append-only journal — history, details, decisions, flow
    reproduce.py            # OPTIONAL — declared in DoD when present
    [other validation scripts]

One title, one directory, forever. Status changes mutate frontmatter, not paths.

Two files, two edit disciplines: the README is the dashboard (rewritten in place as understanding evolves so a cold reader sees only what is true now); log.md is the append-only journal (history, details, decisions, and flow preserved verbatim, never rewritten). See Skill(card-schema)'s "What goes where" subsection for the routing rule.

Lifecycle

   open ──→ active ──→ done (terminal, DoD-100% required)
    │
    ├──→ disproved (terminal; body documents rebuttal)
    └──→ superseded (terminal; typed `superseded_by` → successor,
                     rationale appended to log.md)

open is the queue. active claims the work. done, disproved, and superseded are all terminal — none deletes the directory; the forensic record stays.

A card that is temporarily not workable does not move to a separate status; the three-axis model expresses it as either derived dependency-readiness (an advances prereq is still open and shows as "awaiting" in the queue, advisory only) or the stored impediment overlay (waiting_on + optional waiting_until, set via goc wait, hides the card from the ready queue until cleared or the date elapses). See Skill(card-schema) "Three-axis 'stuck' model" for the full contract. Closed cards stay amendable, and the three axes are orthogonal — reference.md § Closure is not frozenness and § Status, overlay, and gate are orthogonal axes.

The action skills

One skill per job; compose, don't bundle.

  • Skill(scan-deck) — browse the deck. Triage default surfaces parked cards (gate ≠ none); also filtered queues, kanban board, JSON dump, and the "decisions to make" Q&A flow. Read-only by default; the Q&A mode calls Skill(decide-card) per answer.
  • Skill(next-card) — auto-pick the highest-leverage open gate=none card to work on next. Read-only; does NOT flip status.
  • Skill(create-card) — file a new card with proper frontmatter and a DoD scaffold (reproduce.py is authored by hand for bug-class cards, not scaffolded by the tool).
  • Skill(advance-card) — flip status (open→active, *→open, *→disproved, *→superseded) and manage the waiting_on impediment overlay (goc wait). Wraps goc status and goc wait. Status + overlay only — human_gate is decide-card's responsibility.
  • Skill(decide-card) — the human's Andon-cord lowering action. Records <decision> + <because> on a parked card and flips gate decision/session → none. The card comes out open (one parked while active is released) so the next pull-card claims and implements per the recorded decision.
  • Skill(finish-card) — close a card: tick DoD, append closure log, run goc done <title>, then run any project-specific post-close or commit handoff defined by the consuming repo's hook.
  • Skill(card-schema) — schema reference (read-only): required fields, enums, canonical tags with predicates, DoD detection, relationship invariants.
  • Skill(refine-deck) — hygiene pass: retag stale cards, prune unverified parks, surface cards citing defunct file:lines, propose new canonical tags.
  • Skill(audit-deck) — discovery: hunt for one previously-undocumented defect / derivation gap / doc drift / missing test. Files via Skill(create-card).
  • Skill(standup) — daily read: active + impeded cards (those carrying a waiting_on overlay), closures since yesterday, cards waiting on a human decision gate.
  • Skill(retrospective) — backwards analysis of the last N closed cards: cluster by tag, surface recurring failure modes, propose generalization candidates.

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.