Kanban Markdown

Manage kanban board features stored as markdown files with YAML frontmatter. Each feature is a .md file; the VS Code kanban-markdown extension renders them as a board.

File Format

Every feature file follows this exact format:

---
id: "my-feature-2026-02-20"
status: "backlog"
priority: "medium"
assignee: null
dueDate: null
created: "2026-02-20T10:00:00.000Z"
modified: "2026-02-20T10:00:00.000Z"
completedAt: null
labels: []
order: "a0"
---

# My Feature

Description and details here.

Serialization rules (must match exactly for the extension to parse correctly):

String fields: always "double-quoted"
Nullable fields (assignee, dueDate, completedAt): bare null when unset
Labels: inline array ["bug", "ui"] or []
Order: "double-quoted" string — fractional index for lexicographic sorting (see below)
Field order: id, status, priority, assignee, dueDate, created, modified, completedAt, labels, order

Valid values:

status: backlog | todo | in-progress | review | done
priority: critical | high | medium | low

For full field specs, see references/data-model.md.

Features Directory

Default: .devtool/features/ relative to workspace root. Configurable via VS Code setting kanban-markdown.featuresDirectory.

Active features (backlog, todo, in-progress, review): {featuresDir}/{id}.md
Completed features (done): {featuresDir}/done/{id}.md

Fractional Index Ordering

The order field uses fractional indexing — lexicographically sortable strings that allow inserting between any two items without reindexing. The extension uses the fractional-indexing npm package internally.

When creating features, determine the order by reading existing features in the target column (sorted by order):

If the column is empty: use "a0"
To append after the last item: increment the trailing character — "a0" → "a1", "a1" → "a2", ..., "a9" → "aA", etc.
The full character sequence is 0-9, A-Z, a-z (base-62, ASCII order)

When moving features via drag-and-drop, the extension computes fractional keys between neighbors automatically. The skill only needs to handle appending new features to the end of a column.

Creating Features

Generate ID: lowercase title, keep only a-z 0-9 - space, replace spaces with -, collapse multiple -, trim - from ends, truncate to 50 chars, append -YYYY-MM-DD. If empty, use feature-YYYY-MM-DD.
Set created and modified to current ISO timestamp. Set order by reading existing features in the target column and generating a key that sorts after the last one (see Fractional Index Ordering above).
If status is done, set completedAt to now and place in done/ subfolder.
Write frontmatter in exact field order above, then # Title and body.

Updating Features

Always update modified to current ISO timestamp
Never change id or created
Preserve exact serialization format

Moving Features

Update status and modified. When crossing the done boundary:

To done: set completedAt to current ISO timestamp, move file to done/ subfolder
From done: set completedAt to null, move file back to root

Writing Content

Start with # Title (the extension extracts the display title from the first # heading). Use acceptance criteria checklists, notes, etc. as needed.