Last updated July 20, 2026
Specs
A spec is where a change starts when it starts as a product idea rather than a technical one. It captures what should become true and why — a short narrative plus a list of requirements, each with its own acceptance criteria — before anyone decides how the code will do it.
Specs live on app boards, on the Specs tab, and they sit one step upstream of intents: a spec describes the outcome, you create an intent from each requirement, and those intents flow to a coding session through Cdx Code. From then on the spec tracks delivery for you — a requirement reads Delivered once every work item under it has been resolved, so you read the state of the ask instead of chasing it.
You don't have to start from a spec. Plenty of changes are born technical — an intent created from an insight finding, a board edit, a hand-written intent. Specs add the missing front door for work that begins as a requirement, and everything meets in the same intents queue either way.
Anatomy of a spec
Hit New spec on the Specs tab and the composer asks for four things:
| Field | What to write |
|---|---|
| Title | The change, named — "Invoice self-service" |
| Summary | One line on what this spec covers |
| Why | The narrative — problem, goal, what's out of scope |
| Requirements | One statement per thing that must become true, each with Done when… acceptance criteria (one per line) |
Requirements are the unit everything downstream works in: each one becomes an intent, and is tracked and signed off on its own. Keep them small and testable — "Customers can download past invoices", not "Improve the billing area".
The lifecycle
| Status | What it means |
|---|---|
| Draft | Being written. Content is fully editable. |
| In Review | Optional. A stop for teams that want a second pair of eyes — the reviewer approves or sends it back to draft. |
| Approved | The content is frozen and you can start creating intents from the requirements. |
| In Delivery | At least one requirement has an intent — entered automatically the first time you create one. |
| Delivered | You confirmed the spec is done, once every requirement is delivered. |
| Archived | Retired, at any point. |
Two deliberate choices in that table:
- Review is a choice, not a gate. Approve is available straight from draft — the author can take their own spec through the entire lifecycle. Submit for review exists for teams that want the stop, and it's exactly as optional as a draft PR.
- Approval freezes content. Once approved, the narrative and requirements stop being editable — acceptance sign-offs and delivery tracking build on them, so the ground can't shift underneath. Need to change the ask? That's a new spec (or archive and rewrite while still in draft).
From requirements to delivery
On an approved spec, select requirements and create intents from them:
- Create intent — one requirement selected, one intent. Select several and the button reads Create N intents: one intent per requirement, the default and usually right.
- Create one intent — bundle several requirements into a single work item when they only make sense shipped together.
Each intent lands unreleased in the same intents queue as everything else — same lifecycle, same Release step, same assignment. It carries the requirement's statement and acceptance criteria as its Instructions, and it stays back-linked to the spec that created it.
When a developer pulls the queue with /intents, an intent born from a spec brings its spec along — the coding session sees part of spec "Invoice self-service" with the narrative and the exact requirements it serves, so the implementer reads the why, not just the what.
Coverage
The spec's detail view shows a coverage badge per requirement:
| Badge | Meaning |
|---|---|
| No intent yet | Nothing has been created from it. |
| In delivery | Its intents are moving through the queue. |
| Delivered | Every linked intent reached a terminal state. |
| Needs attention | Something under it was rejected, went stale, or needs a decision. |
Coverage is derived, never typed in: a requirement's badge is a rollup of the intents created from it, so the spec keeps up with the queue without anyone maintaining a status field on it.
Be precise about what that proves. An intent created from a requirement carries your statement and acceptance criteria as Instructions — prose telling an implementer what to do — and no sync can check prose against code. So a requirement's Delivered rests on the implementer's resolution. Verification is real, but it's narrower than that: where an intent proposes a structural change to the board — a node added, an edge redrawn — the next /sync matches the pushed code against it and stamps it verified (Intents → Trust, then verify). Your own confirmation pass is the acceptance sign-off below.
When every requirement is delivered, the spec offers the last step itself — Every requirement is delivered — confirm above — and Mark delivered closes it.
Signing off acceptance criteria
After approval, each acceptance criterion gains a checkbox. Ticking it records who signed it off and when — so "Done when a customer can download any invoice from the last 24 months" is a recorded human judgement with a name on it, distinct from the coverage rollup, which only tells you the work was resolved — not that it was right. Use them as your product-side confirmation pass once delivery turns green.
Drafting with chat
You rarely have to write a spec from a blank page:
- From a bound document. If the board carries a PRD, RFC, or feature brief as a reference source, ask chat to draft a spec from it. It reads the whole document, proposes a structured spec — narrative, requirements, acceptance — and asks for your confirmation before anything is created. The draft lands as a normal spec, attributed to the document it came from.
- From a rough ask. Describe the outcome in a sentence — "we need annual billing" — and chat reads what the board already knows about the system and proposes a requirement breakdown for you to confirm and edit.
Both paths end in a spec draft you own. Chat never approves a spec, and never creates an intent, on its own — anything a machine proposes waits for a person.
If you drive your app through requirements and conversations rather than diagrams, make Specs your front door: write or draft a spec, approve it, create the intents, and watch coverage close. Anyone with edit access to the board can do all of it — write, approve, create intents, and confirm delivery — whether their title says product owner, analyst, or architect. The For Every Role guide walks this path end to end.