deck

name	deck
description	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).

Codex GoC Command

When this skill says goc ..., resolve the executable before running the command:

• In the game-of-cards source checkout, use uv run goc ....
• If goc is already on PATH, use goc ....
• If this skill is loaded from the Game of Cards Codex plugin, use the bundled helper at <plugin-root>/skills/_goc-bootstrap.sh ...; the plugin root is the parent directory that contains both skills/ and bin/.
• If the plugin root is not obvious from the loaded skill path, locate the helper with:

GOC_BOOTSTRAP=$(find "$HOME/.codex/plugins/cache" -path '*/game-of-cards/*/skills/_goc-bootstrap.sh' -type f -perm -111 -exec ls -t {} + 2>/dev/null | head -n 1)
test -n "$GOC_BOOTSTRAP" || { echo "GoC Codex plugin bootstrap not found" >&2; exit 127; }
"$GOC_BOOTSTRAP" --help

Use that helper path in place of bare goc for the rest of the skill. Do not edit deck files directly just because goc is not on PATH.

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.