Task Cards

Task cards are the next move in spec-driven development: the unit of delegated work. Once you master task cards, you can break a specification into small, self-contained pieces that an AI agent or a colleague can execute independently, in parallel, and you can review each piece as it comes back. This unlocks the rest of the spec-driven workflow: you will be able to write acceptance criteria that define 'done' for each card, set up review gates to check the work, and run a spec-to-code pipeline where an agent generates code from your cards. Without task cards, launching an AI agent at a specification produces a jumbled mess with no way to check progress; with them, you control the whole process.

Suppose you have to build a small website for a local shop: a product page, a shopping cart, and a checkout form. A specification for that might run to a few pages. You cannot hand that whole document to a colleague or an AI agent and say 'build this' — it is too much, and many decisions are left open. Instead, you break the specification into small work items, each of which says exactly what to do, what information is already available, and what will count as finished. Each work item is small enough that a person or an agent can finish it in a sitting, and it is self-contained: the person does not need to read the whole specification to know what to do. For example, one item might be 'Add an 'add to cart' button to the product page. When clicked, call the addToCart function (already stubbed in cart.js) with the product ID, and show a small message saying the item is in the cart. Done when the button appears and the message shows on click.' That is a task card. Because each card carries its own context, several people or agents can work on different cards at the same time without interfering with each other. And because each card is small, reviewing the result takes a few minutes, not a whole day. Task cards turn a big vague job into a list of small, checkable jobs.

Think of a wedding planner. The bride gives her a thick binder: colors, venue, guest list, menu, timeline. The planner cannot 'plan the wedding' in one go; she must break it into dozens of small tasks: book the caterer, order the flowers, send invitations, confirm the band, arrange seating. For each task, the planner writes an index card: what to do (call three florists and get quotes, then book one within budget), what information is needed (guest count, color scheme, budget), and what 'done' means (a signed contract with a florist). She can hand a card to an assistant or a vendor, and they can execute it without asking her for more details. The cards are self-contained: the florist does not need to know the entire wedding plan to arrange flowers. They can work in parallel: while the florist handles flowers, the caterer handles food, and the planner reviews each card when it comes back. The analogy breaks down where a task card is more precise than a wedding index card. In software, 'done' is testable, not just agreed upon. The card must specify acceptance criteria — conditions that can be checked automatically or manually to know the card is complete. Also, a wedding card might leave room for taste; a software card should leave as little as possible, because an AI agent has no taste and needs explicit instructions. A true task card is not a broad goal like 'improve the user experience' but a narrow, verifiable action like 'add a tooltip to the submit button that appears on hover, with text: This will send your request'.

A task card is a small, self-contained work item derived from a specification, carrying enough context (what to do, what inputs are available, what 'done' means) for an agent or person to execute it independently, and sized so that its output is a reviewable unit of change.

You have not learned any other concepts yet, so this page stands alone. But your library will soon hold notes on Acceptance Criteria, Engineering Intent Documents, Product Requirements Documents, Requirements Traceability, Review Gates, Spec Drift, and the Spec-to-Code Pipeline. Task cards sit right in the middle of all of those. Each card should be derived from a requirement (from a product requirements document), should carry acceptance criteria (from the acceptance criteria notes), and should be reviewed at a gate (from the review gates notes). When the code drifts from the specification, the problem often shows up as a task card that was badly written or missing. When you build a spec-to-code pipeline, the task cards are what you feed to the AI agent. So every concept you learn later will assume you know what a task card is.