Custom Tracker Types

Beyond the six built-in types, you can define custom tracker types using YAML configuration files. Custom types get the same kanban board, detail view, and AI integration as built-in types.

Where to Define Custom Types

Create YAML files in your project's .nimbalyst/trackers/ directory. Each file defines one custom tracker type. Nimbalyst loads these definitions when the workspace opens.

Example: Customer Feedback

# .nimbalyst/trackers/customer-feedback.yaml
type: customer-feedback
displayName: Customer Feedback
displayNamePlural: Customer Feedback
icon: feedback
color: "#f59e0b"

modes:
  inline: true
  fullDocument: false

idPrefix: fb
idFormat: ulid

fields:
  - name: title
    type: string
    required: true
  - name: status
    type: select
    default: new
    options:
      - value: new
        label: New
        icon: fiber_new
      - value: reviewing
        label: Reviewing
        icon: psychology
      - value: planned
        label: Planned
        icon: event
      - value: shipped
        label: Shipped
        icon: rocket_launch
      - value: wont-fix
        label: Won't Fix
        icon: block
  - name: source
    type: select
    options:
      - value: support
        label: Support Ticket
      - value: interview
        label: User Interview
      - value: survey
        label: Survey
      - value: social
        label: Social Media
  - name: customerName
    type: string
  - name: priority
    type: select
    options:
      - value: low
        label: Low
      - value: medium
        label: Medium
      - value: high
        label: High
      - value: critical
        label: Critical

roles:
  title: title
  workflowStatus: status
  priority: priority

Field Types Reference

Type	Description	Options
string	Single-line text	minLength, maxLength
text	Multi-line text	--
number	Numeric value	min, max
select	Single choice from options	options array with value, label, icon, color
multiselect	Multiple choices	Same as select
date	Calendar date	--
datetime	Date and time	--
boolean	True/false toggle	--
user	Person reference	--
array	List of values	itemType

Field Properties

Property	Description
name	Field identifier (used in code and YAML)
type	One of the types listed above
required	Must have a value when creating
default	Initial value for new items
displayInline	Show in compact inline view (default: true)
readOnly	Cannot be edited by users

Roles

Roles map your custom fields to standard tracker behaviors:

Role	Purpose
title	Which field is the item's display title
workflowStatus	Which field drives kanban columns
priority	Which field is the priority level
assignee	Which field is the item owner
tags	Which field contains categorization tags
progress	Which field tracks completion percentage
dueDate	Which field is the deadline
startDate	Which field is the start date

Schema Properties

Property	Description	Default
type	Unique identifier for this type	Required
displayName	Singular display name	Required
displayNamePlural	Plural display name	Required
icon	Material Design icon name	Required
color	Hex color for the icon	Required
modes.inline	Show as inline markers in markdown	true
modes.fullDocument	Can be a full markdown document	false
idPrefix	2-3 character prefix for IDs	Required
idFormat	ID generation: ulid, uuid, or sequential	ulid
creatable	Can users create items of this type	true