v0.39.0 / Field Notes / workflow highlights

What's new
in v0.39.0.

Preserve extra task metadata, filter and display custom properties, and give child tasks a reading order. In the terminal board, search tags, follow parent chains and focus one hierarchy level.

5 October 2026Optional features · existing defaults stay the same

Commands are independent examples. Substitute your board's task IDs.

Available in v0.39.0

This page covers the new workflow features. See the full release notes and downloads for all changes in this release.

01 / Task metadata

Use your own task properties

Add information that matters to your workflow without adding a new built-in task field.

Task edits now preserve extra frontmatter, including metadata written by other tools. New property flags let you set, remove, filter and display supported values. Here, type and reading_order are names chosen for the example board, not reserved kanban-md concepts.

# Set properties on an existing task
kanban-md edit 3 --set-property type=story --set-property reading_order=20

# Filter by a property and display another
kanban-md list --property type=story --show-property reading_order

# Remove a stored property
kanban-md edit 3 --clear-property reading_order

create also accepts --set-property. Repeat flags for different keys. Multiple --property filters must all match and combine with existing filters such as --status.

Values have types

Properties support . reading_order=15 stores a number; 'reading_order="15"' stores text. A stored null is different from a missing property. Equality filters respect these distinctions.

Technical details: values, keys and preservation

Scalar values: Strings, finite numbers, booleans and null. Lists, maps, aliases and other unsupported YAML values remain preserved in task files but cannot be selected by these property flags.

Keys are case-sensitive. Start with a letter or underscore, then use letters, digits, underscores, dots or hyphens. A dot names a literal top-level key, not a nested path. Built-in fields stay reserved.

Values accept bare strings, JSON-quoted strings, decimal or scientific numbers, and lowercase true, false or null. Use 'note=""' for an empty string. Duplicate or conflicting property flags fail before mutation.

Preservation protects metadata values, not comments, formatting or identical file bytes. Unsafe YAML references or field-ownership conflicts make an edit refuse instead of silently deleting metadata. Batch edits keep the existing per-task behavior, not an all-or-nothing transaction.

02 / Display and grouping

Put useful properties in your views

Choose card badges and compact fields. Group CLI counts by a property, with your preferred group order.

Add these settings to kanban/config.yml, keeping your existing settings. A tells a view which extra field to read.

group_orders:
  property:type: [milestone, epic, story, bug]
display:
  compact_fields: [status, property:type]
tui:
  card_fields: [property:type]

Terminal board showing configured type badges for milestone, epic, story and bug, plus a missing type indicator. — **Categories on cards.** `tui.card_fields` replaces the default priority badge with your chosen field. Use `[priority, property:type]` to show both. Restart the TUI after changing its configuration.

Original-size property badge screenshot. — **Categories on cards.** `tui.card_fields` replaces the default priority badge with your chosen field. Use `[priority, property:type]` to show both. Restart the TUI after changing its configuration.

kanban-md list --compact
kanban-md board --group-by property:type

CLI property grouping with milestone, epic, story and bug counts in configured order and unclassified tasks last. — **Your group order, not a fixed taxonomy.** The example puts milestones and epics first. Other values still appear; tasks without a supported value fall into `(unclassified)`. TUI columns remain status-based.

Original-size property group screenshot. — **Your group order, not a fixed taxonomy.** The example puts milestones and epics first. Other values still appear; tasks without a supported value fall into `(unclassified)`. TUI columns remain status-based.

Technical details: display choices and group order

Property selector: property:KEY selects a literal top-level property. For example, property:type reads type. It is not a query or nested path.

Card and compact field lists accept one or two distinct entries from status, priority, class and property:KEY. Compact fields affect list, show and pick, not every command confirmation.

Grouping on list or board produces counts. Configured values that exist come first. Other strings follow alphabetically, then numbers in numeric order, booleans and null. Missing and unsupported values come last. Group preferences neither restrict values nor create absent groups.

Badges distinguish missing KEY=--, unsupported KEY=? and present KEY=null. TUI refresh reloads tasks, not configuration. Property editing, filtering and grouping are CLI operations.

03 / Detail views

Give child tasks a reading order

Use a numeric property to order a parent's direct children in CLI and TUI details.

# In kanban/config.yml
children:
  detail_sort: property:reading_order

Set values such as 10, 20 and 30, leaving gaps for later inserts. In the example, changing task 5's value to 5 puts it first under parent task 2.

kanban-md edit 5 --set-property reading_order=5
kanban-md show 2 --show-property type --show-property reading_order

CLI edit setting task 5 reading_order to 5, followed by parent details with children ordered 5, 4, 3, 6, 7. — **The next step comes first.** Numeric values produce the order `5, 4, 3`. Task 6 has no order; task 7 has text `"15"`. Both follow the numeric children.

Original-size CLI child-order screenshot. — **The next step comes first.** Numeric values produce the order `5, 4, 3`. Task 6 has no order; task 7 has text `"15"`. Both follow the numeric children.

