Labels, States, Types, and Properties
Plane gives you four metadata mechanisms for work items. Pick the right one or your project becomes a tag soup nobody can search.
The Four Mechanisms
| Mechanism |
Purpose |
Cardinality |
Workflow effect |
| State |
where the item is in the workflow |
one per item |
drives boards, burndown, velocity |
| Work item type |
what kind of work it is |
one per item |
can drive different fields, templates |
| Property |
structured, queryable attribute |
one or many depending on type |
reportable filter values |
| Label |
freeform tag |
many per item |
grouping, filter shortcut |
Decision tree
Need a different workflow / different fields?
→ Work item type (e.g. Bug vs Spike)
Need a structured value you'll filter or report by?
→ Property (e.g. severity = S1, environment = prod)
Need a yes/no flag the team will toggle?
→ Label (e.g. needs-design, flaky, carryover)
Need to track the state of work?
→ State (e.g. In Review, Done)
If the answer is "I'm not sure", default to label. Labels are cheap to create and cheap to delete. Properties have schema cost. Types have workflow cost.
Labels — Naming Convention
Use prefixed namespaces so labels stay searchable. Without prefixes, you end up with bug, Bug, bug-fix, Bug Fix, BUG, defect, all meaning the same thing.
Recommended namespaces:
| Prefix |
Purpose |
Examples |
type/ |
nature of work (when not using work item types) |
type/bug, type/feature, type/chore, type/spike, type/tech-debt |
area/ |
code area or product surface |
area/api, area/web, area/mobile, area/infra, area/auth |
priority/ |
urgency (when not using built-in priority) |
priority/p0, priority/p1, priority/p2 |
status/ |
secondary status the workflow doesn't capture |
status/needs-info, status/blocked-external, status/needs-design, status/ready-for-review |
customer/ |
per-customer requests (only if you track this) |
customer/acme, customer/contoso |
release/ |
release earmarks |
release/v2.0, release/v2.1 |
Rules:
- One namespace per label. Don't combine (
type/bug-priority/p0).
- Lower-kebab-case after the slash. No spaces.
- Choose a stable color per namespace (red for
type/bug, blue for area/*, etc.) — labels become visually scannable on the board.
- Quarterly audit: list all labels, drop any with <3 uses or stale by >6 months.
Work Item States — Designing the State Machine
Plane groups states into five fixed buckets. Velocity counts only items moved into a state in the completed group during the cycle. If you put "Done" in started, your burndown lies.
Recommended state sets
Standard Scrum (most teams):
| Group |
States |
Notes |
| backlog |
Backlog |
unrefined ideas |
| unstarted |
Ready |
meets Definition of Ready |
| started |
In Progress |
actively worked |
| started |
In Review |
PR open, awaiting review |
| completed |
Done |
meets Definition of Done |
| cancelled |
Cancelled |
will not do |
Kanban with QA gate:
| Group |
States |
| backlog |
Backlog |
| unstarted |
Ready, Blocked |
| started |
In Progress, In Review, In QA |
| completed |
Done |
| cancelled |
Won't Fix |
Support / triage:
| Group |
States |
| backlog |
New |
| unstarted |
Triaged, Needs Info |
| started |
In Progress, Waiting on Customer |
| completed |
Resolved |
| cancelled |
Closed (no action) |
Research / discovery:
| Group |
States |
| backlog |
Idea |
| unstarted |
Approved |
| started |
Researching, Drafting |
| completed |
Decided |
| cancelled |
Abandoned |
State design rules
- Max 6 states across started + unstarted — beyond that, the board becomes a horizontal scroll wasteland.
- Don't add per-team states like "In Alice's review". Use assignee for that.
- Sequence matters for burndown — order states left-to-right in the natural flow.
update_state accepts sequence.
- Renaming is safe, deleting is not — items in a deleted state break. Migrate first via
/bulk-update --state new.
- Pick one default state for new items (usually
Backlog or New).
Work Item Types
Custom types let you give different kinds of work different fields and templates. Use them when the workflow itself differs.
When to use a type vs a label
| Use a TYPE when... |
Use a LABEL when... |
| different fields (Bug needs severity, Spike needs timebox) |
same fields, different categorization |
| different default state machine |
same workflow |
| different velocity treatment (Spikes don't count points) |
counts the same |
| reporting needs the breakdown |
nice-to-have filtering |
Recommended type sets
Product team: Story, Bug, Task, Spike, Tech Debt
Platform team: Feature, Bug, Incident, Runbook Item, RFC
Support team: Ticket, Bug, Question, Escalation
Maximum: 6 types. Beyond that, taxonomy fatigue dominates and people start mistyping.
Custom Properties
Properties are typed fields. They are the right mechanism for structured, queryable, reportable data.
Property data types
| Type |
Use for |
text |
freeform short string (root cause one-liner) |
number |
counts, ratios, customer impact |
select |
one-of fixed options (severity, environment) |
multi-select |
many-of fixed options (affected platforms) |
date |
deadlines, discovery dates |
boolean |
yes/no flags that need filtering (use a label for casual flags) |
user |
secondary owners (reviewer, QA lead) |
url |
links beyond /link add (vendor docs) |
Example property sets per type
Bug type:
severity (select: S0, S1, S2, S3) — requiredenvironment (select: prod, staging, dev) — requiredaffected platforms (multi-select: web, ios, android, api) — requiredroot cause (text)customers affected (number)regression? (boolean)
Spike type:
timebox (number, hours) — requiredoutcome (text)
Story type:
customer (select: from CRM list)value (select: must, should, could, won't) — required for Definition of Ready
Property design rules
- Mark required only what blocks Definition of Ready. Over-requiring kills throughput.
- Don't change a property's data type after rollout — existing values become invalid.
select is better than text for anything that will be filtered. text becomes inconsistent within a week.- Scope properties to a type when possible (severity only on Bug). Project-wide properties bloat the form.
- Pair properties with views — a property without a view that uses it is ceremony.
Maintenance — Quarterly Taxonomy Audit
Run this every quarter:
- Labels — list all labels. Drop any with <3 uses or no use in the last 90 days. Merge near-duplicates.
- States — check distribution. If items pile up in one state, the workflow has a bottleneck not captured by a state.
- Types — check usage. If a type has <5% of items, fold it into another.
- Properties — check fill rate. If a property is filled <30% of the time, it's not pulling its weight — remove or make optional.
Bad taxonomy is technical debt that compounds. A 30-minute quarterly audit prevents a 3-day cleanup later.
Cross-references
- See
agile-fundamentals for Definition of Ready / Definition of Done — these reference required properties.
- See
velocity-metrics for how state groups affect velocity calculation.
- Use commands:
/label, /state, /work-item-type, /property.
1---2name: labels-states-properties3description: Design taxonomies for Plane projects — labels, workflow states, work item types, and custom properties. Use when the user asks how to organize labels, design a state machine, set up custom fields, configure work item types, decide between label/property/type, or audit a noisy taxonomy. Covers naming conventions, recommended sets, and the difference between the four metadata mechanisms.4---56# Labels, States, Types, and Properties78Plane gives you four metadata mechanisms for work items. Pick the right one or your project becomes a tag soup nobody can search.910## The Four Mechanisms1112| Mechanism | Purpose | Cardinality | Workflow effect |13|---|---|---|---|14| **State** | where the item is in the workflow | one per item | drives boards, burndown, velocity |15| **Work item type** | what kind of work it is | one per item | can drive different fields, templates |16| **Property** | structured, queryable attribute | one or many depending on type | reportable filter values |17| **Label** | freeform tag | many per item | grouping, filter shortcut |1819### Decision tree2021```22Need a different workflow / different fields?23 → Work item type (e.g. Bug vs Spike)2425Need a structured value you'll filter or report by?26 → Property (e.g. severity = S1, environment = prod)2728Need a yes/no flag the team will toggle?29 → Label (e.g. needs-design, flaky, carryover)3031Need to track the state of work?32 → State (e.g. In Review, Done)33```3435If the answer is "I'm not sure", default to **label**. Labels are cheap to create and cheap to delete. Properties have schema cost. Types have workflow cost.3637## Labels — Naming Convention3839Use **prefixed namespaces** so labels stay searchable. Without prefixes, you end up with `bug`, `Bug`, `bug-fix`, `Bug Fix`, `BUG`, `defect`, all meaning the same thing.4041Recommended namespaces:4243| Prefix | Purpose | Examples |44|---|---|---|45| `type/` | nature of work (when not using work item types) | `type/bug`, `type/feature`, `type/chore`, `type/spike`, `type/tech-debt` |46| `area/` | code area or product surface | `area/api`, `area/web`, `area/mobile`, `area/infra`, `area/auth` |47| `priority/` | urgency (when not using built-in priority) | `priority/p0`, `priority/p1`, `priority/p2` |48| `status/` | secondary status the workflow doesn't capture | `status/needs-info`, `status/blocked-external`, `status/needs-design`, `status/ready-for-review` |49| `customer/` | per-customer requests (only if you track this) | `customer/acme`, `customer/contoso` |50| `release/` | release earmarks | `release/v2.0`, `release/v2.1` |5152Rules:53- One namespace per label. Don't combine (`type/bug-priority/p0`).54- Lower-kebab-case after the slash. No spaces.55- Choose a stable color per namespace (red for `type/bug`, blue for `area/*`, etc.) — labels become visually scannable on the board.56- Quarterly audit: list all labels, drop any with <3 uses or stale by >6 months.5758## Work Item States — Designing the State Machine5960Plane groups states into five fixed buckets. **Velocity counts only items moved into a state in the `completed` group during the cycle.** If you put "Done" in `started`, your burndown lies.6162### Recommended state sets6364**Standard Scrum (most teams):**6566| Group | States | Notes |67|---|---|---|68| backlog | Backlog | unrefined ideas |69| unstarted | Ready | meets Definition of Ready |70| started | In Progress | actively worked |71| started | In Review | PR open, awaiting review |72| completed | Done | meets Definition of Done |73| cancelled | Cancelled | will not do |7475**Kanban with QA gate:**7677| Group | States |78|---|---|79| backlog | Backlog |80| unstarted | Ready, Blocked |81| started | In Progress, In Review, In QA |82| completed | Done |83| cancelled | Won't Fix |8485**Support / triage:**8687| Group | States |88|---|---|89| backlog | New |90| unstarted | Triaged, Needs Info |91| started | In Progress, Waiting on Customer |92| completed | Resolved |93| cancelled | Closed (no action) |9495**Research / discovery:**9697| Group | States |98|---|---|99| backlog | Idea |100| unstarted | Approved |101| started | Researching, Drafting |102| completed | Decided |103| cancelled | Abandoned |104105### State design rules1061071. **Max 6 states across started + unstarted** — beyond that, the board becomes a horizontal scroll wasteland.1082. **Don't add per-team states** like "In Alice's review". Use assignee for that.1093. **Sequence matters for burndown** — order states left-to-right in the natural flow. `update_state` accepts `sequence`.1104. **Renaming is safe**, deleting is not — items in a deleted state break. Migrate first via `/bulk-update --state new`.1115. **Pick one default state** for new items (usually `Backlog` or `New`).112113## Work Item Types114115Custom types let you give different kinds of work different fields and templates. Use them when the *workflow itself* differs.116117### When to use a type vs a label118119| Use a TYPE when... | Use a LABEL when... |120|---|---|121| different fields (Bug needs severity, Spike needs timebox) | same fields, different categorization |122| different default state machine | same workflow |123| different velocity treatment (Spikes don't count points) | counts the same |124| reporting needs the breakdown | nice-to-have filtering |125126### Recommended type sets127128**Product team:** `Story`, `Bug`, `Task`, `Spike`, `Tech Debt`129**Platform team:** `Feature`, `Bug`, `Incident`, `Runbook Item`, `RFC`130**Support team:** `Ticket`, `Bug`, `Question`, `Escalation`131132**Maximum: 6 types.** Beyond that, taxonomy fatigue dominates and people start mistyping.133134## Custom Properties135136Properties are typed fields. They are the right mechanism for **structured, queryable, reportable** data.137138### Property data types139140| Type | Use for |141|---|---|142| `text` | freeform short string (root cause one-liner) |143| `number` | counts, ratios, customer impact |144| `select` | one-of fixed options (severity, environment) |145| `multi-select` | many-of fixed options (affected platforms) |146| `date` | deadlines, discovery dates |147| `boolean` | yes/no flags that need filtering (use a label for casual flags) |148| `user` | secondary owners (reviewer, QA lead) |149| `url` | links beyond `/link add` (vendor docs) |150151### Example property sets per type152153**Bug type:**154- `severity` (select: S0, S1, S2, S3) — required155- `environment` (select: prod, staging, dev) — required156- `affected platforms` (multi-select: web, ios, android, api) — required157- `root cause` (text)158- `customers affected` (number)159- `regression?` (boolean)160161**Spike type:**162- `timebox` (number, hours) — required163- `outcome` (text)164165**Story type:**166- `customer` (select: from CRM list)167- `value` (select: must, should, could, won't) — required for Definition of Ready168169### Property design rules1701711. **Mark required only what blocks Definition of Ready.** Over-requiring kills throughput.1722. **Don't change a property's data type** after rollout — existing values become invalid.1733. **`select` is better than `text`** for anything that will be filtered. `text` becomes inconsistent within a week.1744. **Scope properties to a type** when possible (severity only on Bug). Project-wide properties bloat the form.1755. **Pair properties with views** — a property without a view that uses it is ceremony.176177## Maintenance — Quarterly Taxonomy Audit178179Run this every quarter:1801811. **Labels** — list all labels. Drop any with <3 uses or no use in the last 90 days. Merge near-duplicates.1822. **States** — check distribution. If items pile up in one state, the workflow has a bottleneck not captured by a state.1833. **Types** — check usage. If a type has <5% of items, fold it into another.1844. **Properties** — check fill rate. If a property is filled <30% of the time, it's not pulling its weight — remove or make optional.185186Bad taxonomy is technical debt that compounds. A 30-minute quarterly audit prevents a 3-day cleanup later.187188## Cross-references189190- See `agile-fundamentals` for Definition of Ready / Definition of Done — these reference required properties.191- See `velocity-metrics` for how state groups affect velocity calculation.192- Use commands: `/label`, `/state`, `/work-item-type`, `/property`.
agents-store