Cards

A card is one piece of work: small enough for one agent to finish in one sitting and for you to review in one pull request. Everything an agent is told about the work comes from the card, so a card that leaves something out leaves the agent to decide it.

What a card holds

Field	What it is for
Title	A short name for the work. The only field a card must have.
Goal	What done looks like, in a sentence or two.
Constraints	The decisions already made: what to follow, what to avoid.
Scope	The files the work may change, and the functions or types involved.
Acceptance command	A command that exits zero when the card is done.
Depends on	The cards that have to be finished first.
Version	A label, such as 1.0, for the release the card belongs to.
Feature	The group of cards it ships with.

The arguments themselves are in the tool reference: create_card and update_card.

What a good card looks like

Field	An example
Title	Prorate a seat added in the middle of a cycle
Goal	Adding a member mid-cycle charges only for the days left.
Constraints	Use the existing Money type; never floats. Round half up, once, at the end. Do not touch how a full cycle is charged.
Scope	app/billing/proration.ts, app/billing/proration.test.ts
Acceptance command	npm test -- billing/proration
Depends on	APP-214

• The goal is an outcome, not a list of steps. The agent works out the steps; it cannot work out what you meant.
• The constraints are the things it would otherwise decide again. A library to use, an approach that was already tried and failed, a part of the code to leave alone. This is where most of a card’s value is.
• The scope names exact files where you can. An exact path is what Docket uses to keep two cards out of the same file. A pattern like app/billing/** still tells the agent where its edges are, but is not compared with other cards. See Scope and collisions.
• The command really can fail. npm test -- billing/proration says something when it passes. true does not.
• Dependencies are written down. A card that needs another one first stays off the list of ready cards until that one is finished, so the order does not depend on anybody remembering it.

Changing and deleting

A card’s fields can be changed at any time with update_card or from the board. Its status is not one of them: a card moves between states by being claimed, finished or released.

Dependencies are added and removed with link_cards and unlink_cards.

delete_card refuses to delete a card that others depend on. It can be told to delete it anyway, which leaves those cards orphaned. The board can also delete a card together with everything that depends on it; an agent cannot.

A deleted card disappears from the board, but it is hidden, not erased. It stays in the database, with its history, until the account is deleted. See Security and data.