Definition of Done & Ready for Jira

2.1 Installation

1. Install Definition of Done & Ready for Jira from the Atlassian Marketplace.
2. Grant the requested permissions when prompted. The app is built on Atlassian Forge and runs entirely on Atlassian infrastructure.
3. Open any issue — the Definition of Done panel appears in the issue view. Add the starter templates from the admin page (see section 4) and you are ready to go.

2.2 Entry points

Issue panel

The Definition of Done context panel on every issue — checklists, statuses, the readiness score, and history. See section 3.

Admin page

Jira Settings → Apps → Definition of Done — manage templates and configure gate enforcement. Jira admin permission required.

Compliance report

A global page under Apps in the Jira navigation — readiness and gate status across every tracked issue. See section 7.

Workflow validators

Two validators — Definition of Done gate and Definition of Ready gate — you attach to workflow transitions. See section 5.

2.3 Requirements

• Jira Cloud — the app is a Forge app and supports Jira Cloud only.
• Any project type — the checklists work everywhere; the workflow gates work in both team-managed and company-managed projects.

3.1 Readiness score & gate status

The panel header shows the issue's readiness score (0–100, see section 6) next to a gate badge: All criteria met when every mandatory item is complete, or N mandatory item(s) left when a gate would still block. The badge counts mandatory items across every checklist on the issue; the Done gate enforces all of them except Definition of Ready items, which belong to the Ready gate (section 5).

3.2 Adding a checklist

Use Add a checklist to apply any template to the issue — the picker lists each template with its kind (DoR, DoD, AC, QA, security). An issue can carry several checklists at once, each rendered as its own card with a progress bar and a done/total counter. Templates flagged for auto-apply attach themselves to new issues without any manual step.

3.3 Item statuses

Every item has five possible statuses:

Check the box to mark an item done, or use the … menu for Mark in progress, Skip…, Mark N/A…, and Reopen. Skipping or marking N/A always prompts for a reason, which is shown under the item and recorded in the history — conscious exceptions, not silent ones.

3.4 Required items

Items marked Required carry a badge and drive the gate: a transition guarded by a gate passes only when every required item is Done, Skipped, or N/A. Optional items influence the readiness score but never block.

3.5 Suggested acceptance criteria

Suggest AC derives acceptance-criteria suggestions from the issue's own summary and description — deterministically, on-platform, with zero egress. No large language model is involved and nothing leaves Atlassian. Pick the suggestions you want and they are added as a checklist on the issue.

3.6 History

History opens the issue's audit trail: every checklist applied or removed, every status change with who did it and when, and every skip/N-A reason. The log is bounded per issue (newest 200 entries) and is the basis of the app's auditability.

4.1 The five starter templates

From the admin page, Add built-in starter templates seeds five ready-made checklists so there is no blank-page setup:

Every starter item is editable — treat them as a starting point, not a prescription.

4.2 Creating and editing templates

New template opens the editor: name the template, pick its kind (Definition of Ready, Definition of Done, Acceptance Criteria, QA, Security Review, or Custom), add items, and mark each item Required or optional. Items can be reordered and removed. Editing a template affects checklists applied from it going forward; already-applied checklists on issues keep their state.

4.3 Scoping

All projects (global)

The template is available and auto-applies everywhere.

A specific project

Limited to one project — useful for team-specific standards.

A specific issue type

For example, a Security Review checklist only on Story issues.

Project + issue type

The narrowest scope — one issue type in one project.

4.4 Auto-apply

Toggle Auto-apply to matching new issues on a template and every newly created issue that matches its scope receives the checklist automatically. Auto-apply is idempotent per template — an issue never receives the same checklist twice.

5.1 Adding a gate to a workflow (one-time setup)

What you are about to do, in plain words: a workflow is the path an issue travels in Jira (for example To Do → In Progress → Done), and a transition is one hop on that path. Right now, anyone can drag an issue to Done even with required checklist items still open. In the steps below you will add the app's Definition of Done gate as a rule on the hop into Done, so Jira checks the checklist first and politely refuses when required items are unfinished. It takes about two minutes, once, per project workflow.