Parent task TUI details with children in the same order, 5, 4, 3, 6, 7, and selected property values. — **The same order in the TUI.** Child rows and keyboard navigation follow the configured order. The selected property values explain each child's position.

Original-size TUI child-order screenshot. — **The same order in the TUI.** Child rows and keyboard navigation follow the configured order. The selected property values explain each child's position.

Technical details: scope, ties and reset

This changes only direct-child rows in detailed show table/JSON output and the TUI. It does not change priority, board-card order, list order or pick selection.

Finite numbers sort ascending, including negative, zero and fractional values. Equal numbers use task ID as a tie-breaker. Missing, unsupported and nonnumeric values follow in ID order. Numbers remain exact within kanban-md.

Remove children.detail_sort or set it to id to restore ID order. Stored values remain until you use --clear-property. Changing or clearing a parent also retains its properties.

04 / TUI search

Find cards by their tags

The board's / search now matches tags as well as titles.

Search for release-notes to keep the tasks carrying that tag, even when their titles do not contain those words.

Terminal board filtered by release-notes, showing the tagged First-use checklist and Publish quickstart cards. — **`/` → `release-notes` → `Enter`.** Two tagged cards remain. To clear a retained search, press `/` and then `Esc`.

Original-size tag search screenshot. — **`/` → `release-notes` → `Enter`.** Two tagged cards remain. To clear a retained search, press `/` and then `Esc`.

Technical details: search matching

Matching is case-insensitive and checks a substring of the title or each individual tag. It does not search the body, join separate tags or parse property queries. Existing # ID search keeps its behavior.

Esc clears the query while search input is active. In board navigation, Esc quits the TUI.

05 / TUI navigation

Follow parents and children from details

See the full known parent chain, open a related task, then retrace your steps.

Task details with the ancestry path Autumn launch, Smooth onboarding and the current First-use checklist task. — **Context above the description.** The path starts at the oldest known ancestor and ends at the current task. Active ancestors and direct children are keyboard-navigable.

Original-size ancestry screenshot. — **Context above the description.** The path starts at the oldest known ancestor and ends at the current task. Active ancestors and direct children are keyboard-navigable.

Tab and Shift + Tab focus relations; Enter opens the selected task.
Esc or Backspace goes back one detail-history step.
q returns directly to the board. From the board, q quits.

Technical details: filters and incomplete links

Active relatives can open even when a board filter hides their cards. Archived ancestors remain visible as context but cannot open; archived children are hidden. Back navigation skips tasks that disappeared or were archived.

Missing parents, self-links and cycles have explicit markers. Navigation does not rewrite or repair those links.

06 / TUI focus

Show one hierarchy level at a time

Press v on the board to cycle through the levels present in your tasks, then back to all.

Level labels come from parent links. Roots are L0, their children are L1, and grandchildren are L2. A category such as story or bug does not determine the level.

Terminal board filtered to level two, with five grandchildren visible and level[2] in the status line. — **Only level two.** On this board, three presses of `v` reach `level[2]`. The next returns to `level[all]`. Search and level filters work together.

Original-size hierarchy filter screenshot. — **Only level two.** On this board, three presses of `v` reach `level[2]`. The next returns to `level[all]`. Search and level filters work together.

Technical details: derived levels and session state

The filter selects an exact level and lasts only for the TUI session. It saves no depth field and changes no task files. It cycles active-task levels in ascending order, then unknown depth if present, then all.

Archived ancestors still count toward depth. Missing or self-parent links produce an effective L0 with an ancestry warning. Multi-task cycles and chains reaching them have unknown depth, L?.

Compatibility / Defaults

Existing boards keep their defaults

No new properties or view settings are required. The default priority badge, compact status/priority fields and ID-based child order stay the same. Older configurations migrate to version 12 on load without rewriting task files.

Remove an optional view setting to restore its default. Restart the TUI after changing its configuration. Removing a view setting does not erase saved properties.

JSON output: properties are explicitly selected

Default JSON stays unchanged. Use when an integration needs extra fields.

kanban-md show 2 --json --show-property type --show-property reading_order

Explicit property selection: On list and show, --show-property adds a properties object containing only the supported requested values. On show, selection also applies to child records. Display settings do not opt fields into JSON.

Missing keys are omitted; present null values appear as null. Unsupported selected data is omitted with a warning. kanban-md preserves exact numeric values, but downstream JSON readers may round them if they use floating point.

Implementation and screenshot evidence

The screenshots were captured from reviewed source cb84ccd6937d, whose file tree matches the released revision. The README documents the commands and settings. The tag-triggered release workflow passed on Linux, macOS and Windows.

The seven screenshots show the real application in a background terminal, using a 1280 × 800 logical viewport, a 130 × 32 terminal and 16-pixel Menlo text. The surrounding window frame is CSS, not a physical laptop capture. The Autumn launch board is example data.