Custom Fields

Rule

Field definitions, per-task values, and task-card visibility are three separate surfaces with their own actions. Use the definition actions for the schema, the update-task fieldValues patch for values, and the visible-field actions for what shows on cards.

Definitions

• Use list-custom-fields, create-custom-field, update-custom-field, and delete-custom-field for field definitions.
• Use reorder-custom-fields with every field id in the desired order when moving fields in the Fields list.
• A field's type is immutable after creation; update-custom-field patches the title and/or type-compatible config only.
• delete-custom-field only after explicit user confirmation; warn that deleting the definition removes its values on every task.

Field types and config

• Custom field types are text, rich_text, number, percent, currency, single_select, multi_select, and date.
• Number, percent, and currency field precision limits decimal places; precision: 0 means whole numbers only. Number fields also support optional positiveOnly.
• Select option colors are named tokens: red, orange, yellow, green, blue, purple, pink, and gray.

Values on tasks

• Use list-tasks with includeFields to read per-task custom values and update-task with fieldValues to set or clear them; empty values clear the stored row.

Task-card visibility

• Use list-visible-task-fields and update-visible-task-fields to read or change which fields appear on task cards (max 3, persisted per user in SQL).

What view-screen returns

• On /tasks, view-screen includes visibleTaskFields from stored prefs for the custom fields currently shown on task cards and selectedTaskFields for a highlighted task.
• On /fields, view-screen returns the field-definition list and selectedItem when a field is highlighted.
• navigation.fieldId highlights a custom field when the Fields page is opened from a deep link.

Related Skills

• task-inbox-workflow — reading visible task context before editing.
• store-conventions — how custom field value writes are shaped in the store.