advance-card
Skill7 starsChanged 6 months agoMITView on GitHub
Mutate a card's status (everything except done — that is finish-card's job), record relationship edges, or set the goc wait impediment overlay. AUTO-INVOKE on "I'll start on X", "mark this disproved", "supersede with Z", "make this depend on Y".
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- site/llms.txtllms.txt
- 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
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
If any ! block below shows goc: command not found, Permission for this action has been denied, or no such file or directory: …
- Distinctive: line 17
Every status transition is a documented agreement, not a silent flag flip — the reason lives on disk: in the body for terminal transitions, …
- Very specific: line 41
Run goc show <title> yourself with the real title bound.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
When to invoke
Invoke when the user says "I'll start on X", "I'm working on", "mark this disproved", "supersede with Z", "this is part of X", "make this depend on Y", "these should be linked", "should this be an edge or a tag?", "remove this dependency", "unlink these", or describes any non-done status change or relationship-modeling intent. For "this is blocked by Y" / "unblock", set or clear the impediment overlay with goc wait (Step 6) instead of flipping status. Status transitions and relationship edges are documented agreements (Kanban explicit policies, Anderson).
Preflight
If any ! block below shows goc: command not found, Permission for this action has been denied, or no such file or directory: .game-of-cards/deck/, stop and invoke Skill(kickoff) first. Kickoff finds the missing setup step (CLI not installed, deck not scaffolded); a denied goc call goes to Skill(claude-kickoff) on Claude Code. Re-invoke this skill only after kickoff completes.
Advance a card
Every status transition is a documented agreement, not a silent flag
flip — the reason lives on disk: in the body for terminal
transitions, in the commit message for mid-flight ones. Mutate a
card's status — everything except done, which is
Skill(finish-card)'s DoD-gated contract. Read the card first to
confirm the transition is legal, then run the matching CLI.
Edge cases live in reference.md — a sibling file in this
skill's directory. Read the named section only when the situation
actually applies:
| Situation | reference.md section |
| Flipping to disproved / superseded (required body work) | Terminal transitions |
| "Should this be an edge or a tag?" / coordinating cards | Edge vs tag |
A recorded advances edge turns out false | Retraction |
| Worker assignment and queue filtering | Worker field |
A legacy status: blocked card | Deprecated blocked status |
| Why transitions are explicit policies | Rationale |
User argument: $ARGUMENTS — <title> <new-status> [--by <other-title>].
Step 1 — read the card
Run goc show <title> yourself with the real title bound. Confirm:
- Current status matches the transition (e.g.
open → activerequires currentopen). - The
human_gatefits the move. Flipping asession-gated card toactiveautonomously is a stop — that needs the human in the loop. - For
disproved/superseded, the body documents the rebuttal / replacement BEFORE you flip (reference.md§ Terminal transitions).
status, human_gate, and the impediment overlay (waiting_on +
waiting_until) are orthogonal axes — a card may be active AND
carry waiting_on: external (see Skill(card-schema) "Three-axis
stuck model"). The legacy status: blocked is deprecated; set the
overlay (Step 6) or rely on derived readiness instead
(reference.md § Deprecated blocked status).
Step 2 — match the transition to the CLI
| transition | CLI | notes |
open → active | goc status <title> active | "claiming" the card; also clears draft: true |
active → open | goc status <title> open | release the claim (re-queue) when stepping away mid-flight without disproving the work |
* → open | goc status <title> open | re-queue (rare) |
* → disproved | goc status <title> disproved | populate rebuttal first; CLI stamps closed_at |
* → superseded | goc status <title> superseded --by <successor> | sets the typed superseded_by / supersedes link bidirectionally; CLI stamps closed_at |
- To release an authored draft to the queue without claiming it:
goc publish <title>. A draft cannot be moved tosuperseded/disproved— a title-only scaffold has no authored scope to judge (seeSkill(card-schema)"Draft"). - Parking on an external wait is the overlay's job (Step 6), never a
status flip; a human-judgement wait raises
human_gateinstead. - An
advanced_byprereq that is still open needs NO status change — derived dependency-readiness shows it and self-clears when the prereq closes.
Step 3 — populate the two writing surfaces
Each transition routes writing to the README dashboard (rewrite in
place) and/or the log.md journal (append):
| Transition | README dashboard | log.md journal |
open → active | no change required | optional; the claim commit usually suffices |
set / clear waiting_on | update the affected section to reflect the wait / its resolution | append: what the wait is for and the expected return signal / what changed |
* → open (re-queue) | rewrite sections no longer accurate | append: why re-queued |
* → disproved | rewrite body to document the rebuttal | append: when disproved, by what evidence |
* → superseded | leave body as the historical record | append: successor link + one-line why |
Rule of thumb: state-of-the-world updates rewrite the README;
transition narrative, decisions, and timestamps append to log.md
(see Skill(card-schema) "What goes where"). The required body
content for disproved (hypothesis / verdict / source of error) and
superseded (typed link, journal rationale, no README rewrite) is
specified in reference.md § Terminal transitions — read it before
your first terminal flip.
Step 4 — run the transition
# Open → active (claiming):
goc status <title> active
# Add / remove a value-flow edge:
goc advance <title> --by <other>
goc unadvance <title> --by <other>
# Disproved / superseded:
goc status <title> disproved
goc status <title> superseded --by <successor-title>The CLI prints <title>: <prior> → <new> on success and follows the
repo's .game-of-cards/config.yaml workflow.auto_commit policy.
Step 5 — claim is its own commit
Status flips and edge mutations commit immediately, separately from
the work commit, so a sibling branch pulling sees status: active
before it races on the same YAML. --no-commit skips once;
--commit forces a state-only commit when the repo config disables
auto-commit. If the commit is skipped (no repo, mid-merge, no diff),
the CLI prints a note — the on-disk state still mutated.
Step 6 — set or clear an impediment overlay (goc wait)
For exogenous waits the dependency graph cannot see: external
(vendor / third party), resource (person or skill unavailable),
deferred (calendar-postponed).
goc wait <title> --reason external --until <YYYY-MM-DD>
goc wait <title> --until <YYYY-MM-DD> # bare --until implies deferred
goc wait <title> --reason resource # open-ended wait
goc wait <title> --clearA future waiting_until (or a reason with no date) hides the card
from --ready / next-card / pull-card and re-enters it automatically
when the date passes; a date that elapses while the card waits is
surfaced by goc validate as WAITING_OVERDUE. An --until that has
already elapsed hides nothing, so goc wait refuses it (exit 2,
nothing written). A bare date is midnight UTC at the start of that
day: --until <today> has already elapsed — to defer through today,
pass tomorrow's date. The overlay is orthogonal to status.
Edge vs tag (short form)
- Same value chain — closing the source delivers a piece of the
target's value →
advancesedge:goc advance <title> --by <other>(maintains both sides atomically; half-edges are validator errors; cycles forbidden). - Same theme, no closure dependency — a future filter would want them grouped → shared tag, no edge.
- One card coordinates many — aggregation epic (closes when its
children close) →
child.advances: [epic]; governing cluster (closes when decided) → shared tag, NO edge; neverepic.advances: [children](BACKWARDS_EPIC_EDGE). The tell: a coordinator that closes on its own deliverable is a governing cluster.
At filing time, goc new <child> --advances <epic> --commit wires
both sides in one atomic commit. Full decision procedure, the
value-law reasoning, and the retraction contract: reference.md
§ Edge vs tag and § Retraction.
Worker field
goc status <title> active auto-populates worker with the current
identity at claim time. Free-form: flat string (worker: rodja) or
mapping (worker: {who: rodja, where: feature/foo}). Filter queue
views with goc --worker <X> or the GOC_WORKER env var. Details:
reference.md § Worker field.
Cross-references
reference.md(this skill's directory) — edge cases routed in the table above.Skill(finish-card)—donetransitions (DoD-gated).Skill(card-schema)— transition semantics, edge invariants,human_gaterules.Skill(create-card)— when a supersession needs a new card to point at.
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.

