Blueprints

Overview

Every team has a shape for a kind of work that never reaches the tracker: a new endpoint also needs a metric, a test, an access rule and a page of documentation, and the person who knows that is the reviewer who says so afterwards. A blueprint writes that shape down as a custom work-item type — a display name, one of the eight base types, and a list of facets the work has to cover. File an item as that type and the facets land on it as acceptance criteria, ticked automatically wherever a pipeline can prove them. Define the type once on a group and every repository beneath it offers it.

Quick start

Before you start

How it works

A custom type is a base type wearing a name

A blueprint does not invent a new kind of object. It picks one of the eight base types — epic, story, bug, task, spike, chore, incident, sub_task — and adds two things to it: a display name and a facet list. "API Feature" is a story wearing a blueprint. The base type still decides everything structural: which container the item may live in, which children it may hold, and which fields it has. Nothing about hierarchy, boards, listings or rollups changes because an item was filed as a custom type.

That is also why one rule exists that surprises people: an epic lives only in a group, and a group has no pipelines to prove anything, so an epic-based blueprint may declare manual facets only. A bound facet on one is refused at the moment you save the type, not silently dropped when somebody files an item.

Facets become acceptance criteria

Applying a blueprint seeds one acceptance criterion per facet. There is no second checklist and no generated markdown — the facets are the item's Definition of Done, written as the same typed criteria you would author by hand.

Each facet carries a category — interface, operability, accessibility, runbook, whatever your work decomposes into. The vocabulary is yours: a category the platform has never seen is a first-class category, stored and grouped exactly like the ones it has. A facet is green when every one of its required criteria is satisfied, and an item is verified when every required criterion on it is green — which is exactly what the merge gate reads in a repository that has turned it on.

A facet's hint becomes the criterion's text. Leave it out and the criterion is titled by the facet's label, which is fine for Tests and useless for Observability — a hint like "the endpoint emits a request metric and an error metric" is the difference between a checklist and a checklist somebody can act on.

The key is the identity, the label is just the label

Every facet has a key — a slug of 1 to 40 characters, lowercase letters, digits and hyphens — and that key is what the platform matches on. Rename the "Observability" facet to "Operability" and keep its key, and an item that already carries it keeps the criterion it has, with its tick and its history. Change the key instead and you have made a different facet: the old one stays on every item that has it, and the new one arrives beside it the next time the type is applied.

Types are inherited down the group chain

The types a container offers are its own plus every ancestor group's. Ask a repository for its available types and you get its own first, then the inherited ones nearest group first. Where two definitions share an id, the nearest one wins — a repository Maintainer can define api-feature locally and shadow the organisation's version, without affecting any other repository and without needing anything from the group.

Inheritance runs upward only. A type defined on a repository is invisible to its group, and a type defined on a sibling group is invisible here.

Applying is additive, and never a clobber

Applying a blueprint to an item compares facet keys and seeds only the ones the item does not already have. It never rewrites, reorders, unticks or removes an acceptance criterion: an existing facet keeps its tick, its evidence and any criteria a person added underneath it. So re-applying a type after it grew a fifth facet adds one criterion and disturbs nothing.

The consequences of that rule are worth stating plainly, because they are what make the feature safe to use on live work:

• Editing a blueprint does not reach back into items already filed. Adding a facet does not appear on last month's stories until somebody re-applies the type to them.
• Removing a facet from a blueprint does not retract it from anything. Items that were filed with it keep it.
• Deleting a blueprint leaves every seeded criterion intact. A tracker that silently deleted acceptance criteria out from under a team would be a tracker nobody could trust with a Definition of Done.

What an item takes from a blueprint is its Definition of Done, and only that. The item's own type stays the base type the blueprint named — an item shaped by "API Feature" is a story, and reads as a story everywhere a type is shown.

A type is addressed by the container that defines it

A blueprint is named by the container it was defined on, never by the container a work item happens to sit in. That is what makes an inherited type usable — a repository's item can be filed as a type defined three groups above it — and it is why, whenever you name a type outside the picker, you give the group or repository that owns the definition. Every listing entry carries that container, so it is the place to read the id from rather than guessing.

Filing with a type and applying a type are not quite the same

Filing a new item as a custom type sets the item's underlying type from the blueprint's base type and seeds the facets in the same write. It also checks the base type against the container: an epic-based type files in a group, an incident-based one in either, every other base type files in a repository, and the wrong pairing is refused with 400 BAD_REQUEST before anything is written. Applying a type to an item that already exists seeds the facets it is missing and leaves the underlying type where it was — so a task that gets a story-based type is still a task, with a task's fields and a task's legal children. When you want the structure too, file the item as the type; when you want the checklist on work already in flight, apply it.

How to

Define a custom type on a repository

Give it an id, a display name, a base type and its facets. The id is the identity — 1 to 40 characters, lowercase letters, digits and hyphens, not starting with a hyphen — and it has to be free within that container. The display name is what people pick from the type selector.

