Tutorials · Lesson 2 of 13

Spec

The spec is what to build: every requirement as one row of SPEC.md, in one format. Agents draft rows and you approve them. Only approved rows are canon, and every item cites the rows it serves.

By the spec, we mean:

The row

Five parts: an id, a status, a priority, what must be true, and the test that proves it.

G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js
  1. IdA section letter and a number. Items and commits cite it.
  2. StatusA draft until you mark it approved.
  3. Prioritymust, or aim for what can wait.
  4. RequirementWhat must be true, in one sentence.
  5. GateThe test that proves it.

Approval is canon

Agents draft rows. A row counts only once you mark it approved.

The Spec tab of pullboard view: four rows of a checkout spec, three approved and one draft, with row G1 open beside them listing the items that cite it.

Try it

Approve a row in SPEC.md, then check the spec.

~/your-repo
$ pullboard spec check          # lints SPEC.md and DOCTRINE.md
$ pullboard spec show G1        # the row, its gate, signed or not
$ pullboard spec unmet --must   # approved musts nothing has met