Skip to content
Spec{0}

Cards and the spec

Every card in Spec0 is a structured spec — not just a title and a description. That structure is what lets you hand work to an agent without re-explaining everything every time.

The shape of a card

A card has four parts:

  • Requirements — what should be true when this card is done. One short markdown file. User stories, acceptance criteria, anything that helps a stranger pick this up cold.
  • Design — how you’d build it. Approach, file locations, trade-offs. Another short markdown file.
  • Tasks — a flat, ordered list of build steps. Each task has a status: pending → in-progress → completed (or skipped).
  • Verifications — a checklist of proof items. Each one names a specific thing to verify and what kind of proof to attach (text, screenshot, video, file).

There’s no “ticket description” field separate from these — the spec is the description.

Two kinds of card

  • feature — new behavior. Requirements typically follow EARS-style user stories (“When X, the system SHALL Y”).
  • bugfix — broken existing behavior. Requirements describe Current vs Expected, with the trigger.

Kind is locked at creation. Pick the right one when you create the card.

Why the spec matters

When an agent claims a card, it reads the requirements, design, tasks, and verifications. That’s its complete brief. If the spec is sloppy, the agent will either guess (badly) or ask for clarification.

A good rule of thumb: a teammate should be able to pick up the card cold and know what to do without asking you.

Who writes the spec

Two routes, both first-class:

  • You write it. Open the new-card view and fill in the requirement, design, tasks, and verifications yourself. Good when you already know the shape.
  • An agent writes it. Brief a connected agent in plain language (“create a feature card for a project-wide search box, hitting the existing index, with three or four tasks”) and let it call spec0_create_card, spec0_add_task, and spec0_add_verification on your behalf. The card lands in Drafts for you to read, edit, and lock.

The second route is how most cards get written in practice — you talk through the shape, the agent drafts the spec, you tighten it. Either way the result is the same structured card; the only difference is who held the pen.

Templates

The templates spec0.requirements, spec0.design, and spec0.tasks are MCP prompts available to any connected agent. Whether you’re writing the card yourself or having an agent draft it, the same templates apply — they branch on kind, so the requirements template for a bugfix is different from one for a feature.