# Deck

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

- Skill: `zauberzeug/deck-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zauberzeug/deck-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zauberzeug/deck-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zauberzeug (https://skillmd.com/u/zauberzeug)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zauberzeug/deck-2

---


## 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:

| Situation | `reference.md` section |
|---|---|
| Why XP/Scrum/Kanban discipline is load-bearing for agent swarms | Heritage & philosophy |
| Why card operations stay invisible; full operating-mode prose | Game of Cards as the runtime |
| Why the methodology is named Game of Cards | The worldview |
| New evidence after a card closed | Closure is not frozenness |
| How status / `waiting_on` / `human_gate` compose | Status, overlay, and gate are orthogonal axes |
| Pre-2026-05-01 placeholder DoDs; v1 `find-todo`/`work-todo` names | Migration 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; git's merge handles the rare simultaneous-claim race
(whichever commits first wins).

## 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

| Verb | What it does |
|---|---|
| `goc` | Show the open queue (value-sorted). |
| `goc --board` | Multi-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 7d` | Recently 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 Y` | Lower gate from decision/session → none. |
| `goc validate` | Validate 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/
  SCHEMA.md                 # canonical schema (frontmatter IS the schema)
  README.md                 # navigation + conventions
  deck.py                   # CLI; computes filtered views from frontmatter
  <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`. Status stays `open` 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.