Every facet is a manual checkbox until you bind it, and that is the right default — most facets on most teams are not worth binding, and a type that demanded machine-checkable everything would go unused. Bind the ones that pay: a test result, a metric threshold, a coverage floor over a path, or a pipeline node going green. A bound facet's box is filled in from evidence and cannot be ticked by a person, which is the whole point of binding it.

Define a custom type for every repository in a group

Same builder, one level up. This is where a type belongs if more than one repository files that kind of work.

A type whose base type is epic may declare manual facets only, because an epic lives in a group and no group has pipelines that could decide a bound one. That is a property of the base type rather than of where you define it, so it holds for an epic-based type defined on a repository too. Trying to save a bound facet on one is refused with 400 BAD_REQUEST naming the facet. incident is not caught by this — an incident can live in a repository, so an incident-based type may bind.

See which types a repository offers

By default a repository reports only the types defined on it. Ask for inherited ones as well and you get the full picker: its own first, then each ancestor group's, nearest first, with any shadowed duplicate already resolved in favour of the nearer one. Each entry says whether it was inherited, and which container defines it.

Archived types come back in that listing too, each carrying its archived flag. The listing is the raw available set; leaving the archived ones out of the picker is the picker's job, so a script that reads this should filter them itself.

See the types a group defines

Read one type's definition

Reading one type asks the container that defines it. A repository will not answer for a type it merely inherits — that read belongs to the group that owns it, and asking the repository gives 404 NOT_FOUND.

File work as a custom type

There is no separate "assign a blueprint" step, because picking the type is the assignment. The type selector on the new-item form lists the base types that container takes plus every custom type it offers, and choosing one files the item on the blueprint's base type with its facets already seeded, in a single write — if any part of it is refused, nothing is created. That path is covered in Work items.

Apply a type to work already filed

Applying seeds the facets the item is missing as acceptance criteria. Name the blueprint by the container that defines it — the group, if the type is inherited — and the item by its number in the repository.

Applying the same type twice is safe and adds nothing the second time. Applying it after the type grew a facet adds that one facet. If the item has no room left — fifteen criteria is the ceiling on any plan — the whole apply is refused with 429 TOO_MANY_REQUESTS and nothing is written, so you never end up with half a checklist.

A work item filed in a group takes its facets at the moment it is filed. Applying a type after the fact is a repository operation.

Change a type

An update is a full replace under the version you read: send the whole definition, including every facet you want to keep, along with the version that came back from your last read. If somebody else saved the type in between, the write is refused with 409 CONFLICT rather than quietly discarding their edit.

Removing a facet from a definition stops it being seeded onto anything new. It does not remove it from work that already carries it — delete the criterion on those items if that is what you meant.

Retire a type without breaking anything

Archiving is the safe retirement: the type stays exactly where it is, keeps its facets and its bindings, and is marked archived so the type picker stops offering it. Archived is a field on the definition, so you archive a type by saving it — the same full-replace save described under Change a type — with that field set to true. Because the save is a full replace, a later save that leaves the field out brings the type back out of the archive; send it every time.

Archiving is a signal to the pickers, not a lock. The listing still returns an archived type, and a request that names its id can still file or apply with it, so archiving stops people choosing the type by accident rather than stopping the type working. Delete it when the id has to stop working altogether.

Delete a type

Reference

Limits

Two of the limits here scale with your plan. Both are checked as part of the write, so a refused request creates nothing at all — no half-saved type and no partial checklist.

The type count is of the types a container defines itself. Inherited ones are free, which is the direct incentive the design intends: define api-feature once on the organisation's root group rather than twenty-eight times, and you spend one slot instead of twenty-eight. Reaching the ceiling answers 429 TOO_MANY_REQUESTS; delete a type nobody files with, move the definition up to a group, or have an Owner request a limit increase from the group's usage page. Archiving does not help here — an archived type leaves the picker but keeps its slot.

The bound-criteria count is per repository and counts only criteria that carry a binding — manual checkboxes are not counted at all. It exists because every bound criterion is re-checked against every pipeline run in that repository.

The rest are the same on every plan, because they are product shape rather than capacity:

Going over the facet, label or id limits is a 400 BAD_REQUEST when you save the type. The per-item criteria limit is the one that binds when the type reaches an item rather than when you save it: a type with twenty facets is perfectly legal to define and is refused with 429 TOO_MANY_REQUESTS the moment you file or apply it, because fifteen is all an item holds. If a type keeps hitting that, it is describing more than one piece of work — split it, and let the facets that are really their own job become their own items.

Troubleshooting

Examples

A type for an endpoint-shaped story, with three required facets and one optional one, and the test facet bound so a pipeline decides it. This is the body of a create call against a repository or a group:

Applying it to work already filed. Replace <group-id> with the id of the group the type is defined on — the listing tags every entry with the container it came from, and that is the container to name here even when you are applying to a repository's item:

A type defined on a repository is named the same way, with repo in place of group and the repository's id. The item itself is addressed by the path, so the repository in the path and the container in the body are different things and are meant to be.

Later, the team decides documentation is not optional and adds a fifth facet. The update is a full replace, so send every facet you are keeping, with the same keys, plus the version you last read — then apply the type again to the items that should follow it.

FAQ

Related