Definition of Ready and Done
The two checklists every work item carries: the templates the project writes once, the lists each item ticks on its own, and the gates that hold an item out of a sprint or out of Done until the required entries are ticked.
By the end of this page you will know what the Definition of Ready and the Definition of Done are in Zuse Bifrost, how a project writes their templates once, how each item ticks its own copy, what the two gates refuse and where, and how an agent reads and ticks the same lists.
A definition is a checklist. The Definition of Ready says what a story needs before the team takes it into a sprint; the Definition of Done says what an item needs before it counts as done. The project keeps a template for each under its settings, and every work item carries its own copy of both, seeded from the templates when the item is created or first opened. From then on the copy is the item's: entries are ticked by a person at a time, added when this item needs one more, removed when one does not apply, without touching the template or any other item. The lists are workflow state rather than content, so they write no version of the item. They are the team's: a client guest never sees them.
Each entry is required or optional. The gates read only the required ones: when the project switches a gate on, an item whose required entries are not all ticked is held out of a sprint, or out of Done, with a message that names the entries still to tick.
Before you begin
| To | You need |
|---|---|
| See an item's lists | work-item:view-any; a viewer, an analyst, a tester and a release manager read them |
| Tick an entry, add one or remove one | work-item:update; the project manager, the analyst and the developers by default |
| Write the templates and switch the gates | project:update, under the project's settings |
The templates and the gates live on the project settings page, under Workflow. A new project starts with the workspace's templates, four entries each, and the done gate on.
Write the templates
Under Workflow on the project's settings, each definition has a list of rows: the entry in one sentence and a Required switch. Add a row with Add Entry, reorder with the arrows, remove with the cross, and Save. The workspace's defaults are a starting point:
| Definition of Ready | Definition of Done |
|---|---|
| The story says who it is for and why | The code is reviewed and merged |
| The acceptance criteria are written and testable | Every acceptance criterion is verified |
| The story is sized | The automated tests cover the change and pass |
| Its dependencies and blockers are known (optional) | The documentation and the release notes are updated (optional) |
A template feeds the items created or opened after it is saved. Items that already carry a copy keep it as it is, because a definition the team agreed on for a sprint should not change under the work in flight; change an item's own list from its flyout when it needs to follow.
Switch the gates on
Two switches on the same section decide what the definitions hold back:
- Require the Definition of Ready for a sprint holds an item out of a sprint, from the sprint's planner, the backlog's Sprint menu and field, and the API, until every required entry of its Definition of Ready is ticked. Off by default, so a team refines in its own time.
- Require the Definition of Done to finish holds an item out of Done, from the backlog's Move to, a drag on the board, an agent's move and the API, until every required entry of its Definition of Done is ticked. On by default.
A refused move says which definition and lists the entries still to tick; nothing else changes. With a gate off, the lists stay on the items as a shared checklist the team ticks for its own record.
Tick the list on an item
Open an item on the backlog; below its acceptance criteria the flyout shows Definition of Ready and Definition of Done, each with a badge of ticked / total that turns green once every required entry is ticked. Tick a box to mark an entry done; the entry then says who ticked it and when, and ticking again unticks it. Under each list, write a sentence and press Add to give this item one more entry, required by default; the cross on an entry removes it from this item only.
A viewer sees the lists and the stamps without the boxes to tick or the controls to add and remove. An item created before the project wrote a template, or whose project keeps an empty template, shows an empty list; the gate for an empty list is open, because there is nothing to tick.
What the gates refuse
The same check runs wherever an item moves, so the answer is the same from every door:
| Where the move comes from | What happens when the definition is not met |
|---|---|
| Move to on the backlog, or a drag on the board | The toast names the definition and the entries still to tick |
| Plan Scope on the sprint, or Sprint on the backlog | The same toast; the item stays where it was |
| The REST API | 422 DEFINITION_INCOMPLETE with the list under error.context.kind and the entries under error.context.missing |
An agent's move_work_item | DEFINITION_INCOMPLETE with the entries, so it can tick them first |
The gate reads the item's own list at the moment of the move. Ticking the entries, removing an entry that does not apply, or switching the gate off in the settings opens it.
Agents and the definitions
get_work_item returns the item's two lists under checklists, each with its entries, who ticked
them and the tally, so a coding agent sees the Definition of Done before it starts and knows what
is left when it finishes. tick_checklist_item ticks one entry by its id, stamped with the token's
holder, and move_work_item into done is refused with DEFINITION_INCOMPLETE until the required
entries are ticked, when the project asks for the definition. Agents never rewrite a list; adding
and removing entries stays with people and the REST API.
All the fields
What happens next
- Ticking, unticking, adding or removing an entry emits
work_item.checklist_changedwith the list and its tally after the change; a change that leaves the list as it was emits nothing. - The item's record and its versions are untouched; the activity log shows the moves the gates let through, not the ticks.
- Saving the templates or the gates emits
project.settings_changedwith the keys that changed, like every other setting. - A new item, from the backlog, from Heimdall's drafts or from the API, is seeded with both lists the moment it is written.
Heimdall on this page
The lists have no assist of their own. Heimdall's panel reads an item's definitions the way an agent does, so ask it which items of the running sprint still have a required done entry open, or what is left on an item before it can be done; its answer names the entries.
From the API and MCP
Work items API
List an item's checklists, replace one, tick an entry, and the DEFINITION_INCOMPLETE answer on a refused move.
tick_checklist_item
An agent ticks one entry of a Definition of Ready or Done, stamped with its token's holder.
get_work_item
The item with its two lists under checklists, each entry with its tick and the tally.
Project settings API
The templates as definition_of_ready and definition_of_done, and the two gate flags.
Permissions
| Action | Permission |
|---|---|
| See an item's lists | work-item:view-any; never a client guest |
| Tick, untick, add or remove an entry | work-item:update |
| Tick an entry as an agent | work-item:update |
| Write the templates and switch the gates | project:update |
Frequently asked
I changed the template. Why do the open items still show the old list? By design: an item's list is its own from the moment it is seeded, so a sprint's agreed definition does not shift under the work. Edit the items that should follow, from their flyouts, or over the API with a replace.
Can an optional entry block a move? No. The gates read required entries only. Make an entry required when it must be ticked before the move, and optional when it is a reminder.
Our project has no Definition of Ready. Will the sprint gate block everything? No. A list with no required entries is complete, so the gate is open. Keep the gate off, or keep the template empty, until the team agrees on one.
Does ticking an entry write a version of the item?
No. Ticks are workflow state, kept with who and when, and announced by work_item.checklist_changed;
the item's versions follow its record, not its lists.
Can a client guest see the lists? No. The definitions are the team's working agreement; a guest reads the item's record and its acceptance criteria once the item is approved, never its lists.
Related
- Backlog: the flyout where the lists live and the moves the done gate holds.
- Sprints: the planner the ready gate holds.
- Board: the drag the done gate holds.
- Project settings: the templates and the two gates.
- Acceptance criteria: what a story must do, beside what the team must do to call it done.
How is this guide?
Last updated on
Estimation
Choose the project's story point scale, size an item by hand or take Heimdall's suggestion against the items the project already sized, and see where the points go: the sprint's capacity, its planner, the burndown and the velocity.
Time Tracking
The Time page of a project and the timer in the sidebar: log a stretch of work on an item by hand or by the clock, with the day, the kind of work, whether it bills and what is left on the item; who may change a log, and what the logs feed.