Before you start — two things to check:

• You need admin rights: project admin is enough for a team-managed project; company-managed workflows need a Jira admin.
• Find out which project type you have: look at the bottom of your project's left sidebar. If it says "You're in a team-managed project", follow the first list below. If it doesn't, yours is company-managed — follow the second list.

If your project is team-managed (most newer projects are):

1. Open your project, then click Project settings at the bottom of the left sidebar.
2. In the settings menu, open the work type you want to guard — for example Task. (Jira may call these "work types" or "issue types".)
3. Click the Edit workflow button at the top right. A diagram opens showing your statuses as boxes: To Do, In Progress, Done.
4. Click on the small chip or arrow attached to the Done box (it is usually labelled Any or with the transition's name). A panel opens on the right titled Transition.
5. In that panel, under Rules, click the + next to Validate details (it says "Validate details before moving the issue").
6. A rule picker opens. Choose Definition of Done gate — you will find it at the top, or under Marketplace rules. Click Select.
7. The rule needs no configuration — just click Add.
8. Now click the blue Update workflow button at the very top right, and confirm with Save in the dialog. (The dialog lists every work type sharing this workflow — that is fine, keep them selected.)

If your project is company-managed:

1. Click the ⚙ gear icon in the top-right of Jira, then Issues.
2. In the left menu choose Workflows, find the workflow your project uses, and click Edit.
3. Click the transition arrow that points into Done.
4. Open the Validators tab and click Add validator.
5. Choose Definition of Done gate from the list and confirm.
6. Click Publish (or Publish draft) to make the change live.

Check it worked:

• In the workflow diagram, the transition into Done now shows a small rule marker (a ⚡ on the chip in team-managed projects).
• Open any issue that has a checklist with an unfinished Required item and try to move it to Done. Jira should refuse with a message like: Definition of Done not met — 1 mandatory item remaining: …
• Tick the remaining required items and try again — now the issue moves.

Which checklists does each gate check? The Done gate enforces the required items of every checklist type except Definition of Ready — DoD, Acceptance Criteria, QA, Security, and custom checklists alike. The Ready gate enforces Definition of Ready checklists only: add it with the same recipe on the transition out of To Do (or your sprint-start transition), picking Definition of Ready gate in step 6 instead.

5.2 Hard-block vs. warn-only

On the admin page, the Gate enforcement card has a Hard-block toggle. In hard-block mode the transition is refused until mandatory items are complete. In warn-only mode the gate is advisory: the transition is allowed, so teams can adopt the discipline gradually before turning enforcement on.

5.3 What a blocked transition looks like

When a gate blocks, Jira shows the standard validator error with the app's message, for example: Definition of Done not met — 2 mandatory item(s) remaining: Acceptance criteria verified; No open critical or blocker bugs. The panel's gate badge shows the same state before anyone attempts the transition, so blocks are never a surprise.

5.4 Fail-open design

If the gate cannot read an issue's checklist state (for example, a transient error), it allows the transition rather than trapping your team. A gate should enforce your working agreement — never lock you out of your own workflow.

7.1 Reading the report

The global report (under Apps) aggregates every issue that carries a checklist:

• Issues tracked — how many issues have checklists.
• Avg readiness — the mean readiness score, color-coded.
• Gates met / Gates blocked — how many issues would pass or fail their gate right now.
• Checklists by kind — distribution across DoR, DoD, AC, QA, and security.
• Issues blocking on mandatory items — the worst-first list of issues with open mandatory items, each showing its score and how many items are left.

The report is capped for performance on very large sites; a footer note tells you when it is showing a subset.

7.2 CSV export

Export CSV downloads the full table — issue key, readiness, gate state, blocking-item count, checklist kinds, and item totals — ready for spreadsheets or BI tooling.