work-item-types

work_item_types is the per-workspace catalog that classifies a feature as engineering work: Feature, Bug, Tech-Debt, or whatever else a team tracks. Every workspace is seeded with those three; the catalog is yours to extend.

It is workspace configuration, not a Golden Thread entity, it has no junctions and nothing links to it except features.type_id.

The catalog is per-workspace

Types are scoped by workspace_id with a unique (workspace_id, key). Two workspaces can both have a "Hotfix" type and they are unrelated rows.

The key is the stable slug; label is display-only and can be renamed freely. Import matches on key, so renaming a label never breaks an existing template.

Roadmap visibility

show_on_roadmap decides whether features of this type appear on the in-app Roadmap page and reach the public roadmap and embed. Feature is seeded true; Bug and Tech-Debt are seeded false, so internal work stays off the roadmap and does not leak to customers.

The public surfaces fail closed: they inner-join on the type and require show_on_roadmap = true. A feature whose type is missing is withheld rather than published, there is no flag to honour, and guessing in the permissive direction is how bug trackers end up on customer roadmaps.

You should never see an untyped feature in practice. ProductOS fills type_id with the workspace default whenever a writer omits it, which covers integration sync, MCP, and raw API posts alike. If one does exist, the in-app Roadmap page treats it as the default type, the way the rest of the app labels it; only the public surfaces withhold it.

Archive, don't delete

is_archived retires a type: it disappears from pickers while existing features keep their classification and history.

Tenancy

A feature can only reference a type in its own workspace; cross-workspace ids are rejected.

Ordering and colour

sort_order drives display order in pickers and settings. color holds one of the tokens in the Settings → Work-Item Types palette, bg-accent-purple (Purple), bg-accent-teal (Teal), bg-accent-orange (Orange) or bg-accent-rose (Rose), never a raw hex value, so badges stay correct in both light and dark themes.

Permissions

Reads are available to any workspace member. Writes require the taxonomy.manage capability, which members and above hold, worth knowing, since show_on_roadmap is a public-visibility toggle that a member can flip.